ALTER ICEBERG TABLE

Modifica as propriedades, colunas ou restrições de uma tabela Iceberg existente. Quando uma tabela Iceberg usa uma integração de catálogo, use ALTER ICEBERG TABLE para atualizar a tabela com novos dados.

Você também pode usar ALTER ICEBERG TABLE para converter uma tabela que usa uma integração de catálogo em uma tabela que usa Snowflake como catálogo Iceberg. Para obter mais informações, consulte Conversão de uma tabela Iceberg.

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> REFRESH [ '<metadata_file_relative_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> CONVERT TO MANAGED [ BASE_LOCATION = '<file_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER ICEBERG TABLE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]
Copy

Onde:

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

Parâmetros

name

Identificador da tabela Iceberg a ser alterada. 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.

REFRESH [ 'metadata_file_relative_path' ]

Acessa um arquivo de metadados no caminho especificado (em relação ao local de armazenamento do volume externo da tabela) para uma tabela Iceberg que não é gerenciada pelo Snowflake e atualiza os metadados da tabela.

Use esta opção somente se sua tabela Iceberg usar arquivos Iceberg no armazenamento de objetos como origem. Omita esta opção se você usar AWS Glue como seu catálogo Iceberg.

Por exemplo, se s3://mybucket_us_east_1/metadata/v1.metadata.json for o caminho completo para seu arquivo de metadados e o local de armazenamento do volume externo associado à tabela for s3://mybucket_us_east_1, especifique metadata/v1.metadata.json como metadata_file_relative_path.

Nota

Antes da versão 7.34 do Snowflake, um parâmetro denominado BASE_LOCATION (também conhecido como FILE_PATH nas versões anteriores) era necessário para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos. O parâmetro especificou um caminho relativo do local EXTERNAL_VOLUME.

Para atualizar uma tabela criada usando a sintaxe antiga, especifique um caminho relativo ao BASE_LOCATION. Por exemplo, se o caminho completo para o arquivo de metadados for s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json, especifique metadata/v1.metadata.json como metadata-file-relative-path.

CONVERT TO MANAGED

Converte uma tabela Iceberg somente leitura que usa uma integração de catálogo em uma tabela que usa Snowflake como catálogo Iceberg. A tabela convertida oferece suporte a operações de leitura e gravação, e o Snowflake cuida de toda a manutenção do ciclo de vida, como compactação, da tabela. Para obter mais informações, consulte Conversão de uma tabela Iceberg.

[ BASE_LOCATION = 'file_path' ]

Especifica um caminho relativo para um diretório do local EXTERNAL_VOLUME da tabela onde o Snowflake pode gravar dados e metadados da tabela. Você deverá especificar um valor para essa propriedade durante a conversão se a instrução CREATE ICEBERG TABLE original não permitisse ou incluísse um BASE_LOCATION.

O valor deste parâmetro não pode ser alterado após a conversão de uma tabela.

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):

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.

UNSET

Atualmente, você só pode desabilitar o seguinte com este comando:

  • TAG tag_name [ , tag_name ... ]

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.

Requisitos de controle de acesso

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

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

Obrigatório para atualizar manualmente os metadados da tabela.

USAGE

Formato do arquivo

Obrigatório para atualizar manualmente os metadados da tabela.

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.

  • O uso do comando ALTER ICEBERG TABLE … REFRESH em transações (implícitas ou explícitas) não é suportado.

  • Antes da versão 7.34 do Snowflake, um parâmetro denominado BASE_LOCATION (também conhecido como FILE_PATH nas versões anteriores) era necessário para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos. O parâmetro especificou um caminho relativo do local EXTERNAL_VOLUME.

    Para atualizar uma tabela criada usando a sintaxe antiga, especifique um caminho relativo ao BASE_LOCATION. Por exemplo, se o caminho completo para o arquivo de metadados for s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json, especifique metadata/v1.metadata.json como metadata-file-relative-path.

  • 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.

Exemplos

Atualização manual de metadados da tabela que usam uma integração de catálogo

Arquivos Iceberg no armazenamento de objetos

Este exemplo atualiza manualmente os metadados da tabela com base nas alterações em um novo arquivo de metadados. Neste exemplo, o caminho completo para o arquivo de metadados é <external-volume-storage-base-url>/path/to/metadata/v2.metadata.json.

Nota

Antes da versão 7.34 do Snowflake, um parâmetro denominado BASE_LOCATION (também conhecido como FILE_PATH nas versões anteriores) era necessário para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos. O parâmetro especificou um caminho relativo do local EXTERNAL_VOLUME.

Para atualizar uma tabela criada usando a sintaxe antiga, especifique um caminho relativo ao BASE_LOCATION. Por exemplo, se o caminho completo para o arquivo de metadados for s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json, especifique metadata/v1.metadata.json como metadata-file-relative-path.

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'path/to/metadata/v2.metadata.json';
Copy

AWS Glue

Este exemplo atualiza manualmente os metadados de uma tabela que usa AWS Glue para o catálogo Iceberg. Ao usar AWS Glue como catálogo Iceberg, você não especifica um caminho de arquivo de metadados no comando de atualização.

ALTER ICEBERG TABLE myIcebergTable REFRESH;
Copy

Conversão de uma tabela Iceberg

O exemplo a seguir usa a instrução ALTER ICEBERG TABLE … CONVERT TO MANAGED para converter uma tabela que não é gerenciada pelo Snowflake em uma tabela que usa o Snowflake como catálogo Iceberg.

ALTER ICEBERG TABLE myTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;
Copy