CREATE CATALOG INTEGRATION (Snowflake Open Catalog)¶

Crée une intégration de catalogue pour les tables Apache Iceberg qui s’intègre à Snowflake Open Catalog dans le compte ou remplace une intégration de catalogue existante.

Vous pouvez également utiliser cette commande pour créer une intégration de catalogue pour les tables Iceberg dans Apache Polaris™.

Voir aussi :: ALTER CATALOG INTEGRATION , DROP CATALOG INTEGRATION , SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION

Syntaxe¶

CATALOG_API_TYPE: PUBLIC¶

Utilisez cette intégration de catalogue pour connecter Snowflake à Open Catalog via l’internet public. La valeur par défaut du paramètre CATALOG_API_TYPE est PUBLIC, il n’est donc pas nécessaire de spécifier ce paramètre.

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>'
    [ CATALOG_API_TYPE = PUBLIC ]
    CATALOG_NAME = '<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

CATALOG_API_TYPE: PRIVATE¶

Si vous utilisez la connectivité privée pour le trafic réseau entrant dans Snowflake Open Catalog, utilisez cette intégration de catalogue pour connecter Snowflake à Open Catalog via une adresse IP privée.

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>'
    CATALOG_API_TYPE = PRIVATE
    CATALOG_NAME = '<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

Paramètres requis¶

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

Spécifie Snowflake Open Catalog comme source du catalogue.

TABLE_FORMAT = ICEBERG

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

REST_CONFIG = ( ... )

Spécifie des informations sur votre nom du compte Open Catalog et le nom du catalogue.

CATALOG_URI = 'https://open_catalog_account_url'
Votre compte Open Catalog : URL. Valeurs prises en charge :

https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog : lorsque CATALOG_API_TYPE = PUBLIC. Exemples de valeurs :

https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.com/polaris/api/catalog

https://<account_locator>.<cloud_region_id>.<cloud>.snowflakecomputing.com/polaris/api/catalog

Note

Pour trouver le nom de votre organisation Snowflake (<orgname>), suivez les étapes indiquées dans Recherche de l’organisation et du nom de compte pour un compte.

Pour trouver <my-snowflake-open-catalog-account-name, voir Trouver le nom d’un compte Snowflake Open Catalog dans la documentation Snowflake Open Catalog.

Pour trouver votre <account_locator>, <cloud_region_id>, et <cloud>, voir Format 2 : localisateur de compte dans une région.

https://<open_catalog_privatelink_account_url>/polaris/api/catalog : lorsque CATALOG_API_TYPE = PRIVATE.

Note

Pour <open_catalog_privatelink_account_url>, entrez l’une des valeurs suivantes :

Compte PrivateLink : URL

Compte PrivateLink sans région : URL

Pour obtenir ces valeurs, récupérez les paramètres de votre compte Open Catalog pour la connectivité privée. Pour plus de détails, consultez les instructions relatives à la plateforme Cloud où est hébergé votre compte Open Catalog :

AWS

Azure

CATALOG_API_TYPE = { PRIVATE | PUBLIC }
Spécifie le type d’API du catalogue. Si votre connexion entre Snowflake et Open Catalog doit être routée à travers l’internet public, ce paramètre est optionnel.

PRIVATE: Si vous utilisez la connectivité privée pour le trafic réseau entrant dans Snowflake Open Catalog, connecte Snowflake à Open Catalog via une adresse IP privée.

PUBLIC : connecte Snowflake à Open Catalog par l’intermédiaire de l’internet public.

Par défaut : PUBLIC

CATALOG_NAME = 'open_catalog_name'
Spécifie le nom du catalogue à utiliser dans Open Catalog.

REST_AUTHENTICATION = ( ... )

Spécifie les détails d’authentification que Snowflake utilise pour se connecter à Open Catalog.

TYPE = OAUTH: Spécifie OAuth comme type d’authentification à utiliser.
OAUTH_CLIENT_ID = 'oauth_client_id': L’ID client des identifiants OAuth2 associés à votre connexion de service Open Catalog.
OAUTH_CLIENT_SECRET = 'oauth_secret': Le secret des identifiants OAuth2 associés à votre connexion de service Open Catalog.
OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2'): La portée du jeton OAuth. Une seule portée est incluse dans la spécification REST API Iceberg, mais les catalogues peuvent prendre en charge plusieurs portées dans leur implémentation.

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. Les tables Iceberg existantes qui font référence à cette intégration fonctionnent normalement.

FALSE empêche les utilisateurs de créer de nouvelles tables Iceberg faisant référence à cette intégration. Les tables Iceberg existantes qui font référence à cette intégration ne peuvent pas accéder au catalogue dans la définition de la table.

Paramètres facultatifs¶

CATALOG_NAMESPACE = 'open_catalog_namespace'

Si vous créez l’intégration de catalogue pour interroger une table dans Snowflake Open Catalog à l’aide de Snowflake, vous pouvez éventuellement spécifier l’espace de noms à partir de Open Catalog. Snowflake utilise cet espace de noms pour toutes les tables Iceberg que vous associez à cette intégration de catalogue.

Si elle est spécifiée, vous pouvez remplacer cette valeur au niveau de la table lorsque vous créez une table. Si elle n’est pas spécifiée, vous devez paramétrer un espace de noms au niveau de la table lorsque vous créez une table.
Si vous créez l’intégration de catalogue pour synchroniser une table gérée par Snowflake avec Snowflake Open Catalog, ce paramètre n’a aucun effet sur la manière dont vous synchronisez la table avec Open Catalog. Snowflake synchronise la table avec le catalogue externe dans Open Catalog que vous spécifiez dans l’intégration du catalogue à l’aide d’une règle prédéfinie.

Par exemple, si vous avez une table Iceberg db1.public.table1 enregistrée dans Snowflake et que vous spécifiez catalog1 dans l’intégration du catalogue, Snowflake synchronise la table avec Open Catalog avec le nom pleinement qualifié suivant : catalog1.db1.public.table1.

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.

Pour les tables basées sur le Delta, spécifie le nombre de secondes que Snowflake attend entre les tentatives d’interrogation de votre stockage Cloud externe pour de nouvelles métadonnées.

Valeurs : 30 à 86 400, inclus

Par défaut : 30 secondes

COMMENT = 'string_literal'

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

Par défaut : aucune valeur

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¶

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 clauses OR REPLACE et IF NOT EXISTS s’excluent mutuellement. Elles ne peuvent pas être utilisées dans la même instruction.
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.

Pour résoudre les problèmes liés à la création d’une intégration de catalogue, consultez Impossible de créer une intégration de catalogue pour Open Catalog.

Exemples¶

L’exemple suivant crée une intégration de catalogue pour Open Catalog pour un espace de noms particulier dans un catalogue interne dans Open Catalog afin d’interroger les tables regroupées sous cet espace de noms dans Snowflake. Pour plus d’informations sur les catalogues internes dans Open Catalog, voir Types de catalogues dans la documentation 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'
    CATALOG_NAME = '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

L’exemple suivant crée une intégration de catalogue pour Open Catalog afin de synchroniser les tables gérées par Snowflake avec le catalogue customers dans Open Catalog, qui est un catalogue externe. Pour plus d’informations sur les catalogues externes dans Open Catalog, voir Types de catalogues dans la documentation Open Catalog.

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int2
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.com/polaris/api/catalog'
    CATALOG_NAME = '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