ALTER ICEBERG TABLE

Modifica propriedades como opções de clustering e tags para uma tabela Apache Iceberg™ existente.

Você também pode usar uma instrução ALTER ICEBERG TABLE para atualizar uma tabela, converter uma tabela ou alterar uma coluna de tipo estruturado. A sintaxe para essas operações varia consideravelmente. Para visualizar a sintaxe, descrições de parâmetros, notas de uso e exemplos para atualizar ou converter uma tabela Iceberg, consulte as seguintes páginas:

Este tópico refere-se às tabelas Iceberg simplesmente como “tabelas”, exceto onde a especificação de tabelas Iceberg evita confusão.

Consulte também:

CREATE ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE

Sintaxe

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> { clusteringAction | tableColumnAction }

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

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

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> searchOptimizationAction
Copy

Onde:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }
Copy
tableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
        [ inlineConstraint ]
        [ COLLATE '<collation_specification>' ]

   | RENAME COLUMN <col_name> TO <new_col_name>

   | ALTER | MODIFY [ ( ]
                          , [ COLUMN ] <col1_name> { [ SET ] NOT NULL | DROP NOT NULL }
                          , [ COLUMN ] <col1_name> [ [ SET DATA ] TYPE ] <type>
                          , [ COLUMN ] <col1_name> COMMENT '<string>'
                          , [ COLUMN ] <col1_name> UNSET COMMENT
                        [ , [ COLUMN ] <col2_name> ... ]
                        [ , ... ]
                    [ ) ]

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }

  inlineConstraint ::=
    [ NOT NULL ]
    [ CONSTRAINT <constraint_name> ]
    { UNIQUE | PRIMARY KEY | { [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ] } }
    [ <constraint_properties> ]
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>
        [ ENTITY KEY ( <col_name> [, ... ] ) ]
        [ FORCE ]
    | UNSET AGGREGATION POLICY
  }
  |
  {
      SET JOIN POLICY <policy_name>
        [ FORCE ]
    | UNSET JOIN POLICY
  }
  |
  ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
    [ [ WITH ] MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] ]
    [ [ WITH ] PROJECTION POLICY <policy_name> ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>'
          [ , <tag_name> = '<tag_value>' , ... ] ) ]
  |
  {
    { 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
searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON <search_method_with_target> [ , <search_method_with_target> ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON { <search_method_with_target> | <column_name> | <expression_id> }
          [ , ... ]
     ]
  }
Copy

Para obter mais detalhes, consulte Ações de otimização de pesquisa (searchOptimizationAction).

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 sobre a sincronização de tabelas Iceberg gerenciadas pelo Snowflake com o Open Catalog, consulte Sincronizar uma tabela gerenciada pelo Snowflake com Snowflake Open Catalog.

Para obter mais informações sobre este parâmetro, consulte CATALOG_SYNC.

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.

Para tabelas baseadas em Delta, o Snowflake consulta seu armazenamento em nuvem externo para obter atualizações.

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

CONTACT ( purpose = contact [ , purpose = contact ... ] )

Associe o objeto existente a um ou mais contatos.

UNSET

Atualmente, você só pode cancelar a configuração dos seguintes parâmetros com esse comando:

  • REPLACE_INVALID_CHARACTERS

  • CATALOG_SYNC

  • CONTACT purpose

Ações de clustering (clusteringAction)

Nota

O clustering só é suportado para tabelas que usam Snowflake como catálogo Iceberg

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.

Ações de coluna da tabela (tableColumnAction)

ADD [ COLUMN ] [ IF NOT EXISTS ] col_name col_data_type . [ inlineConstraint ] [ COLLATE 'collation_specification' ] [ , ... ]

Adiciona uma nova coluna. Você pode especificar uma restrição inline ou uma especificação de agrupamento.

Para obter detalhes adicionais sobre ações de coluna de tabela, consulte:

Você pode realizar operações ADD COLUMN em várias colunas no mesmo comando.

Se não tiver certeza se a coluna já existe, você pode especificar IF NOT EXISTS ao adicionar a coluna. Se a coluna já existir, ADD COLUMN não terá efeito sobre a coluna existente e não resultará em um erro.

Nota

Não é possível especificar IF NOT EXISTS se você também estiver especificando qualquer um dos seguintes itens para a nova coluna:

  • AUTOINCREMENT ou IDENTITY

  • UNIQUE, PRIMARY KEY ou FOREIGN KEY

RENAME COLUMN col_name to new_col_name

Renomeia a coluna especificada para um novo nome que não é usado atualmente para nenhuma outra coluna na tabela.

Você não pode renomear uma coluna que faz parte de uma chave de clustering.

Quando você renomeia um objeto (tabela, coluna etc.), deve atualizar outros objetos que fazem referência a ele com o novo nome.

DROP COLUMN [ IF EXISTS ] col_name [ CASCADE | RESTRICT ]

Remove a coluna especificada da tabela.

Se não tiver certeza de que a coluna já existe, você pode especificar IF EXISTS ao descartar a coluna. Se a coluna não existir, DROP COLUMN não terá efeito e não resultará em erro.

O descarte de uma coluna é uma operação somente de metadados. Ele não reescreve imediatamente as micropartições e, portanto, não libera imediatamente o espaço usado pela coluna. Normalmente, o espaço dentro de uma micropartição individual é liberado na próxima vez em que a micropartição é regravada, o que normalmente ocorre quando uma gravação é feita devido a DML (INSERT, UPDATE, DELETE) ou a reclustering.

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 Cota de tags para objetos.

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.

SET JOIN POLICY policy_name
[ FORCE ]

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

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

UNSET JOIN POLICY

Desvincula uma política de junçã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.

Ações de otimização de pesquisa (searchOptimizationAction)

ADD SEARCH OPTIMIZATION

Adiciona uma otimização de pesquisa para toda a tabela ou, se você especificar a cláusula opcional ON, para colunas específicas.

Nota

A otimização de pesquisa pode ser de cara manutenção, especialmente se os dados na tabela mudam com frequência. Para obter mais informações, consulte Estimativa e gerenciamento de custos de otimização de pesquisa.

ON search_method_with_target [, search_method_with_target ... ]

Especifica que você deseja configurar a otimização de pesquisa para colunas específicas (em vez de toda a tabela).

Para search_method_with_target, use uma expressão com a seguinte sintaxe:

<search_method>( <target> [ , <target> , ... ] [ , ANALYZER => '<analyzer_name>' ] )
Copy

Onde:

  • search_method especifica um dos seguintes métodos que otimiza as consultas para um determinado tipo de predicado:

    Método de pesquisa

    Descrição

    FULL_TEXT

    Predicados que usam os tipos VARCHAR (texto).

    EQUALITY

    Igualdade e predicados IN.

    SUBSTRING

    Predicados que correspondem a subcadeias de caracteres e expressões regulares (por exemplo, [ NOT ] LIKE, [ NOT ] ILIKE, [ NOT ] RLIKE e REGEXP_LIKE).

  • target especifica a coluna ou um asterisco (*).

    Dependendo do valor de search_method, você pode especificar uma coluna de um dos seguintes tipos:

    Método de pesquisa

    Alvos suportados

    FULL_TEXT

    Colunas de tipos de dados VARCHAR (texto).

    EQUALITY

    Colunas de tipos de dados numéricos, de cadeia de caracteres e binários.

    SUBSTRING

    Colunas de tipos de dados VARCHAR (texto).

    Para especificar todas as colunas aplicáveis na tabela como alvos, use um asterisco (*).

    Observe que você não pode especificar um asterisco e nomes de colunas específicos para um determinado método de pesquisa. Entretanto, você pode especificar um asterisco em diferentes métodos de busca.

    Por exemplo, você pode especificar as seguintes expressões:

    -- Allowed
    ON SUBSTRING(*)
    ON EQUALITY(*), SUBSTRING(*)
    
    Copy

    Não é possível especificar as seguintes expressões:

    -- Not allowed
    ON EQUALITY(*, c1)
    ON EQUALITY(c1, *)
    ON EQUALITY(v1:path, *)
    ON EQUALITY(c1), EQUALITY(*)
    
    Copy
  • ANALYZER => 'analyzer_name' especifica o nome do analisador de texto, se search_method for FULL_TEXT.

    Para obter mais informações sobre analisadores de otimização de pesquisa, consulte ALTER TABLE.

Para especificar mais de um método de busca em um alvo, use uma vírgula para separar cada método seguinte do alvo:

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);
Copy

Se você executar o comando ALTER ICEBERG TABLE … ADD SEARCH OPTIMIZATION ON … várias vezes na mesma tabela, cada comando seguinte será adicionado à configuração existente para a tabela. Por exemplo, suponha que você execute os seguintes comandos:

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);
Copy

Isso acrescenta os predicados de igualdade para as colunas c1, c2, c3 e c4 à configuração da tabela. Isso é equivalente a executar o comando:

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);
Copy

Para exemplos, consulte Habilitação da otimização de pesquisa para colunas específicas.

DROP SEARCH OPTIMIZATION

Remove a otimização de pesquisa para toda a tabela ou, se você especificar a cláusula opcional ON, de colunas específicas.

Nota

  • Se uma tabela tiver a propriedade de otimização de pesquisa, descartar a tabela e cancelar o descarte preservará a propriedade de otimização de pesquisa.

  • Remover a propriedade de otimização de pesquisa de uma tabela e voltar a adicioná-la incorre no mesmo custo que adicioná-la pela primeira vez.

ON search_method_with_target | column_name | expression_id [ , ... ]

Especifica que você deseja descartar a configuração de otimização de pesquisa para colunas específicas (em vez de descartar a otimização de pesquisa para a tabela inteira).

Para identificar a configuração da coluna a ser removida, especifique uma das seguintes opções:

  • Para search_method_with_target, especifique um método para otimizar as consultas para uma ou mais colunas específicas. Use a sintaxe descrita anteriormente.

  • Para column_name, especifique o nome da coluna configurada para otimização de pesquisa. A especificação do nome da coluna descarta todas as expressões para essa coluna.

  • Para expression_id, especifique a ID para uma expressão listada na saída do comando DESCRIBE SEARCH OPTIMIZATION.

Para especificar mais de um deles, use uma vírgula entre os itens.

Você pode especificar qualquer combinação de métodos de pesquisa com alvos, nomes de colunas e IDs de expressão.

Para exemplos, consulte Descarte da otimização de pesquisa para colunas específicas.

Requisitos de controle de acesso

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

Privilégio

Objeto

Notas

OWNERSHIP

Tabela Iceberg

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

USAGE

Volume externo

USAGE

Integração de catálogo

Obrigatório se a tabela usar uma integração de catálogo.

O privilégio USAGE no banco de dados e no esquema pai é necessário para executar operações em qualquer objeto de um esquema.

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 usar funções de métricas de dados para realizar verificações de qualidade de dados.

  • Para obter mais informações sobre o uso da otimização de pesquisa com tabelas Iceberg, incluindo limitações, consulte Suporte a tabelas Apache Iceberg™ na documentação de otimização de pesquisa.

  • 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';
Copy

O exemplo a seguir habilita a atualização automatizada para uma tabela existente gerenciada externamente:

ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = TRUE;
Copy

Os exemplos a seguir adicionam e descartam a otimização de pesquisa para uma tabela Iceberg:

ALTER ICEBERG TABLE my_iceberg_table ADD SEARCH OPTIMIZATION ON SUBSTRING(C6);

ALTER ICEBERG TABLE my_iceberg_table DROP SEARCH OPTIMIZATION ON EQUALITY(C7, C8);
Copy