Converter uma tabela Apache Iceberg™ para usar o Snowflake como catálogo¶

Converta uma tabela Apache Iceberg™ que o Snowflake não gerencia em uma tabela que usa o Snowflake como catálogo Iceberg.

Você pode optar por converter uma tabela quando desejar suporte completo à plataforma Snowflake, incluindo suporte para SDK do catálogo Snowflake.

Para saber mais sobre as diferenças entre os tipos de tabela Iceberg, consulte Opções de catálogo.

Antes e depois da conversão da tabela¶

Quando você converte uma tabela Iceberg para usar o Snowflake como catálogo, a tabela se torna gravável e o Snowflake assume o gerenciamento do ciclo de vida dela.

A tabela a seguir compara as tabelas Iceberg antes e depois da conversão:

	Antes da conversão	Depois da conversão
Catálogo Iceberg	Um catálogo externo (como AWS Glue) ou nenhum catálogo. Exige uma integração de catálogo.	Snowflake. Snowflake registra alterações nos dados de origem e registra as alterações no catálogo Snowflake. O Snowflake então atualiza os metadados da tabela no seu volume externo. Não exige integração de catálogo.
Operações de leitura do Snowflake	✔	✔
Operações de gravação do Snowflake	❌	✔
Local de armazenamento para dados e metadados da tabela	Volume externo (armazenamento externo em nuvem).	Volume externo (armazenamento em nuvem externo) em um local base especificado.
Limpeza de dados e metadados	Gerenciado por você ou por seu catálogo externo.	Gerenciado pelo Snowflake. O Snowflake nunca exclui metadados, listas de manifestos ou manifestos criados antes da conversão do seu armazenamento externo. O Snowflake não reescreve nenhum arquivo de dados Parquet durante a conversão. Depois de converter uma tabela, o Snowflake pode reescrever alguns dos arquivos de dados como parte da manutenção regular da tabela.
Acessível no Snowflake Catalog SDK	❌	✔

Importante

Quando você converte uma tabela Iceberg, o Snowflake não bloqueia nem assume acesso exclusivo ao seu armazenamento externo. Para evitar corrupção de tabela, monitore ou interrompa qualquer gravação que não seja do Snowflake (como trabalhos de manutenção automatizados) em seu local de armazenamento externo.

Requisitos¶

Antes de converter uma tabela Iceberg, certifique-se de que o Snowflake possa gravar em seu volume externo.

Para que o Snowflake grave em seu volume externo, as seguintes condições devem ser atendidas:

Use o comando ALTER ICEBERG TABLE … REFRESH para atualizar manualmente a tabela antes de convertê-la.

A propriedade ALLOW_WRITES do seu volume externo está definida como TRUE. Para atualizar o valor desta propriedade para um volume externo existente, use o comando ALTER EXTERNAL VOLUME. Por exemplo: ALTER EXTERNAL VOLUME my_ext_vol SET ALLOW_WRITES=TRUE.

As permissões de controle de acesso definidas na conta de armazenamento em nuvem devem permitir acesso de gravação. Por exemplo, se você usar um volume externo configurado para Amazon S3, sua função IAM deverá ter a permissão s3:PutObject para seu local S3.

Nota

Não há suporte para a conversão de uma tabela que tenha uma coluna de partição de identidade não materializada. Uma coluna de partição de identidade não materializada é criada quando uma tabela define uma transformação de identidade usando uma coluna de origem que não existe em um arquivo Parquet.

Exemplo: converter uma tabela¶

Importante

Este exemplo começa criando uma tabela Iceberg a partir de arquivos Iceberg no armazenamento de objetos. Snowflake usa o valor METADATA_FILE_PATH para procurar os metadados da tabela no seguinte local para definições de coluna: <ext-vol-storage-base-url>/path/to/metadata/v1.metadata.json.

CREATE ICEBERG TABLE myIcebergTable
  EXTERNAL_VOLUME='icebergMetadataVolume'
  CATALOG='icebergCatalogInt'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';

Copy

Em seguida, use o comando ALTER ICEBERG TABLE … REFRESH para sincronizar os metadados da tabela com o arquivo de metadados mais recente. O comando de exemplo a seguir atualiza a tabela especificando um caminho de arquivo de metadados.

ALTER ICEBERG TABLE myIcebergTable REFRESH 'metadata/v2.metadata.json';

Copy

Por fim, converta a tabela para usar o Snowflake como o catálogo Iceberg usando o comando ALTER ICEBERG TABLE … CONVERT TO MANAGED.

ALTER ICEBERG TABLE myIcebergTable CONVERT TO MANAGED
  BASE_LOCATION = 'my/relative/path/from/external_volume';

Copy

Nota

Neste exemplo, a instrução ALTER deve especificar um BASE_LOCATION porque a tabela foi criada a partir de arquivos Iceberg no armazenamento de objetos e BASE_LOCATION não fazia parte da instrução CREATE ICEBERG TABLE original. O BASE_LOCATION define o caminho relativo do seu volume externo para um diretório onde o Snowflake grava dados e metadados da tabela convertida.

Caso contrário, se BASE_LOCATION foi especificado na instrução CREATE ICEBERG TABLE original, não será necessário incluí-lo no comando ALTER ICEBERG TABLE … CONVERT TO MANAGED.

Por exemplo, o Snowflake grava dados da tabela em <ext-vol-storage-base-url>/myBaseLocation/data/.

Snowflake grava metadados da tabela convertida em <ext-vol-storage-base-url>/myBaseLocation/metadata/.

Conversão e tipos de dados¶

Nota

Não é possível converter uma tabela que usa os seguintes tipos de dados Iceberg:

uuid
fixed(L)

O Snowflake usa tipos de dados Snowflake para processar e retornar valores, mas grava os tipos Iceberg originais em arquivos de dados de tabela.

Para tipos de dados como int e long, o tipo de dados Snowflake oferece suporte a um intervalo maior de valores do que o tipo de dados Iceberg. Para permanecer consistente com o tipo de dados de origem, o Snowflake não permite a inserção de valores fora do intervalo compatível com o tipo de dados de origem. Para obter mais informações, consulte Tipos aproximados.