ALTER ICEBERG TABLE¶

Sintaxe¶

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> UNSET REPLACE_INVALID_CHARACTERS

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

Onde:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }

Copy

dataGovnPolicyTagAction ::=
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ROW ACCESS POLICY <policy_name>
    | DROP ROW ACCESS POLICY <policy_name> ,
        ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }
  |
  {
      SET AGGREGATION POLICY <policy_name> [ FORCE ]
      | UNSET AGGREGATION POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET PROJECTION POLICY <policy_name>
          [ FORCE ]
      | UNSET PROJECTION POLICY
  }
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> SET TAG
      <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
      , [ COLUMN ] <col2_name> SET TAG
          <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                  , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]

Copy

Parâmetros¶

table_name

Identificador da tabela a ser modificada.

Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais informações, consulte Requisitos para identificadores.

SET ...

Especifica uma ou mais propriedades/parâmetros a serem definidos para a tabela externa (separados por espaços em branco, vírgulas ou novas linhas):

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

Especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (�) nos resultados da consulta. Você só pode definir esse parâmetro para tabelas que usam um catálogo Iceberg externo.

• TRUE substitui os caracteres UTF-8 inválidos pelo caractere de substituição Unicode.

• FALSE deixa caracteres UTF-8 inválidos inalterados. O Snowflake retorna uma mensagem de erro do usuário quando encontra caracteres UTF-8 inválidos em um arquivo de dados Parquet.

Se não for especificado, a tabela Iceberg assumirá o valor do parâmetro para o esquema, banco de dados ou conta. O esquema tem precedência sobre o banco de dados e o banco de dados tem precedência sobre a conta.

Padrão: FALSE

CATALOG_SYNC = 'snowflake_open_catalog_integration_name'

Especifica o nome de uma integração de catálogo configurada para o Snowflake Open Catalog. O Snowflake sincroniza a tabela com um catálogo externo em sua conta Snowflake Open Catalog. Para obter mais informações, consulte Sincronizar uma tabela gerenciada pelo Snowflake com Snowflake Open Catalog.

DATA_RETENTION_TIME_IN_DAYS = integer

Especifica o período de retenção para uma tabela gerenciada pelo Snowflake para que ações de Time Travel (SELECT, CLONE e UNDROP) possam ser executadas em dados históricos na tabela. Para obter mais informações, consulte Compreensão e uso do Time Travel.

Para uma descrição detalhada deste parâmetro de nível de objeto, bem como mais informações sobre parâmetros de objeto, consulte Parâmetros.

Valores:

• Standard Edition: 0 ou 1

• Enterprise Edition: 0 a 90 para tabelas permanentes

Padrão:

• Standard Edition: 1

• Enterprise Edition (ou superior): 1 (a menos que um valor padrão diferente tenha sido especificado no esquema, banco de dados ou nível de conta)

Nota

Um valor de 0 desabilita efetivamente o Time Travel para a tabela.

AUTO_REFRESH = { TRUE | FALSE }

Especifica se o Snowflake deve pesquisar automaticamente o catálogo Iceberg externo associado à tabela para atualizações de metadados ao usar a atualização automatizada. Se nenhum valor for especificado para o parâmetro REFRESH_INTERVAL_SECONDS na integração do catálogo, o Snowflake usará um intervalo de atualização padrão de 30 segundos.

Padrão: FALSE

Recurso em versão preliminar

Disponível para todas as contas.

UNSET

Atualmente, você só pode remover a definição do seguinte parâmetro com este comando:

• REPLACE_INVALID_CHARACTERS

Ações de clustering (clusteringAction)¶

CLUSTER BY ( expr [ , expr , ... ] )

Especifica (ou modifica) uma ou mais colunas de tabela ou expressões de coluna como a chave de clustering da tabela. Essas são as colunas/expressões para as quais o clustering é mantido por Clustering automático.

Para saber mais sobre clustering, consulte Chaves de clustering e tabelas clusterizadas.

SUSPEND | RESUME RECLUSTER

Habilita ou desabilita Clustering automático para a tabela.

DROP CLUSTERING KEY

Descarta a chave de clustering para a tabela.

Para obter mais informações sobre chaves de clustering e reclustering, consulte Explicação das estruturas de tabela do Snowflake.

Política de governança de dados e ações de tag (dataGovnPolicyTagAction)¶

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

Especifica o nome da tag e o valor da cadeia de caracteres dela.

O valor de tag é sempre uma cadeia de caracteres, e o número máximo de caracteres do valor da tag é 256.

Para obter informações sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

policy_name

Identificador da política; deve ser único para seu esquema.

As cláusulas a seguir se aplicam a todos os tipos de tabelas que suportam políticas de acesso a linhas, como, entre outras, tabelas, exibições e tabelas de eventos. Para simplificar, as cláusulas referem-se apenas a “tabela”.

ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])

Adiciona um política de acesso a linhas à tabela.

Pelo menos um nome de coluna deve ser especificado. Colunas adicionais podem ser especificadas com uma vírgula que separa cada nome de coluna. Use esta expressão para adicionar uma política de acesso a linhas tanto a uma tabela de eventos como a uma tabela externa.

DROP ROW ACCESS POLICY policy_name

Descarta uma política de acesso a linhas da tabela.

Use esta cláusula para descartar a política da tabela.

DROP ROW ACCESS POLICY policy_name, ADD ROW ACCESS POLICY policy_name ON ( col_name [ , ... ] )

Descarta a política de acesso a linhas definida na tabela e adiciona uma política de acesso a linhas à mesma tabela em uma única instrução SQL.

DROP ALL ROW ACCESS POLICIES

Descarta todas as associações de política de acesso a linhas de uma tabela.

Esta expressão é útil quando uma política de acesso a linhas é descartada de um esquema antes de descartar a política de uma tabela de eventos. Use esta expressão para descartar as associações de política de acesso a linhas da tabela.

SET AGGREGATION POLICY policy_name

[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]

Atribui uma política de agregação à tabela.

Use o parâmetro opcional ENTITY KEY para definir quais colunas identificam exclusivamente uma entidade dentro da tabela. Para obter mais informações, consulte Implementação de privacidade ao nível de entidade com políticas de agregação.

Use o parâmetro opcional FORCE para substituir atomicamente uma política de agregação existente pela nova política de agregação.

UNSET AGGREGATION POLICY

Desanexa uma política de agregação da tabela.

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

Especifica os argumentos para passar para a expressão SQL da política de mascaramento condicional.

A primeira coluna da lista especifica a coluna das condições da política para mascarar ou tokenizar os dados e deve corresponder à coluna para a qual a política de mascaramento é definida.

As colunas adicionais especificam as colunas a serem avaliadas para determinar se os dados em cada linha do resultado da consulta devem ser mascarados ou tokenizados quando uma consulta é feita na primeira coluna.

Se a cláusula USING for omitida, o Snowflake tratará a política de mascaramento condicional como uma política de mascaramento normal.

FORCE

Substitui uma política de mascaramento ou projeção que está atualmente definida em uma coluna por uma política diferente em uma única instrução.

Observe que a utilização da palavra-chave FORCE com uma política de mascaramento exige o tipo de dados da política na instrução ALTER TABLE (isto é, STRING) para corresponder ao tipo de dados da política de mascaramento atualmente definida na coluna (isto é, STRING).

Se uma política de mascaramento não estiver definida atualmente na coluna, a especificação dessa palavra-chave não tem efeito.

Para obter mais detalhes, consulte: Substituição de uma política de mascaramento em uma coluna ou Substituir uma política de projeção.

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

• Somente o proprietário da tabela (ou seja, a função com o privilégio OWNERSHIP na tabela) ou superior pode executar este comando.

• O clustering só é suportado para tabelas que usam Snowflake como catálogo Iceberg Para adicionar clustering a uma tabela Iceberg, você também deve ter privilégios USAGE ou OWNERSHIP para o esquema e o banco de dados que contém a tabela.

• É possível usar funções de métricas de dados com tabelas Iceberg executando um comando ALTER TABLE. Para obter mais informações, consulte Como trabalhar com funções de métricas de dados.

• Em relação aos metadados:

  Atenção

  Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

• Para solucionar problemas com a alteração do parâmetro CATALOG_SYNC, consulte Você não pode alterar uma tabela Iceberg ao especificar o parâmetro CATALOG_SYNC

Exemplos¶

O exemplo a seguir define uma tag (my_tag) com um valor de customer em uma tabela Iceberg.

ALTER ICEBERG TABLE my_iceberg_table SET TAG my_tag = 'customer';