CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)¶

Sintaxe¶

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ] <name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<namespace>'
  REST_CONFIG = (
    restConfigParams
  )
  REST_AUTHENTICATION = (
    restAuthenticationParams
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

Onde:

restConfigParams ::=

  CATALOG_URI = '<rest_api_endpoint_url>'
  PREFIX = '<prefix>'
  WAREHOUSE = '<warehouse_name>'
  CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY }

Os restAuthenticationParams são os seguintes, dependendo do seu método de autenticação:

OAuth

restAuthenticationParams (for OAuth) ::=

  TYPE = OAUTH
  OAUTH_TOKEN_URI = 'https://<token_server_uri>'
  OAUTH_CLIENT_ID = '<oauth_client_id>'
  OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
  OAUTH_ALLOWED_SCOPES = ('<scope_1>', '<scope_2>')

Token de portador

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'

SigV4

restAuthenticationParams (for SigV4) ::=

  TYPE = SIGV4
  SIGV4_IAM_ROLE = '<iam_role_arn>'
  SIGV4_SIGNING_REGION = '<region>'

Parâmetros¶

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 = ICEBERG_REST

Especifica que a origem do catálogo é um catálogo REST compatível com a especificação REST Apache Iceberg.

TABLE_FORMAT = ICEBERG

Especifica ICEBERG como o formato de tabela fornecido pelo catálogo.

CATALOG_NAMESPACE = 'namespace'

Especifica o namespace no catálogo externo. O Snowflake usa esse namespace para todas as tabelas Iceberg que você associou a esta integração de catálogo.

É possível substituir esse valor especificando um namespace no nível da tabela ao criar uma tabela.

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.

• FALSE impede que os usuários criem novas tabelas Iceberg que referenciem esta integração.

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

Recurso em versão preliminar

Disponível para todas as contas.

COMMENT = 'string_literal'

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

Padrão: sem valor

Parâmetros de autenticação REST (restAuthenticationParams)¶

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

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¶

• As integrações de catálogo fornecem acesso somente leitura a catálogos Iceberg externos.

• 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.

Exemplos¶

O exemplo a seguir cria uma integração de catálogo REST que usa OAuth para se conectar ao tabular.

CREATE OR REPLACE CATALOG INTEGRATION tabular_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://api.tabular.io/ws'
    WAREHOUSE = '<tabular_warehouse_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://api.tabular.io/ws/v1/oauth/tokens'
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
    OAUTH_ALLOWED_SCOPES = ('catalog')
  )
  ENABLED = TRUE;