CREATE CATALOG INTEGRATION (Snowflake Open Catalog)¶

Cria uma nova integração de catálogo para tabelas Apache Iceberg™ que se integram ao Snowflake Open Catalog na conta ou substitui uma integração de catálogo existente.

Consulte também:: ALTER CATALOG INTEGRATION, DROP CATALOG INTEGRATION, SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION

Sintaxe¶

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ]
  <name>
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<open_catalog_namespace>'
  REST_CONFIG = (
    CATALOG_URI = '<open_catalog_account_url>'
    WAREHOUSE = '<open_catalog_catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('<scope 1>', '<scope 2>')
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

Copy

Parâmetros obrigatórios¶

name

Cadeia de caracteres que especifica o identificador (nome) para a integração de catálogo; deve ser única em sua conta.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

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

CATALOG_SOURCE = POLARIS

Especifica Snowflake Open Catalog como a fonte do catálogo.

TABLE_FORMAT = ICEBERG

Especifica Apache Iceberg™ como o formato de tabela fornecido pelo catálogo.

CATALOG_NAMESPACE = 'open_catalog_namespace'

Se você estiver criando a integração de catálogo para consultar uma tabela no Snowflake Open Catalog usando o Snowflake, especifique o namespace em Open Catalog. O Snowflake usa esse namespace para todas as tabelas Iceberg que você associa a essa integração de catálogo.

É possível substituir esse valor especificando um namespace no nível da tabela ao criar uma tabela.
Se você estiver criando a integração do catálogo para sincronizar uma tabela gerenciada pelo Snowflake com o Snowflake Open Catalog, especifique default. Esse valor especifica o namespace padrão do catálogo.

Ao sincronizar uma tabela gerenciada pelo Snowflake com o Open Catalog, o Snowflake sincroniza a tabela com o catálogo associado à integração de catálogo da tabela usando dois namespaces pai. Os namespaces correspondem ao banco de dados e ao esquema da tabela no Snowflake. Por exemplo, se você tiver uma tabela Iceberg db1.public.table1 registrada no Snowflake e especificar catalog1 na integração do catálogo, ela será sincronizada com o Open Catalog com o seguinte nome totalmente qualificado: catalog1.db1.public.table1.

REST_CONFIG = ( ... )

Especifica informações sobre sua conta e nome de catálogo Open Catalog.

CATALOG_URI = 'https://open_catalog_account_url'

Seu URL do localizador de conta Open Catalog.

Exemplo de valores:

https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog
- Para encontrar o nome de sua organização Snowflake (<orgname>), siga as etapas em Como encontrar o nome da conta e organização de uma conta.
- Para encontrar <my-snowflake-open-catalog-account-name, consulte Encontre o nome de uma conta do Snowflake Open Catalog na documentação de Snowflake Open Catalog.
https://<account_locator>.<cloud_region_id>.<cloud>.snowflakecomputing.com/polaris/api/catalog
- Para encontrar seu <account_locator>, <cloud_region_id> e <cloud>, consulte Formato 2: Localizador de conta em uma região..

WAREHOUSE = 'open_catalog_name'

O parâmetro WAREHOUSE especifica o nome do catálogo a ser usado em Open Catalog.

REST_AUTHENTICATION = ( ... )

Especifica os detalhes de autenticação que o Snowflake usa para se conectar ao Open Catalog.

TYPE = OAUTH: Especifica o OAuth como o tipo de autenticação a ser usado.
OAUTH_CLIENT_ID = 'oauth_client_id': O ID de cliente da credencial OAuth2 associada à sua conexão de serviço Open Catalog.
OAUTH_CLIENT_SECRET = 'oauth_secret': O segredo da credencial OAuth2 associada à sua conexão de serviço Open Catalog.
OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2'): O escopo do token de OAuth. Apenas um escopo está incluído na especificação da API REST Iceberg, mas os catálogos podem oferecer suporte a mais de um escopo em sua implementação.

ENABLED = {TRUE | FALSE}

Especifica se a integração do catálogo está disponível para uso em tabelas Iceberg.

TRUE permite que os usuários criem novas tabelas Iceberg que fazem referência a esta integração. As tabelas Iceberg existentes que fazem referência a esta integração funcionam normalmente.

FALSE impede que os usuários criem novas tabelas Iceberg que referenciem esta integração. As tabelas Iceberg existentes que fazem referência a esta integração não podem acessar o catálogo na definição da tabela.

Parâmetros opcionais¶

REFRESH_INTERVAL_SECONDS = value

Especifica o número de segundos que o Snowflake aguarda entre as tentativas de pesquisar o catálogo Iceberg externo para atualizações de metadados para atualização automatizada.

Valores: 30 a 86400, inclusivo

Padrão: 30 segundos

COMMENT = 'string_literal'

Cadeia de caracteres (literal) que especifica um comentário da integração.

Padrão: sem valor

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

Privilégio	Objeto	Notas
CREATE INTEGRATION	Conta	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

Não é possível modificar uma integração de catálogo existente; use uma instrução CREATE OR REPLACE CATALOG INTEGRATION.
Não é possível descartar ou substituir uma integração de catálogo se uma ou mais tabelas Apache Iceberg™ estiverem associadas à integração de catálogo.

Para visualizar as tabelas que dependem de uma integração de catálogo, você pode usar o comando SHOW ICEBERG TABLES e uma consulta usando RESULT_SCAN que filtra na coluna catalog_name.

Nota

O identificador da coluna (catalog_name) diferencia maiúsculas de minúsculas. Especifique o identificador da coluna exatamente como ele aparece na saída SHOW ICEBERG TABLES.

Por exemplo:
```
SHOW ICEBERG TABLES;

SELECT * FROM TABLE(
  RESULT_SCAN(
      LAST_QUERY_ID()
    )
  )
  WHERE "catalog_name" = 'my_catalog_integration_1';
```
Copy
Em relação aos metadados:

Atenção

Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.
Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.
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.

Exemplos¶

O exemplo a seguir cria uma integração de catálogo para o Open Catalog para um namespace específico em um catálogo interno no Open Catalog para consultar tabelas agrupadas neste namespace no Snowflake. Para obter mais informações sobre catálogos internos no Open Catalog, consulte Tipos de catálogo na documentação do Open Catalog.

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_catalog_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.com/polaris/api/catalog'
    WAREHOUSE = 'my_catalog_name'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;

Copy

O exemplo a seguir cria uma integração de catálogo para Open Catalog para sincronizar tabelas gerenciadas pelo Snowflake com o catálogo customers no Open Catalog, que é um catálogo externo. Para obter mais informações sobre catálogos externos no Open Catalog, consulte Tipos de catálogo na documentação do Open Catalog.

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int2
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.com/polaris/api/catalog'
    WAREHOUSE = 'customers'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;

Copy