Suporte de gravação para tabelas Apache Iceberg™ gerenciadas externamente¶

Considerações¶

Considere o seguinte ao usar o suporte de gravação para tabelas Iceberg gerenciadas externamente:

• O Snowflake fornece comandos de Linguagem de Definição de Dados (DDL) e Linguagem de Manipulação de Dados (DML) para tabelas gerenciadas externamente. No entanto, você configura retenção de dados e metadados usando seu catálogo externo e as ferramentas fornecidas pelo seu provedor de armazenamento externo. Para obter mais informações, consulte Tabelas que usam um catálogo externo.

  Para gravações, o Snowflake garante que as alterações sejam confirmadas no seu catálogo remoto antes de atualizar a tabela no Snowflake.

• Se você usar um banco de dados vinculado a catálogo, poderá usar a sintaxe CREATE ICEBERG TABLE com definições de coluna para criar uma tabela no Snowflake e no seu catálogo remoto. Se você usar um banco de dados Snowflake padrão (não vinculado a catálogo), deverá primeiro criar uma tabela no seu catálogo remoto. Depois disso, você poderá usar a sintaxe CREATE ICEBERG TABLE (catálogo REST Iceberg) para criar uma tabela Iceberg no Snowflake e gravar nela.

• Para o catálogo de dados do AWS Glue: Remover uma tabela gerenciada externamente por meio do Snowflake não exclui os arquivos da tabela subjacente. Esse comportamento é específico da implementação do catálogo de dados do AWS Glue.

• Se você tiver participado da versão preliminar privada deste recurso, as exclusões em nível de linha de posição poderão estar ativadas por padrão na sua conta. Para verificar, execute o seguinte comando:

  SHOW PARAMETERS LIKE 'ENABLE_ICEBERG_MERGE_ON_READ' IN ACCOUNT;
  

  Copy

  Se o parâmetro estiver visível na sua conta (independentemente do valor), as exclusões de posição estarão ativadas. Para desativar as exclusões de posição, defina o parâmetro ENABLE_ICEBERG_MERGE_ON_READ como FALSE no nível da tabela, do esquema ou do banco de dados.

• Não há suporte para gravação em tabelas gerenciadas externamente com os seguintes tipos de dados Iceberg:

  • uuid

  • fixed(L)

• Os seguintes recursos não são aceitos atualmente quando você usa o Snowflake para gravar em tabelas Iceberg gerenciadas externamente:

  • Credenciais fornecidas pelo catálogo.

  • Criptografia do lado do servidor (SSE) para volumes externos GCS ou do Azure.

  • Transações com várias instruções. O Snowflake oferece suporte apenas a transações de confirmação automática.

  • Conversão em tabelas gerenciadas pelo Snowflake.

  • Catálogos Iceberg externos que não estão em conformidade com o protocolo Iceberg REST.

  • Exclusões em nível de linha (mesclagem na leitura).

  • Uso da opção OR REPLACE ao criar uma tabela.

  • Uso da sintaxe CREATE TABLE … AS SELECT se você usar o AWS Glue como seu catálogo remoto.

• Para criar esquemas em um banco de dados vinculado a catálogo, esteja ciente do seguinte:

  • O comando CREATE SCHEMA cria um namespace correspondente no seu catálogo remoto somente quando você usa um banco de dados vinculado a catálogo.

  • As opções ALTER e CLONE não são aceitas.

  • Delimitadores não são aceitos para nomes de esquema. Somente nomes de esquema alfanuméricos são aceitos.

• Você pode definir um tamanho de arquivo de destino para os arquivos Parquet de uma tabela. Para obter mais informações, consulte Definir um tamanho de arquivo de destino.

Fluxo de trabalho¶

Use o fluxo de trabalho desta seção para começar a usar este recurso:

1. Configurar um volume externo

2. Criar uma integração de catálogo

3. Escolha entre as seguintes opções:

   • Criar um banco de dados vinculado a catálogo. Com essa opção, você pode gravar em tabelas Iceberg descobertas automaticamente no seu catálogo ou usar o banco de dados vinculado a catálogo para criar tabelas Iceberg adicionais.

   • Criar uma tabela Iceberg (em um banco de dados vinculado a catálogo ou em um banco de dados Snowflake padrão). Com essa opção, você deve primeiro criar uma tabela no seu catálogo remoto antes de criar uma tabela Iceberg gerenciada externamente no Snowflake.

Após concluir essas etapas, você poderá executar operações de gravação em suas tabelas Iceberg.

Configuração de um volume externo para gravações em tabelas gerenciadas externamente¶

Para ativar gravações em tabelas gerenciadas externamente, você deve usar um volume externo configurado com permissões de leitura e gravação para a entidade de serviço do Snowflake (as mesmas permissões necessárias para tabelas gerenciadas pelo Snowflake).

Especifique o local de armazenamento (STORAGE_BASE_URL) em que seu catálogo Iceberg REST grava dados e metadados do Iceberg.

Por exemplo, a instrução a seguir cria um volume externo para o S3 com criptografia que permite acesso de gravação a um bucket denominado my-iceberg-tables:

CREATE OR REPLACE EXTERNAL VOLUME my_external_volume
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-s3-us-west-2'
        STORAGE_PROVIDER = 'S3'
        STORAGE_BASE_URL = 's3://my-iceberg-tables/'
        STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-write-access-role'
        ENCRYPTION = ( TYPE = 'AWS_SSE_S3' )
      )
    )
  ALLOW_WRITES = TRUE;

Para obter instruções completas, consulte os seguintes tópicos:

• Configurar um volume externo para o Amazon S3

• Configurar um volume externo para o Google Cloud Storage

• Configurar um volume externo para o armazenamento do Azure

Para obter mais informações sobre as permissões necessárias, consulte Concessão de acesso do Snowflake ao seu armazenamento.

Configuração de uma integração de catálogo¶

Para gravar em tabelas Iceberg gerenciadas externamente, você deve configurar uma integração de catálogo para conectar o Snowflake ao seu catálogo remoto.

Seu catálogo remoto deve estar em conformidade com a especificação OpenAPI REST do Apache Iceberg de código aberto, como o Open Catalog ou o catálogo do Iceberg REST do AWS Glue.

Para criar uma integração de catálogo, consulte as instruções nos seguintes tópicos:

• Configure uma integração de catálogo para AWS Glue Iceberg REST. Use as permissões no exemplo de política do IAM de leitura e gravação.

  Nota

  Se você usa atualmente uma integração de catálogo para o AWS Glue, precisa criar uma nova integração de catálogo REST para o ponto de extremidade do Iceberg REST do AWS Glue.

• Configurar uma integração de catálogo para o Snowflake Open Catalog

• Configurar uma integração de catálogo para catálogos Apache Iceberg™ REST

Criar um banco de dados vinculado a catálogo¶

O Snowflake oferece suporte à criação de tabelas graváveis ​​gerenciadas externamente em um banco de dados vinculado a catálogo, que é um banco de dados Snowflake que você sincroniza com um catálogo REST Iceberg externo. Você também pode gravar em tabelas Iceberg que o Snowflake descobre automaticamente no seu catálogo remoto. Para obter mais informações, consulte Usar um banco de dados vinculado a catálogo para tabelas Apache Iceberg™.

O exemplo a seguir usa o comando CREATE DATABASE (vinculado a catálogo) para criar um banco de dados vinculado a catálogo que utiliza um volume externo:

CREATE DATABASE my_catalog_linked_db
  LINKED_CATALOG = (
    CATALOG = 'glue_rest_catalog_int'
  ),
  EXTERNAL_VOLUME = 'my_external_vol';

CREATE SCHEMA 'my_namespace';

DROP SCHEMA 'my_namespace';

Criação de uma tabela Iceberg¶

A criação de uma tabela Iceberg gerenciada externamente na qual você pode gravar a partir do Snowflake varia dependendo do tipo de banco de dados que você usa:

• Se você usa um banco de dados vinculado a catálogo, pode usar o comando CREATE ICEBERG TABLE (banco de dados vinculado a catálogo) para criar uma tabela e registrá-la no seu catálogo remoto. Para obter instruções, consulte Criar uma tabela Iceberg em um banco de dados vinculado a catálogo.

• Se você usa um banco de dados Snowflake padrão (não vinculado a catálogo), primeiro crie uma tabela no seu catálogo remoto. Em seguida, você pode usar a sintaxe CREATE ICEBERG TABLE (catálogo REST Iceberg) para criar uma tabela Iceberg no Snowflake e gravar nela. Para obter instruções, consulte Criar uma tabela Iceberg em um banco de dados Snowflake padrão.

USE DATABASE my_catalog_linked_db;

USE SCHEMA my_namespace;

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name string,
  last_name string,
  amount int,
  create_date date
)
TARGET_FILE_SIZE = '64MB';

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table_name';

Remoção de uma tabela Iceberg¶

Você pode remover simultaneamente uma tabela Iceberg gravável gerenciada externamente do Snowflake e do seu catálogo remoto usando o comando DROP ICEBERG TABLE.

DROP ICEBERG TABLE my_iceberg_table;

O Snowflake remove a tabela e também faz uma chamada para o seu catálogo Iceberg remoto, instruindo-o a remover a tabela e excluir os dados e metadados subjacentes da tabela.

O Snowflake remove a tabela somente após confirmar que ela foi removida com sucesso do catálogo remoto.

Gravação em tabelas Iceberg gerenciadas externamente¶

Você pode usar os seguintes comandos DML para tabelas Iceberg gerenciadas externamente:

• INSERT

  • Exemplo: Inserção de várias linhas usando uma consulta (INSERT INTO … SELECT FROM)

  • Exemplo: INSERT INTO … SELECT FROM (fluxo)

• UPDATE

• DELETE

• MERGE

• TRUNCATE TABLE

• COPY INTO <tabela>. Para obter mais informações, consulte Carregamento dados nas tabelas do Apache Iceberg™.

Você também pode usar a Snowpark API para processar tabelas Iceberg.

INSERT INTO my_iceberg_table VALUES (1, 'a');
INSERT INTO my_iceberg_table VALUES (2, 'b');
INSERT INTO my_iceberg_table VALUES (3, 'c');

UPDATE my_iceberg_table
  SET a = 10
  WHERE b = 'b';

DELETE my_iceberg_table
  WHERE b = 'a';

MERGE INTO my_iceberg_table USING my_snowflake_table
  ON my_iceberg_table.a = my_snowflake_table.a
  WHEN MATCHED THEN
      UPDATE SET my_iceberg_table.b = my_snowflake_table.b
  WHEN NOT MATCHED THEN
      INSERT VALUES (my_snowflake_table.a, my_snowflake_table.b);

COPY INTO customer_iceberg_ingest
  FROM @my_parquet_stage
  FILE_FORMAT = 'my_parquet_format'
  LOAD_MODE = ADD_FILES_COPY
  PURGE = TRUE
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;

CREATE OR REPLACE STREAM my_stream ON TABLE my_snowflake_table;

//...

INSERT INTO my_iceberg_table(id,name)
  SELECT id, name
  FROM my_stream;

def copy_into_iceberg():

  try:
      df = session.table("my_snowflake_table")

      df.write.save_as_table("my_iceberg_table")

  except Exception as e:
      print(f"Error processing {table_name}: {e}")

Solução de problemas¶

Se ocorrer um problema quando o Snowflake tentar confirmar as alterações da tabela no seu catálogo externo, o Snowflake retornará uma das seguintes mensagens de erro.

004185=SQL Execution Error: Failed while committing transaction to external catalog. Error:''{0}''

004185=SQL Execution Error: Failed while committing transaction to external catalog with unresolvable commit conflicts. Error:''{0}''

004500=SQL Execution Error: Cannot verify the status of transaction from external catalog. The statement ''{0}'' with transaction id {1} may or may not have committed to external catalog. Error:''{2}''