Gerenciar tabelas Apache Iceberg™¶

Exemplo: atualizar uma tabela¶

Você pode usar instruções INSERT e UPDATE para modificar tabelas Iceberg gerenciadas pelo Snowflake.

O exemplo a seguir insere um novo valor em uma tabela Iceberg chamada store_sales e atualiza a coluna cola para 1 se o valor for atualmente -99.

INSERT INTO store_sales VALUES (-99);

UPDATE store_sales
  SET cola = 1
  WHERE cola = -99;

Consultar tabelas¶

O Snowflake oferece suporte à consulta de tabelas Iceberg gerenciadas externamente quando você tiver configurado as exclusões em nível de linha para operações de atualização, exclusão e mesclagem.

Para configurar as exclusões em nível de linha, consulte Propriedades de gravação na documentação do Apache Iceberg.

Gravar em tabelas usando arquivos de exclusão posicional¶

O Snowflake oferece suporte a exclusões em nível de linha de posição para gravação em tabelas Iceberg gerenciadas externamente e armazenadas no Amazon S3, Azure ou Google Cloud. Para desativar as exclusões de posição, que permitem a execução das operações DML no modo de cópia na gravação, defina o parâmetro ENABLE_ICEBERG_MERGE_ON_READ como FALSE no nível da tabela, do esquema ou do banco de dados.

Gravar em tabelas usando vetores de exclusão¶

Para otimizar as modificações de dados em nível de linha, o Snowflake é compatível com vetores de exclusão para gravação em tabelas Iceberg gerenciadas externamente e gerenciadas pelo Snowflake, armazenadas no Amazon S3, Azure ou Google Cloud. Com vetores de exclusão, o Snowflake pode executar operações de «mesclagem na leitura» (merge-on-read, MOR), que melhoram o desempenho de gravação para as seguintes instruções DML:

• DELETE

• UPDATE

• MERGE

O Snowflake atinge esse desempenho gravando pequenos arquivos vetoriais em vez de reescrever grandes arquivos de dados. Para obter mais informações, consulte Vetores de exclusão na especificação do Apache Iceberg.

Cópia na gravação vs. fusão na leitura¶

O Iceberg oferece dois modos para configurar como os mecanismos de computação lidam com operações em nível de linha para tabelas gerenciadas externamente. O Snowflake oferece suporte a esses dois modos.

A tabela a seguir descreve quando você pode querer usar cada modo:

Para obter mais informações sobre alterações em nível de linha no Iceberg, consulte Exclusões em nível de linha na documentação do Apache Iceberg.

Considerações e limitações¶

Considere as seguintes informações ao usar exclusões em nível de linha com tabelas Iceberg:

• O Snowflake é compatível com exclusões de posição apenas para tabelas Iceberg v2 e vetores de exclusão para tabelas Iceberg v3.

• O Snowflake é compatível com exclusões de posição apenas com tabelas Iceberg gerenciadas externamente.

• Para obter o melhor desempenho de leitura ao usar exclusões em nível de linha, execute a compactação regular e a manutenção da tabela para remover arquivos de exclusão antigos. Para obter mais informações, consulte Manter tabelas que usam um catálogo externo.

• Exclusões de posição excessivas, especialmente exclusões de posição pendentes, podem impedir operações de criação e atualização de tabelas. Para evitar esse problema, execute a manutenção da tabela para remover exclusões de posição extras.

  O método de manutenção de tabela a ser usado depende do seu mecanismo Iceberg externo. Por exemplo, você pode usar o método rewrite_data_files para Spark com as opções delete-file-threshold ou rewrite-all. Para obter mais informações, consulte rewrite_data_files na documentação Apache Iceberg™.

Clustering automático¶

O clustering automático reorganiza os dados em arquivos ou partições com base nas colunas consultadas com frequência. O tamanho do arquivo para tabelas Iceberg é baseado na sua configuração de clustering, a menos que você defina um tamanho de arquivo de destino. Se fizer isso, o tamanho do arquivo será o tamanho definido por você. Para obter mais informações, consulte Definir um tamanho de arquivo de destino.

Para definir o Clustering automático, especifique o parâmetro CLUSTER BY ao criar uma tabela Iceberg gerenciada pelo Snowflake ou modificar uma tabela que já existe. Para obter mais informações, consulte:

• CREATE ICEBERG TABLE (Snowflake como o catálogo Iceberg)

• ALTER ICEBERG TABLE

Para mais informações sobre clustering automático, consulte Clustering automático.

Compactação de dados¶

A compactação de dados combina arquivos pequenos em arquivos maiores e mais eficientes. Isso ajuda a gerenciar o armazenamento, manter um tamanho de arquivo ideal e melhorar o desempenho da consulta.

Na maioria dos casos, a compactação de dados não tem um efeito significativo nos custos de computação. No entanto, se isso for uma preocupação, você pode desativar a compactação. Por exemplo, você pode querer desativar a compactação em uma tabela se raramente a consultar. Para desativar ou ativar a compactação de dados, consulte Definir compactação de dados.

Compactação de manifestos¶

A compactação de manifestos otimiza a camada de metadados reorganizando e combinando arquivos de manifesto menores. Essa compactação reduz a sobrecarga de metadados e melhora o desempenho das consultas.

Este recurso é habilitado automaticamente e não pode ser desativado.

Expiração de instantâneos¶

A expiração de instantâneos exclui sistematicamente instantâneos antigos e seus dados e arquivos de metadados exclusivos do histórico da tabela. Essa exclusão é baseada em políticas de retenção predefinidas.

Este recurso é habilitado automaticamente e não pode ser desativado.

Atualizar os metadados de uma tabela¶

O exemplo a seguir atualiza manualmente os metadados de uma tabela que usa um catálogo externo (por exemplo, AWS Glue ou Delta). A atualização da tabela mantém a tabela sincronizada com quaisquer alterações ocorridas no catálogo remoto.

Com esse tipo de tabela Iceberg, você não precisa especificar um caminho de arquivo de metadados no comando.

ALTER ICEBERG TABLE my_iceberg_table REFRESH;

Para manter uma tabela atualizada automaticamente, você pode configurar a atualização automática. Use o comando ALTER ICEBERG TABLE.

Por exemplo:

ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = TRUE;

Atualizar os metadados de uma tabela criada a partir de arquivos Iceberg¶

O exemplo a seguir atualiza manualmente uma tabela criada a partir de arquivos de metadados Iceberg em um local de armazenamento em nuvem externo, especificando o caminho relativo para um arquivo de metadados sem a barra (/) no início. O arquivo de metadados define os dados na tabela após a atualização.

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'metadata/v1.metadata.json';

Exemplo: Criar uma tabela com um valor padrão¶

Para criar uma tabela Iceberg com valores padrão, use o comando CREATE ICEBERG TABLE.

No exemplo a seguir, você primeiro define um valor padrão para uma coluna ao criar uma tabela Iceberg gerenciada pelo Snowflake. Em seguida, você insere um registro na tabela sem especificar um valor para a coluna com o valor padrão.

1. Crie uma tabela user_events, que inclui uma coluna event_version com um valor padrão de 2:

   CREATE ICEBERG TABLE user_events (
       event_id INT,
       user_id INT,
       event_type STRING,
       event_time TIMESTAMP,
       event_version INT DEFAULT 2
     )
     CATALOG = 'SNOWFLAKE'
     EXTERNAL_VOLUME = 'my_external_volume'
     BASE_LOCATION = 'database/schema/user_event'
     ICEBERG_VERSION = 3;
   

   Copy

   A configuração de um valor padrão na definição da tabela define um padrão inicial e um padrão de gravação. Como a coluna tem um padrão de gravação, o valor 2 será utilizado para novos registros se o event_version não for especificado durante as gravações.

2. Adicione um evento de login com event_version especificado:

   INSERT INTO user_events VALUES
     (1, 101, 'login', '2025-11-01 10:00:00', 1);
   

   Copy

3. Adicione um evento de compra, mas não especifique um event_version:

   INSERT INTO user_events VALUES
   (1, 101, 'purchase', '2025-11-01 10:01:00');
   

   Copy

   Como resultado, o Snowflake insere o valor de event_version na tabela como 2.

4. Consultar a tabela:

   SELECT * FROM user_events;
   

   Copy

   Saída:

   +-----------+----------+-------------+---------------------+----------------+
   | event_id  | user_id  | event_type  | event_time          | event_version  |
   +-----------+----------+-------------+---------------------+----------------+
   | 1         | 101      | login       | 2025-11-01 10:00:00 | 1              |
   | 1         | 101      | purchase    | 2025-11-01 10:01:00 | 2              |
   +-----------+----------+-------------+---------------------+----------------+
   

Exemplo: Adicionar uma coluna com um valor padrão a uma tabela existente¶

Para adicionar uma nova coluna com um valor padrão a uma tabela Iceberg, use o comando ALTER ICEBERG TABLE.

No exemplo a seguir, você modifica a tabela user_events adicionando uma coluna event_version, que tem um valor padrão de 2:

ALTER ICEBERG TABLE user_events ADD COLUMN event_version INT DEFAULT 2;

Além de definir um padrão de gravação, adicionar uma coluna com um valor padrão também define um padrão inicial para a coluna. Como resultado, o valor padrão para registros existentes na coluna event_version é 2.

Exemplo: Alterar o padrão de gravação de uma coluna¶

O exemplo a seguir altera o padrão de gravação da coluna event_version da tabela user_events para 3:

ALTER ICEBERG TABLE user_events ALTER COLUMN event_version SET WRITE DEFAULT 3;

Visualizar os valores padrão definidos para uma tabela¶

Para visualizar o valor padrão de uma coluna de tabela em uma tabela Iceberg gerenciada pelo Snowflake ou gerenciada externamente, execute o comando DESCRIBE ICEBERG TABLE e, em seguida, visualize as colunas DEFAULT e WRITE DEFAULT na saída:

• A coluna DEFAULT corresponde ao valor initial-default na especificação Apache Iceberg.

• A coluna WRITE DEFAULT corresponde ao valor write-default na especificação Apache Iceberg.

Essas colunas retornam na saída, independentemente de a tabela ser Iceberg v2 ou Iceberg v3.

O exemplo a seguir descreve as colunas da tabela user_events. Esta tabela tem um padrão inicial e um padrão de gravação especificados para a coluna event_version:

DESC ICEBERG TABLE user_events
  ->> SELECT
    "name",
    "kind",
    "default",
    "write default"
      FROM $1;

Saída:

+-----------------+---------+---------+---------------+
| name            | kind    | default | write default |
+-----------------+---------+-------------------------+
| EVENT_ID        | COLUMN  |         |               |
| USER_ID         | COLUMN  |         |               |
| EVENT_TYPE      | COLUMN  |         |               |
| EVENT_TIME      | COLUMN  |         |               |
| EVENT_VERSION   | COLUMN  | 2       | 3             |
+-----------------+---------+---------+---------------+

Descartar o padrão de gravação¶

Para descartar o padrão de gravação de uma coluna, use as palavras-chave DROP WRITE DEFAULT com o comando ALTER ICEBERG TABLE.

O exemplo a seguir descarta o valor de gravação padrão da coluna event_version:

ALTER ICEBERG TABLE user_events ALTER COLUMN event_version DROP WRITE DEFAULT;

Considerações e limitações para valores padrão¶

Considere os seguintes itens ao usar valores padrão com tabelas Iceberg gerenciadas pelo Snowflake e gerenciadas externamente:

Considerações e limitações para linhagem de linhas¶

A linhagem de linhas é compatível com fluxos, considerando o seguinte:

• Fluxos apenas de acréscimo e fluxos padrão são compatíveis com as tabelas Iceberg v3 gerenciadas pelo Snowflake.

• Fluxos apenas de inserção e fluxos padrão são compatíveis com tabelas Iceberg v3 gerenciadas externamente.

  • Para que os fluxos padrão produzam os resultados corretos, o mecanismo externo deve gravar nas tabelas Iceberg v3 em relação à especificação Iceberg v3. Especificamente, as linhas recém-inseridas devem ter _row_id=NULL. As linhas copiadas durante a cópia na gravação devem manter o endereço _row_id.

  • MAX_DATA_EXTENSION_TIME_IN_DAYS não funciona em tabelas Iceberg v3 gerenciadas externamente.

• Quando os DMLs são confirmados em transações com várias instruções, os fluxos apenas para acréscimo nas tabelas Iceberg v3 têm semânticas diferentes em comparação com as tabelas Iceberg v2:

  • No Iceberg v2, para fluxos apenas para acréscimo, se uma linha for adicionada e depois excluída em uma transação com várias instruções, essa linha será considerada uma inserção.

  • No Iceberg v3, para fluxos apenas para acréscimo, essa linha não é tratada como uma inserção.

Essas considerações e limitações se aplicam à linhagem de linhas, que é um recurso do Iceberg v3. Para obter uma lista de considerações e limitações que se aplicam a todas as tabelas Iceberg v3, consulte Considerações e limitações para recursos do Iceberg v3.