Usar um banco de dados vinculado a catálogo para tabelas Apache Iceberg™¶

Nota

Update: We will start billing for catalog-linked databases sometime in December 2025.

Com um banco de dados vinculado a catálogo, você pode acessar várias tabelas Iceberg remotas do Snowflake sem criar tabelas gerenciadas externamente individuais.

Um banco de dados vinculado a catálogo é um banco de dados Snowflake conectado a um catálogo Iceberg REST externo. O Snowflake sincroniza automaticamente com o catálogo externo para detectar namespaces e tabelas Iceberg e registra as tabelas remotas no banco de dados vinculado a catálogo. Os bancos de dados vinculados a catálogo também oferecem suporte à criação e remoção de esquemas ou tabelas Iceberg.

Faturamento de banco de dados vinculado a catálogo¶

When billing starts sometime in December 2025, Snowflake bills your account for the following usage:

Descoberta automática de tabela, criação de esquema, remoção de esquema e descarte de tabela. A Snowflake vai faturar sua conta de acordo com o tipo de uso CREDITS_USED_CLOUD_SERVICES. O uso de serviços de nuvem é cobrado somente se o consumo diário dos serviços de nuvem exceder 10% do uso diário de warehouses virtuais. Para obter mais informações, consulte Explicação do faturamento para uso de serviços de nuvem.
Criar tabela. A Snowflake vai faturar sua conta pela atualização automática de acordo com o tipo de uso CREDITS_USED_COMPUTE. O custo desse uso está descrito na tabela 5 da tabela de consumo de serviços do Snowflake no site da Snowflake. Consulte a coluna de computação gerenciada pelo Snowflake para a linha de atualização automatizada e o registro de dados.

A Snowflake não vai cobrar nenhum serviço de nuvem que você usar durante a criação da tabela.

Nota

Quando o faturamento começar, vamos lançar uma nova exibição CATALOG_LINKED_DATABASE_USAGE_HISTORY, que você pode usar para visualizar o uso de crédito para seus bancos de dados vinculados a catálogo.

Fluxo de trabalho para configurar o acesso ao seu catálogo externo e armazenamento de tabelas¶

As etapas a seguir abordam como criar um banco de dados vinculado a catálogo, verificar o status de sincronização entre o Snowflake e seu catálogo e criar ou consultar uma tabela no banco de dados.

Configurar o acesso ao seu catálogo externo e ao armazenamento de tabelas¶

Antes de criar um banco de dados vinculado a catálogo, você precisa configurar o acesso ao seu catálogo externo e ao armazenamento de tabelas. Para configurar esse acesso, você precisa definir uma integração de catálogo com as credenciais fornecidas. Com essa opção, seu catálogo Iceberg remoto deve oferecer suporte ao fornecimento de credenciais.

Para obter instruções, consulte Use as credenciais fornecidas pelo catálogo para tabelas Apache Iceberg™.

Nota

Se seu catálogo Iceberg remoto não oferece suporte ao fornecimento de credenciais, você deve configurar um volume externo e uma integração de catálogo para configurar o acesso ao seu catálogo externo e ao armazenamento de tabelas. Primeiro, configure um volume externo para seu provedor de armazenamento em nuvem. Em seguida, configure uma integração de catálogo Apache Iceberg™ REST para o seu catálogo Iceberg remoto.

Criar um banco de dados vinculado a catálogo¶

Crie um banco de dados vinculado a catálogo com o comando CREATE DATABASE (vinculado a catálogo):

O exemplo a seguir cria um banco de dados vinculado a catálogo que usa as credenciais fornecidas. O intervalo de sincronização é o padrão: 30 segundos. O intervalo de sincronização informa ao Snowflake com que frequência consultar seu catálogo remoto.

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int'
  );

Copy

Nota

Para criar um banco de dados vinculado a catálogo que usa um volume externo, consulte CREATE DATABASE (vinculado a catálogo), incluindo o exemplo.

Seu banco de dados vinculado a catálogo inclui um ícone de link.

Verificar o status de sincronização do catálogo¶

Para verificar se o Snowflake vinculou com sucesso o catálogo remoto ao banco de dados, use a função SYSTEM$CATALOG_LINK_STATUS.

A função também fornece informações para ajudar a identificar tabelas no catálogo remoto que não conseguiram fazer a sincronização.

SELECT SYSTEM$CATALOG_LINK_STATUS('my_linked_db');

Copy

Identificar tabelas que foram criadas, mas não puderam ser inicializadas¶

Para identificar tabelas no catálogo remoto que foram sincronizadas, mas não foram atualizadas automaticamente, execute o comando SHOW ICEBERG TABLES e, em seguida, consulte a coluna auto_refresh_status na saída. Essas tabelas têm um executionState de ICEBERG_TABLE_NOT_INITIALIZED na saída.

Por exemplo, o Snowflake pode descobrir e criar uma tabela em seu catálogo remoto para seu banco de dados vinculado, mas essa tabela tem um arquivo de dados corrompido no catálogo remoto. Como resultado, o Snowflake não pode atualizar automaticamente a tabela até que você resolva o erro.

A atualização automática é desativada para tabelas assim, então a consulta da tabela no Snowflake retorna um erro que diz que a tabela nunca foi inicializada. Para consultar a tabela, você deve corrigir o erro e depois ativar a atualização automática para a tabela.

Consultar uma tabela no seu banco de dados vinculado a catálogo¶

Após criar um banco de dados vinculado a catálogo, o Snowflake inicia o processo de descoberta de tabelas e consulta automaticamente o catálogo vinculado usando o valor do parâmetro SYNC_INTERVAL_SECONDS (com um intervalo padrão de 30 segundos) para verificar se há alterações.

No banco de dados, os namespaces permitidos do catálogo remoto aparecem como esquemas, e as tabelas Iceberg aparecem sob os respectivos esquemas.

Você pode consultar as tabelas remotas usando uma instrução SELECT.

Nota

Para saber os requisitos para identificar objetos em um banco de dados vinculado a catálogo, consulte Requisitos para resolução de identificadores em um banco de dados vinculado a catálogo.

Para obter mais informações sobre identificadores de objetos, consulte Requisitos para identificadores.

Por exemplo:

USE DATABASE my_linked_db;

SELECT * FROM my_namespace.my_iceberg_table
  LIMIT 20;

Copy

Gravar no seu catálogo remoto¶

Você pode usar o Snowflake para criar namespaces e tabelas Iceberg no seu catálogo vinculado. Para obter mais informações, consulte os seguintes tópicos:

Requisitos para resolução de identificadores em um banco de dados vinculado a catálogo¶

O requisito para a resolução de um identificador depende do seguinte:

O valor que você especificou para o parâmetro CATALOG_CASE_SENSITIVITY quando você criou seu banco de dados vinculado a catálogo
Se seu catálogo Iceberg externo usa identificadores com ou sem distinção de maiúsculas e minúsculas.

Nota

Esses requisitos se aplicam à identificação de esquemas, tabelas e colunas de tabelas existentes. Eles também incluem alguns casos especiais para criar ou alterar um objeto.
Ao criar um novo esquema, tabela ou coluna em um catálogo que diferencia maiúsculas de minúsculas, como AWS Glue ou Unity Catalog, você deve usar letras minúsculas e colocar os nomes do esquema, tabela e coluna entre aspas duplas. Isso também é necessário para outros catálogos Iceberg REST que aceitam apenas identificadores em minúsculas.

A tabela a seguir mostra os requisitos de cada cenário:

Valor CATALOG_CASE_SENSITIVITY	Usos do catálogo Iceberg externo	Requisito
CASE_SENSITIVE	Identificadores que diferenciam maiúsculas de minúsculas	O Snowflake corresponde exatamente aos identificadores, incluindo maiúsculas/minúsculas. O Snowflake converte automaticamente os identificadores sem aspas em letras maiúsculas, mas os identificadores entre aspas devem corresponder exatamente ao formato de maiúsculas/minúsculas no catálogo externo. O exemplo a seguir mostra uma consulta válida para a criação de uma tabela: CREATE TABLE "Table1" (id INT, name STRING); Copy O Snowflake cria a tabela no catálogo externo como `Table1`, que preserva o formato que você usou de maiúsculas/minúsculas. Observe que você também pode criar uma tabela `table1` em minúsculas, se necessário. O exemplo a seguir mostra uma consulta válida para selecionar a tabela `Table1`: SELECT * FROM "Table1"; Copy No exemplo anterior, as aspas duplas são necessárias para corresponder exatamente ao uso de maiúsculas. O exemplo a seguir mostra uma consulta inválida, a menos que exista uma tabela `TABLE1`: SELECT * FROM table1; Copy No exemplo anterior, a consulta é inválida se `TABLE1` não existir porque o identificador não está entre aspas duplas. Como resultado, o Snowflake converte o identificador em maiúsculas. O exemplo a seguir mostra uma consulta inválida, quando não existe uma `TABLE1` com todas as letras maiúsculas: SELECT * FROM TABLE1; Copy
CASE_SENSITIVE	Identificadores que não diferenciam maiúsculas e minúsculas	Se o catálogo Iceberg externo realmente não diferencia maiúsculas de minúsculas e normaliza para minúsculas, você deve colocar os identificadores entre aspas duplas. O exemplo a seguir mostra consultas válidas: SELECT * from "s1"; SELECT * from "lowercasetablename"; Copy
CASE_INSENSITIVE	Identificadores que não diferenciam maiúsculas e minúsculas	Se o catálogo que não diferencia maiúsculas de minúsculas tiver uma tabela `table1` em minúsculas, todas as consultas a seguir são válidas: SELECT * from table1; SELECT * from TABLE1; SELECT * from Table1; SELECT * from "table1"; Copy Para qualquer um dos comandos a seguir, você deve colocar os nomes do esquema, da tabela e da coluna entre aspas duplas: CREATE ICEBERG TABLE CREATE SCHEMA ALTER ICEBERG TABLE ADD COLUMN ALTER ICEBERG TABLE RENAME COLUMN
CASE_INSENSITIVE	Identificadores que diferenciam maiúsculas de minúsculas	Se o catálogo Iceberg externo realmente diferenciar maiúsculas de minúsculas, o Snowflake trata os identificadores sem aspas sem diferenciar maiúsculas e minúsculas e converte automaticamente os identificadores sem aspas em letras maiúsculas. Quando você cria ou consulta objetos, o Snowflake corresponde os identificadores independentemente de maiúsculas/minúsculas, desde que não estejam entre aspas. O uso desse padrão não é recomendado, porque o Snowflake não consegue resolver dois identificadores diferentes de maiúsculas/minúsculas. Esse padrão só funciona quando não há dois identificadores diferentes de maiúsculas/minúsculas. Considere o caso em que o catálogo remoto tem uma tabela `Table1`. Todas as consultas a seguir são válidas para consultar essa tabela. SELECT * from table1; SELECT * from TABLE1; SELECT * from Table1; SELECT * from "Table1"; Copy Os identificadores entre aspas preservam maiúsculas e minúsculas e têm uma correspondência exata. Entretanto, no modo CASE_INSENSITIVE, há suporte para formas entre aspas e sem aspas.

Considerações sobre o uso de um banco de dados vinculado a catálogo para tabelas Iceberg¶

Considere os seguintes itens ao usar um banco de dados vinculado a catálogo: