ALTER ICEBERG TABLE … REFRESH

Atualiza os metadados de uma tabela Apache Iceberg™ que usa um catálogo Iceberg externo. A atualização de uma tabela Iceberg sincroniza os metadados da tabela com as alterações mais recentes da tabela.

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>' ]
Copy

Parâmetros

table_name

Identificador da tabela a ser atualizada.

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.

'metadata_file_relative_path'

Especifica um caminho de arquivo de metadados para uma tabela criada a partir de arquivos Iceberg no armazenamento de objeto. O caminho deve ser relativo ao local de armazenamento ativo do volume externo associado à tabela.

A tabela a seguir mostra qual valor especificar com base em um local de armazenamento de exemplo:

Local de armazenamento ativo para o volume externo da tabela

s3://mybucket_us_east_1

Caminho completo para o arquivo de metadados

s3://mybucket_us_east_1/metadata/v1.metadata.json

Valor a ser especificado como 'metadata_file_relative_path'

metadata/v1.metadata.json (sem uma barra inicial)

Nota

  • Se a tabela usar o AWS Glue como catálogo ou for criada a partir de arquivos de tabela Delta, não especifique um caminho de arquivo de metadados.

  • Omita a barra inicial (/) no caminho do arquivo de metadados.

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

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

USAGE

Integração de catálogo

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 uso do comando ALTER ICEBERG TABLE … REFRESH em transações (implícitas ou explícitas) não é suportado.

  • As operações de atualização durante CREATE e ALTER … REFRESH podem processar no máximo 1.000 arquivos de confirmação Delta por operação.

    Nota

    O Snowflake usa arquivos de ponto de verificação Delta ao criar uma tabela Iceberg. O limite de 1.000 arquivo de confirmação se aplica somente a confirmações após o último ponto de verificação.

  • 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 de uma tabela

Este exemplo atualiza manualmente os metadados de uma tabela para os seguintes cenários:

  • A tabela usa o AWS Glue para o catálogo Iceberg.

  • A tabela se baseia em arquivos de tabela Delta no armazenamento de objeto.

Para esses cenários, você não especifica um caminho de arquivo de metadados no comando de atualização.

ALTER ICEBERG TABLE myIcebergTable REFRESH;
Copy

Atualizar uma tabela criada a partir de 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.

Ao especificar um arquivo de metadados, você não inclui uma barra inicial (/) no caminho do arquivo de metadados.

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

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.

Linguagem: Português