CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)

Crée une intégration du catalogue dans le compte ou remplace une intégration de catalogue existante pour les Tables Apache Iceberg™ gérées dans un catalogue distant conforme à la spécification open source OpenAPI Apache Iceberg REST.

Note

Pour créer une intégration pour Snowflake Open Catalog, voir CREATE CATALOG INTEGRATION (Snowflake Open Catalog) plutôt.

Voir aussi :

ALTER CATALOG INTEGRATION , DROP CATALOG INTEGRATION , SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION

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

Où :

restConfigParams ::=

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

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

Jeton du porteur

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'
Copy

SigV4

restAuthenticationParams (for SigV4) ::=

  TYPE = SIGV4
  SIGV4_IAM_ROLE = '<iam_role_arn>'
  [ SIGV4_SIGNING_REGION = '<region>' ]
  [ SIGV4_EXTERNAL_ID = '<external_id>' ]
Copy

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 un espace de noms au niveau de la table à l’aide du paramètre CATALOG_NAMESPACE pour CREATE ICEBERG TABLE (catalogue Iceberg REST).

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 de configuration REST (restConfigParams)

CATALOG_URI = 'rest_api_endpoint_url'

L’URL de point de terminaison pour votre catalogue REST API. Pour AWS Glue REST, indiquez le point de terminaison de service pour le catalogue AWS Glue Iceberg REST.

PREFIX

Spécifie éventuellement un préfixe à ajouter à tous les itinéraires API.

CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY | AWS_GLUE }

Spécifie le type de connexion pour l’API du catalogue. Obligatoire pour l’authentification SigV4 ; sinon, ce paramètre est facultatif.

  • PUBLIC spécifie une API qui est accessible au public et qui n’est pas gérée avec Amazon API Gateway ; utilisé pour les APIs non SigV4.

  • AWS_API_GATEWAY spécifie une API publique gérée avec Amazon API Gateway.

  • AWS_PRIVATE_API_GATEWAY spécifie une API privée gérée avec Amazon API Gateway.

  • AWS_GLUE spécifie le catalogue AWS Glue REST. Avec cette option, vous devez également spécifier une valeur pour WAREHOUSE.

Par défaut : PUBLIC

WAREHOUSE

Spécifie l’emplacement de l’entrepôt (catalogue) ou l’identifiant à demander auprès de votre service de catalogue distant.

Lorsque vous utilisez CATALOG_API_TYPE = AWS_GLUE, indiquez l’ID de votre compte AWS pour ce paramètre.

Ce paramètre est exigé par certains services de catalogue tiers. Vérifiez auprès de votre fournisseur de catalogue si vous devez spécifier un entrepôt.

Paramètres d’authentification REST (restAuthenticationParams)

OAuth

TYPE = OAUTH

Spécifie OAuth comme type d’authentification à utiliser par Snowflake pour la connexion à votre catalogue Iceberg REST.

OAUTH_TOKEN_URI = token_server_uri

Facultatif URL de votre fournisseur d’identité tiers. Si non spécifié, Snowflake suppose que le fournisseur de catalogue distant est le fournisseur d’identité OAuth.

OAUTH_CLIENT_ID = oauth_client_id

Votre ID de client OAuth2.

OAUTH_CLIENT_SECRET = oauth_client_secret

Votre secret client OAuth2.

OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2' )

La portée du jeton OAuth. La spécification API Iceberg REST n’inclut qu’une seule portée, mais les catalogues peuvent prendre en charge plusieurs portées dans leur implémentation.

Jeton du porteur

TYPE = BEARER

Spécifie un jeton du porteur comme type d’authentification que Snowflake doit utiliser pour se connecter à votre catalogue Iceberg REST.

BEARER_TOKEN = bearer_token

Le jeton du porteur de votre fournisseur d’identité. Vous pouvez également spécifier un jeton d’accès personnel (PAT).

SigV4

TYPE = SIGV4

Spécifie la version de signature 4 comme type d’authentification à utiliser par Snowflake pour la connexion à votre catalogue Iceberg REST.

SIGV4_IAM_ROLE = 'iam_role_arn'

Spécifie le nom de la ressource Amazon (ARN) pour un rôle IAM qui a l’autorisation d’accéder à votre REST API dans API Gateway.

SIGV4_SIGNING_REGION = 'region'

Spécifie éventuellement la région AWS associée à votre API dans API Gateway. Si vous ne spécifiez pas ce paramètre, Snowflake utilise la région dans laquelle votre compte Snowflake est déployé.

SIGV4_EXTERNAL_ID = 'external_id'

Spécifie optionnellement un ID externe que Snowflake utilise pour établir une relation de confiance avec AWS. Vous devez spécifier le même ID externe dans la politique de confiance du rôle IAM que vous avez configuré pour cette intégration de catalogue.

Si vous ne spécifiez pas de valeur pour ce paramètre, Snowflake génère automatiquement un ID externe unique lorsque vous créez (ou remplacez) une intégration de catalogue.

Pour plus d’informations sur les IDs externes, voir Comment utiliser un ID externe lorsque vous accordez l’accès à vos ressources AWS à un tiers.

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

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

Privilège

Objet

Remarques

CREATE INTEGRATION

Compte

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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. Il définit un espace de noms par défaut à l’aide du paramètre CATALOG_NAMESPACE.

Pour remplacer l’espace de noms par défaut au niveau de la table, utilisez le paramètre CATALOG_NAMESPACE pour CREATE ICEBERG TABLE.

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;
Copy

Créer une intégration de catalogue pour AWS Glue REST avec l’authentification SigV4 :

CREATE CATALOG INTEGRATION glue_rest_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'rest_catalog_integration'
  REST_CONFIG = (
    CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_GLUE
    WAREHOUSE = '123456789012'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
    SIGV4_SIGNING_REGION = 'us-west-2'
  )
  ENABLED = TRUE;
Copy

Pour des exemples qui traitent des autres options d’authentification, voir Configuration d’une intégration de catalogue pour les catalogues Apache Iceberg™ REST.

Langage: Français