ALTER 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> ... ]

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

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:

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¶

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

ALTER ICEBERG TABLE myIcebergTable REFRESH;

ALTER ICEBERG TABLE myTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;