CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)¶

Syntaxe¶

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>' ]

Où :

restConfigParams ::=

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

Les restAuthenticationParams sont les suivants, en fonction de votre méthode d’authentification :

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>')

Jeton du porteur

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>'

Paramètres¶

name

Chaîne spécifiant l’identificateur (le nom) de l’intégration de catalogue ; elle doit être unique sur votre compte.

De plus, l’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (par exemple, "My object"). Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus d’informations, voir Exigences relatives à l’identificateur.

CATALOG_SOURCE = ICEBERG_REST

Spécifie que la source du catalogue est un catalogue REST compatible avec la spécification Apache Iceberg REST.

TABLE_FORMAT = ICEBERG

Spécifie ICEBERG comme format de table fourni par le catalogue.

CATALOG_NAMESPACE = 'namespace'

Spécifie l’espace de noms dans le catalogue externe. Snowflake utilise cet espace de noms pour toutes les tables Iceberg que vous associez à cette intégration de catalogue.

Vous pouvez remplacer cette valeur en spécifiant l’espace de noms au niveau de la table lorsque vous créez une table.

ENABLED = { TRUE | FALSE }

Indique si l’intégration de catalogue peut être utilisée pour des tables Iceberg.

• TRUE permet aux utilisateurs de créer de nouvelles tables Iceberg faisant référence à cette intégration.

• FALSE empêche les utilisateurs de créer de nouvelles tables Iceberg faisant référence à cette intégration.

REFRESH_INTERVAL_SECONDS = value

Spécifie le nombre de secondes pendant lesquelles Snowflake attend entre les tentatives d’interrogation du catalogue Iceberg externe pour que les mises à jour des métadonnées soient actualisées automatiquement.

Valeurs : 30 à 86 400, inclus

Par défaut : 30 secondes

Fonctionnalité en avant-première

Disponible pour tous les comptes.

COMMENT = 'string_literal'

Chaîne (littéral) qui spécifie un commentaire pour l’intégration.

Par défaut : aucune valeur

Paramètres d’authentification REST (restAuthenticationParams)¶

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

• Les intégrations de catalogues fournissent un accès en lecture seule aux catalogues Iceberg externes.

• Vous ne pouvez pas modifier une intégration de catalogue existante ; utilisez plutôt une instruction CREATE OR REPLACE CATALOG INTEGRATION.

• Vous ne pouvez pas supprimer ni remplacer une intégration de catalogue si une ou plusieurs tables Apache Iceberg™ sont associées à l’intégration de catalogue.

  Pour voir les tables qui dépendent d’une intégration de catalogue, vous pouvez utiliser la commande SHOW ICEBERG TABLES et une requête utilisant RESULT_SCAN qui applique un filtre sur la colonne catalog_name.

  Note

  L’identificateur de colonne (catalog_name) est sensible à la casse. Spécifiez l’identificateur de colonne exactement tel il apparaît dans la sortie SHOW ICEBERG TABLES.

  Par exemple :

  SHOW ICEBERG TABLES;
  
  SELECT * FROM TABLE(
    RESULT_SCAN(
        LAST_QUERY_ID()
      )
    )
    WHERE "catalog_name" = 'my_catalog_integration_1';
  

  Copy

• Concernant les métadonnées :

  Attention

  Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

• Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

Exemples¶

L’exemple suivant crée une intégration REST de catalogue qui utilise OAuth pour se connecter à 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;