Atualizar tabelas Apache Iceberg™ automaticamente

Configure atualizações automatizadas de metadados para Tabelas Apache Iceberg™ novos ou existentes gerenciados externamente. Com atualizações automatizadas, o Snowflake pesquisa seu catálogo Iceberg externo de forma contínua e sem servidor para sincronizar os metadados com as alterações remotas mais recentes.

A atualização automática é compatível para tabelas que usam as seguintes opções de catálogo externo:

  • AWS Glue

  • O catálogo REST que está em conformidade com a especificação Apache Iceberg REST OpenAPI

  • Snowflake Open Catalog

  • Armazenamento de objetos (somente Delta Lake)

Definir o intervalo de atualização em uma integração de catálogo

Ao executar o comando CREATE CATALOG INTEGRATION, você pode especificar um valor para o parâmetro REFRESH_INTERVAL_SECONDS. Caso contrário, o intervalo de atualização padrão é 30 segundos. O Snowflake só pesquisa o catálogo externo se houver tabelas Iceberg definidas com a integração do catálogo.

O exemplo a seguir cria uma integração de catálogo para o AWS Glue, especificando um intervalo de atualização de 60 segundos:

CREATE CATALOG INTEGRATION auto_refresh_catalog_integration
  CATALOG_SOURCE = GLUE
  CATALOG_NAMESPACE = 'my_catalog_namespace'
  TABLE_FORMAT = ICEBERG
  GLUE_AWS_ROLE_ARN = 'arn:aws:iam::123456789123:role/my-catalog-role'
  GLUE_CATALOG_ID = '123456789123'
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 60;
Copy

Para atualizar o intervalo de atualização de uma integração de catálogo, use o comando ALTER CATALOG INTEGRATION.

Por exemplo:

ALTER CATALOG INTEGRATION auto_refresh_catalog_integration SET REFRESH_INTERVAL_SECONDS = 120;
Copy

Criar uma tabela Iceberg com atualização automatizada

Crie uma tabela Iceberg usando o comando CREATE ICEBERG TABLE. Para especificar que a tabela deve usar atualizações automatizadas de metadados, defina AUTO_REFRESH = TRUE.

O exemplo a seguir cria uma tabela Iceberg que usa o AWS Glue como catálogo, especificando a integração de catálogo criada anteriormente (auto_refresh_catalog_integration) e o CATALOG_TABLE_NAME do AWS Glue.

CREATE OR REPLACE ICEBERG TABLE auto_refresh_iceberg_table
  CATALOG_TABLE_NAME = 'myGlueTable'
  CATALOG = 'auto_refresh_catalog_integration'
  AUTO_REFRESH = TRUE;
Copy

Habilitar ou desabilitar a atualização automática

Nota

  • Se a tabela usar uma integração de catálogo criada antes do Snowflake versão 8.22, você deverá usar o comando ALTER CATALOG INTEGRATION para definir o parâmetro REFRESH_INTERVAL_SECONDS antes de habilitar a atualização automatizada na tabela.

  • Ativar e desativar com frequência a atualização automática de uma tabela Iceberg pode tornar as atualizações de metadados da tabela mais lentas.

Use o comando ALTER ICEBERG TABLE para habilitar ou desabilitar a atualização automática de uma tabela Iceberg existente.

Por exemplo:

ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = FALSE;
Copy

Monitoramento do status da atualização automatizada

SHOW ICEBERG TABLES

Para obter o status da atualização automática de várias tabelas, use o comando SHOW ICEBERG TABLES.

SHOW ICEBERG TABLES;
Copy

A saída do comando inclui uma coluna chamada auto_refresh_status, que exibe as mesmas informações que a função SYSTEM$AUTO_REFRESH_STATUS para cada tabela em que você tem privilégios de acesso.

SYSTEM$AUTO_REFRESH_STATUS

Para recuperar o status da atualização automática de uma tabela específica, chame a função SYSTEM$AUTO_REFRESH_STATUS.

SELECT SYSTEM$AUTO_REFRESH_STATUS('my_iceberg_table');
Copy

A função retorna detalhes sobre o canal que o Snowflake usa para automatizar atualizações da tabela, como o estado de execução e o tamanho da fila de snapshots. Um estado de execução RUNNING indica que a atualização automatizada está sendo executada conforme o esperado. Para obter mais informações, consulte SYSTEM$AUTO_REFRESH_STATUS.

ICEBERG_TABLE_SNAPSHOT_REFRESH_HISTORY

Para recuperar informações de metadados e instantâneos sobre o histórico de atualização mais recente de uma tabela específica, use a função ICEBERG_TABLE_SNAPSHOT_REFRESH_HISTORY.

SELECT *
FROM TABLE(INFORMATION_SCHEMA.ICEBERG_TABLE_SNAPSHOT_REFRESH_HISTORY(
  TABLE_NAME => 'my_iceberg_table'
));
Copy

Recuperação de erros

Quando ocorre um erro durante o processo de atualização automatizada, o Snowflake atualiza o estado de execução para um dos seguintes valores:

  • STALLED significa que o Snowflake está tentando se recuperar do erro. Se a recuperação for bem-sucedida, o processo de atualização automatizada continuará sendo executado conforme o esperado, e o estado de execução retornará ao estado RUNNING de integridade.

  • STOPPED significa que o processo de atualização automatizada encontrou um erro irrecuperável e as atualizações automatizadas da tabela foram interrompidas.

    Um erro irrecuperável pode ocorrer, por exemplo, quando o Snowflake não consegue estabelecer uma linhagem direta entre o snapshot de destino e o snapshot atual.

    Para se recuperar de um estado STOPPED, execute as seguintes ações:

    1. Desative a atualização automática na tabela.

    2. Execute uma atualização manual de metadados. Para obter instruções, consulte Atualização dos metadados da tabela.

    3. Reative a atualização automatizada usando uma instrução ALTER ICEBERG TABLE … SET AUTO_REFRESH.

    4. Verifique se a atualização automatizada está no estado RUNNING chamando a função SYSTEM$AUTO_REFRESH_STATUS. Você também pode chamar a função várias vezes para confirmar que o número de snapshots enfileirados (pendingSnapshotCount) diminui gradualmente.

Faturamento

A Snowflake usa o Snowpipe para automatizar atualizações de tabelas Iceberg, então as cobranças por atualizações automatizadas aparecem no mesmo item de linha da sua fatura que as cobranças do Snowpipe. Não há cobrança de arquivo Snowpipe para esse recurso.

Você pode estimar as cobranças incorridas examinando o Account Usage Exibição PIPE_USAGE_HISTORY, que exibe o nome da tabela Iceberg na coluna pipe_name.

Para tabelas Iceberg baseadas em Delta, os canais de atualização automática exibem um nome de canal NULL.

Para obter mais informações sobre as cobranças da tabela Iceberg, consulte Faturamento da tabela Iceberg.

Considerações e limitações

Considere o seguinte ao trabalhar com tabelas Iceberg que usam atualização automática:

  • Quando a atualização automática está habilitada, você não pode atualizar manualmente os metadados da tabela. Para executar uma atualização manual, primeiro desative a atualização automática.

  • Para integrações de catálogo criadas antes da versão 8.22 do Snowflake (ou 9.2 para tabelas baseadas em Delta), você deve definir manualmente o parâmetro REFRESH_INTERVAL_SECONDS antes de ativar a atualização automática em tabelas que dependem dessa integração de catálogo. Para obter instruções, consulte ALTER CATALOG INTEGRATION … SET AUTO_REFRESH.

  • Se a tabela estiver vazia, insira dados na tabela e, em seguida, faça uma atualização manual no Snowflake antes de ativar a atualização automática para evitar comportamentos indefinidos.

  • Para as integrações de catálogo para armazenamento de objetos, a atualização automatizada só é compatível com as integrações com TABLE_FORMAT = DELTA.

  • Para tabelas com atualizações frequentes, o uso de um intervalo de pesquisa mais curto (REFRESH_INTERVAL_SECONDS) pode causar degradação do desempenho.