Metadados e retenção para tabelas Apache Iceberg™¶

Criação¶

O Snowflake gera metadados para a versão 2 da especificação Apache Iceberg periodicamente e grava os metadados em arquivos no seu volume externo. Cada novo arquivo de metadados contém todas as alterações DML ou DDL feitas desde a criação do último arquivo de metadados gerado pelo Snowflake.

Você também pode criar metadados sob demanda usando a função SYSTEM$GET_ICEBERG_TABLE_INFORMATION. Para obter instruções, consulte Geração de instantâneos de alterações de DML.

Para obter informações sobre como localizar arquivos de metadados, consulte Diretórios de dados e metadados.

Visualização do histórico de criação de metadados¶

Para acessar um histórico completo de tentativas de geração de metadados, exiba o histórico de consulta da sua conta e filtre os resultados. Procure o nome da função SYSTEM$GET_ICEBERG_TABLE_INFORMATION no texto SQL.

O Snowflake usa internamente a mesma função SYSTEM$GET_ICEBERG_TABLE_INFORMATION para gerar metadados da tabela. As tentativas feitas pelo Snowflake aparecem no usuário chamado SYSTEM no histórico de consulta. A coluna STATUS no histórico de consulta indica se os metadados foram gerados com sucesso.

Para opções de exibição, consulte Monitoramento da atividade de consulta com o Histórico de consultas.

Exclusão¶

O Snowflake exclui metadados Iceberg do seu armazenamento em nuvem externo quando os seguintes eventos ocorrem:

• Depois de você descartar uma tabela.

• Quando os metadados Iceberg se referem a snapshots ou dados de tabela que expiraram.

A exclusão não ocorre imediatamente após o término do período de retenção de dados. Como resultado, o armazenamento de metadados pode incorrer em custos com seu provedor de armazenamento em nuvem por mais tempo do que a vida útil de uma tabela.

Tabelas baseadas em Delta¶

Para tabelas Iceberg criadas a partir de arquivos de tabela Delta, o Snowflake grava automaticamente os metadados Iceberg em seu armazenamento externo se você configurar o volume externo com acesso de gravação (consulte ALLOW_WRITES). Para obter mais informações sobre o local de gravação, consulte Diretórios de dados e metadados.

Para evitar que o Snowflake grave metadados Iceberg, você pode definir o parâmetro ALLOW_WRITES como FALSE no volume externo, desde que nenhuma tabela Iceberg gerenciada pelo Snowflake use o mesmo volume externo.

Particionamento «oculto»¶

O particionamento “oculto” para Apache Iceberg™ é baseado em metadados e é adaptável. O Iceberg produz valores de partição com base nas transformações que você define ao criar uma tabela. Ao lerem uma tabela particionada, os mecanismos Iceberg utilizam os valores de partição definidos nos metadados da tabela para identificar de forma eficiente os dados relevantes.

Essa opção é a padrão. Com ela, o Snowflake armazena seus arquivos de dados Parquet usando uma estrutura de diretório plana.

Para criar uma tabela Iceberg particionada que usa particionamento oculto, inclua a cláusula PARTITION BY com uma ou mais transformações de partição em sua instrução CREATE ICEBERG TABLE regular.

Para obter um exemplo, consulte Criar uma tabela Iceberg em um banco de dados vinculado a catálogo.

Particionamento com caminhos hierárquicos¶

Com essa opção, o Snowflake grava dados em tabelas Iceberg particionadas usando um layout de caminho hierárquico para arquivos de dados Parquet. As informações de particionamento são incluídas nos caminhos dos arquivos e os valores são baseados em transformações que você define ao criar uma tabela. Esse layout também é chamado de particionamento «estilo Hive». Você pode usar essa opção para interoperabilidade entre o Snowflake e mecanismos externos compatíveis com gravações particionadas com caminhos hierárquicos.

Aqui está um exemplo de um arquivo de dados armazenado em um caminho hierárquico:

s3://my-bucket/iceberg/db_sales/orders/data/country=US/year=2025/month=02/day=21/part-00023.parquet

Para obter mais informações sobre o layout dos diretórios de dados e metadados para tabelas que usam caminhos hierárquicos, consulte Gerenciamento de arquivos.

Matriz de suporte para particionamento¶

A tabela a seguir mostra quais recursos e ações são compatíveis com cada tipo de tabela Iceberg particionada e indica a conformidade com a versão 2 da especificação Apache Iceberg. A tabela mostra a compatibilidade tanto com particionamento oculto quanto com particionamento com caminhos hierárquicos.

Considerações sobre particionamento¶

Considere o seguinte antes de usar gravações particionadas para tabelas Iceberg:

• Se você usar um mecanismo externo para adicionar, excluir ou substituir um campo de partição em uma tabela gerenciada externamente, o Snowflake gravará os dados de acordo com a especificação de partição mais recente.

• A função GET_DDL não inclui a cláusula PARTITION BY em sua saída.

• A soma dos tamanhos das saídas de todas as transformações de partição não pode exceder 1.024 bytes para uma única linha.

• Como a evolução de partição não é compatível com tabelas gerenciadas pelo Snowflake, descarte a tabela e crie outra com particionamento.

• Os parâmetros de transformação de partição DAY(), MONTH() e YEAR(), que você especifica dentro da cláusula PARTITION BY nas propriedades de tabela, fazem parte da especificação Iceberg. Por vários dias, meses ou anos, o parâmetro de expressão de partição retorna uma partição para cada dia, mês ou ano do calendário. Por exemplo, quando a transformação DAY() é usada em uma coluna de carimbo de data/hora que tem 2 meses de dados, 61 partições são criadas.

  Em comparação, as funções DAY(), MONTH() e YEAR() no Snowflake são parte do padrão SQL. Para vários dias, meses ou anos, essas funções extraem a parte do dia, mês ou ano correspondente de uma data ou carimbo de data/hora. Por exemplo, quando a função DAY() é usada em uma coluna de carimbo de data/hora com vários meses de dados, essa função retorna um dia do mês que varia de 1 a 31.

• Você não pode usar o comando ALTER ICEBERG TABLE para modificar a propriedade PATH_LAYOUT de uma tabela existente.

• Para particionamento com caminhos hierárquicos:

  • Para valores float, o Snowflake e mecanismos externos podem se comportar de maneira diferente.

  • O Snowflake não consegue garantir que os caminhos que ele grava correspondam aos caminhos que os mecanismos de consulta externos gravam.

    O Snowflake não garante isso porque, quando um mecanismo de consulta grava um caminho hierárquico, ele precisa serializar os valores em uma cadeia de caracteres e inserir o valor resultante no caminho. A especificação da tabela Apache Iceberg não define um método de serialização padrão; portanto, diferentes mecanismos podem implementar métodos diferentes.

    Por exemplo, o Snowflake não codifica o caractere ~, mas o Apache Spark™ o codifica como %7E.

  • O Snowflake sempre grava os caminhos hierárquicos diretamente no diretório /data do seu armazenamento em nuvem externo.