Conversão de uma tabela Iceberg¶

Este tópico fornece informações sobre como converter uma tabela Iceberg que não é gerenciada pelo Snowflake 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 Iceberg do Snowflake.

Antes de converter uma tabela Iceberg, recomendamos que você esteja familiarizado com as diferentes opções de catálogo Iceberg suportadas pelo Snowflake. Para saber mais, consulte Opções de catálogo Iceberg.

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.	Snowflake não toca em nenhum dado e arquivo de metadados gerados externamente.
Acessível do SDK do catálogo Iceberg do Snowflake	❌	✔

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 e/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.

Exemplo: conversão de uma tabela Iceberg¶

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 um comando ALTER ICEBERG TABLE … CONVERT TO MANAGED.

ALTER ICEBERG TABLE myIcebergTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;

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¶

Se você converter uma tabela com um tipo de dados Iceberg que o Snowflake não suporta, o Snowflake usará um tipo de dados Snowflake para processar e retornar valores. No entanto, o Snowflake grava o tipo de dados Iceberg original nos arquivos de dados da tabela para que você possa usar a tabela com outros mecanismos de computação, como o Apache Spark.

Para tipos de dados como int e long, o tipo de dados que o Snowflake usa para processamento oferece suporte a um intervalo maior de valores do que o tipo de dados de origem. 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.

Por exemplo, considere uma tabela com uma coluna do tipo Iceberg int. Após a conversão, o Snowflake processa os valores da coluna usando o tipo de dados do Snowflake NUMBER(10,0). NUMBER(10,0) tem um intervalo de (-9.999.999.999, +9.999.999.999), mas int tem um intervalo mais limitado de (-2.147.483.648, +2.147.483.647). Se você tentar inserir um valor de 3.000.000.000 nessa coluna, o Snowflake retornará uma mensagem de erro fora do intervalo.

Para obter mais informações sobre tipos de dados, incluindo limitações, consulte Tipos de dados da tabela Iceberg.