Sincronizar uma tabela gerenciada pelo Snowflake com Snowflake Open Catalog

Para consulta uma tabela Apache Iceberg™ gerenciada pelo Snowflake usando um mecanismo de terceiros, como o Apache Spark™, você pode sincronizar a tabela com o Snowflake Open Catalog.

Este tópico aborda como sincronizar uma tabela Iceberg gerenciada pelo Snowflake com o Snowflake Open Catalog usando uma integração de catálogo no Snowflake e um catálogo externo no Open Catalog.

Importante

Se o mecanismo de terceiros só puder consultar tabelas localizadas até o segundo nível de namespace em um catálogo, você deverá sincronizar a tabela Iceberg gerenciada pelo Snowflake com o Open Catalog com um namespace pai. Caso contrário, o Snowflake sincronizará a tabela com o terceiro nível de namespace no Open Catalog e você não poderá consultar a tabela.

Para sincronizar uma tabela Iceberg gerenciada pelo Snowflake com um namespace pai em vez de dois, defina a propriedade CATALOG_SYNC_NAMESPACE_MODE como FLATTEN ao criar o banco de dados. Para obter mais informações, consulte CREATE DATABASE. Você não pode alterar esse modo para um banco de dados existente. As tabelas em um banco de dados existente com CATALOG_SYNC ativado serão sincronizadas com o Open Catalog com dois namespaces pai.

Etapa 1: defina um BASE_LOCATION_PREFIX

O Snowflake grava os arquivos de cada tabela Iceberg em um diretório que inclui uma cadeia de caracteres gerada dinamicamente (ID aleatório).

Para garantir que o Open Catalog possa ver todas as tabelas gerenciadas pelo Snowflake que você sincroniza, recomendamos que use um BASE_LOCATION_PREFIX (como my-open-catalog-tables) no nível da conta, do banco de dados ou do esquema e omita o parâmetro BASE_LOCATION nas instruções CREATE ICEBERG TABLE. Isso organiza os arquivos de todas as tabelas Iceberg que você criar na conta, no banco de dados ou no esquema em um diretório conhecido com o mesmo nome do prefixo. Para obter mais informações, consulte Diretórios de dados e metadados para tabelas gerenciadas pelo Snowflake <label-tables_iceberg_configure_external_volume_base_location>.

A instrução a seguir define um BASE_LOCATION_PREFIX para um esquema chamado open_catalog:

ALTER SCHEMA open_catalog
  SET BASE_LOCATION_PREFIX = 'my-open-catalog-tables';
Copy

Etapa 2: crie um volume externo

Se você ainda não tiver um, comece criando um volume externo no Snowflake que forneça acesso ao local de armazenamento em nuvem onde você deseja armazenar os dados da tabela e os metadados.

Nota

Não inclua o BASE_LOCATION_PREFIX no caminho que você especificar para o STORAGE_BASE_URL.

Siga as instruções para o seu serviço de armazenamento em nuvem:

Etapa 3: configure os recursos de Open Catalog

Em seguida, conclua as etapas desta seção para criar um catálogo externo e uma conexão de serviço em sua conta Open Catalog.

  1. Siga as instruções em Criar um catálogo para criar um catálogo externo na sua conta Open Catalog. Certifique-se de que as seguintes configurações para o catálogo externo estejam configuradas:

    • O botão External está habilitado.

    • O Default base location combina o STORAGE_BASE_URL para o volume externo que você criou em Etapa 2: crie um volume externo e o BASE_LOCATION_PREFIX que você definiu para o esquema; por exemplo, https://<storage_base_url>/<base_url_prefix>/.

    O Open Catalog sincroniza suas tabelas gerenciadas pelo Snowflake com esse catálogo externo.

  2. Se você ainda não tiver uma conexão de serviço para o Snowflake, siga as instruções em Configurar uma conexão de serviço para criar uma conexão para o mecanismo Snowflake na sua conta Open Catalog.

  3. Configure uma função de catálogo para seu catálogo externo com privilégios que permitam acesso ao seu catálogo externo. Para obter instruções, consulte Conceder privilégios a um catálogo.

    A função de catálogo deve ter os seguintes privilégios no catálogo:

    • TABLE_CREATE

    • TABLE_WRITE_PROPERTIES

    • TABLE_DROP

    • NAMESPACE_CREATE

    • NAMESPACE_DROP

    Você pode conceder cada um desses privilégios à função de catálogo ou conceder o privilégio CATALOG_MANAGE_CONTENT, que inclui esses privilégios. Para obter mais informações, consulte Privilégios de catálogo para o Snowflake Open Catalog.

  4. Anexe a função de catálogo à função principal para sua conexão de serviço. Isso permite que a conexão de serviço acesse o catálogo. Para obter instruções, consulte Conceder uma função de catálogo a uma função principal.

Etapa 4: crie uma integração de catálogo para Open Catalog

Crie uma integração de catálogo para o Open Catalog usando o comando CREATE CATALOG INTEGRATION (Snowflake Open Catalog).

Para CATALOG_NAME, especifique o nome do catálogo externo que você configurou na sua conta Open Catalog. O Snowflake sincroniza a tabela e seu namespace pai no Snowflake com esse catálogo externo no Open Catalog. Por exemplo, se você tiver uma tabela db1.public.table1 Iceberg registrada no Snowflake e especificar catalog1 na integração do catálogo, o Snowflake sincronizará a tabela com Open Catalog com o seguinte nome totalmente qualificado: catalog1.db1.public.table1.

Para solucionar problemas com a criação de uma integração de catálogo, consulte Não é possível criar uma integração de catálogo para o Open Catalog.

CREATE OR REPLACE CATALOG INTEGRATION my_open_catalog_int
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog'
    CATALOG_NAME = 'myOpenCatalogExternalCatalogName'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'myClientId'
    OAUTH_CLIENT_SECRET = 'myClientSecret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;
Copy

Nota

Você pode usar essa integração de catálogo para sincronizar uma ou mais tabelas gerenciadas pelo Snowflake.

Etapa 5: configure a sincronização do catálogo

Para que o Snowflake sincronize as tabelas Iceberg gerenciadas pelo Snowflake com o Open Catalog, você deve especificar o catálogo externo no Open Catalog com o qual o Snowflake deve sincronizar as tabelas. Para configurar isso, você define o parâmetro CATALOG_SYNC como o nome de uma integração de catálogo para Open Catalog.

Defina CATALOG_SYNC no nível do banco de dados

Este exemplo define o parâmetro CATALOG_SYNC no nível do banco de dados. Após executar essas instruções, o Snowflake sincroniza todas as tabelas Iceberg gerenciadas pelo Snowflake no banco de dados db1 com o catálogo externo no Open Catalog que você especificou para a integração do catálogo my_open_catalog_int. Para obter mais informações, consulte ALTER DATABASE.

ALTER DATABASE db1 SET CATALOG_SYNC = 'my_open_catalog_int';
Copy

Você também pode definir CATALOG_SYNC no nível do banco de dados ao criar um banco de dados. Por exemplo:

CREATE DATABASE db2
  CATALOG_SYNC = 'my_open_catalog_int';
Copy

Para obter mais informações, consulte CREATE DATABASE.

Defina CATALOG_SYNC no nível do esquema

Este exemplo define o parâmetro CATALOG_SYNC no nível do esquema. Após executar essas instruções, o Snowflake sincroniza todas as tabelas Iceberg gerenciadas pelo Snowflake no esquema public com o catálogo externo no Open Catalog que você especificou para a integração do catálogo my_open_catalog_int. Para obter mais informações, consulte ALTER SCHEMA.

ALTER SCHEMA public SET CATALOG_SYNC = 'my_open_catalog_int';
Copy

Você também pode definir CATALOG_SYNC no nível do esquema ao criar um esquema. Por exemplo:

CREATE SCHEMA schema1
  CATALOG_SYNC = 'my_open_catalog_int';
Copy

Para obter mais informações, consulte CREATE SCHEMA.

Nota

  • Você também pode fazer o seguinte:

    • Defina CATALOG_SYNC no nível da conta ou da tabela.

    • Substitua CATALOG_SYNC em diferentes níveis. Por exemplo, você pode definir CATALOG_SYNC no nível do banco de dados e, em seguida, substituir seu valor para o esquema myschema no banco de dados. Como resultado, as tabelas Iceberg gerenciadas pelo Snowflake no esquema myschema são sincronizadas com um catálogo externo diferente no Open Catalog do que as outras tabelas Iceberg gerenciadas pelo Snowflake no banco de dados.

    Para obter mais informações, consulte CATALOG_SYNC e Hierarquia de parâmetros e tipos.

  • Para ver o nome da integração do catálogo para o Open Catalog com a qual uma tabela Iceberg gerenciada pelo Snowflake é sincronizada, execute o comando SHOW ICEBERG TABLES e veja a coluna catalog_sync_name na saída.

Etapa 6: crie uma tabela gerenciada pelo Snowflake

Crie uma tabela Iceberg gerenciada pelo Snowflake usando o comando CREATE ICEBERG TABLE (Snowflake como o catálogo Iceberg).

Importante

Para garantir que os privilégios de acesso no Open Catalog sejam aplicados corretamente na tabela, certifique-se de que a tabela atenda a determinadas condições antes de criá-la. Essas condições estão relacionadas à hierarquia da estrutura de diretórios do catálogo. Para obter essas condições e instruções sobre como atendê-las, consulte a nota em Organização do conteúdo do catálogo na documentação do Snowflake Open Catalog.

USE SCHEMA open_catalog;

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (col1 INT)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume';
Copy

Para o BASE_LOCATION_PREFIX (my-open-catalog-tables) e o nome de tabela (my_iceberg_table) usados nas instruções do exemplo anterior, o Snowflake grava os arquivos de tabela nos seguintes caminhos:

  • STORAGE_BASE_URL/my-open-catalog-tables/my_iceberg_table.randomId/data/

  • STORAGE_BASE_URL/my-open-catalog-tables/my_iceberg_table.randomId/metadata/

Quando você modifica a tabela no Snowflake, as alterações são sincronizadas automaticamente com o catálogo externo na sua conta Open Catalog. Outros mecanismos, como o Apache Spark™, podem consultar a tabela conectando-se ao Open Catalog.

Para solucionar problemas com a criação de uma tabela gerenciada pelo Snowflake, consulte Não é possível criar uma tabela gerenciada pelo Snowflake.

Linguagem: Português