Premiers pas avec Snowflake Open Catalog¶

Ce que vous apprendrez¶

• Comment créer un nouveau compte Open Catalog.

• Comment créer un nouveau catalogue Iceberg dans le compte Open Catalog et le sécuriser à l’aide de RBAC.

• Comment utiliser Apache Spark™ pour créer des tables dans le catalogue et exécuter des requêtes.

• Comment utiliser Snowflake pour exécuter des requêtes sur les tables du catalogue.

• Comment mettre en miroir ou publier des tables Iceberg gérées dans Snowflake vers Open Catalog.

Ce dont vous aurez besoin¶

• Privilèges ORGADMIN dans votre organisation Snowflake (pour créer un nouveau compte Open Catalog).

• Privilèges ACCOUNTADMIN dans votre compte Snowflake (pour vous connecter au compte Open Catalog). Ce compte Snowflake ne doit pas nécessairement être le même que le compte de l’organisation Snowflake.

Ce que vous ferez¶

Vous effectuerez deux cas d’utilisation :

• Cas d’utilisation 1 : créer un catalogue dans Open Catalog, créer une table à l’aide d’Apache Spark et interroger la table à l’aide d’Apache Spark et de Snowflake.

  

• Cas d’utilisation 2 : créer une table Apache Iceberg dans le compte DB de Snowflake à l’aide de Snowflake et la publier dans Open Catalog afin qu’Apache Spark puisse y exécuter des requêtes.

  

Installez Conda, Spark et Jupyter sur votre ordinateur portable.¶

Dans ce tutoriel, vous pouvez utiliser Conda pour créer facilement un environnement de développement et télécharger les paquets nécessaires. Ceci n’est nécessaire que si vous suivez le cas d’utilisation 2 pour utiliser Apache Spark™ pour lire les tables Apache Iceberg™ gérées par Snowflake. Ceci n’est pas nécessaire pour créer ou utiliser des tables Iceberg sur Snowflake.

1. Pour installer Conda, utilisez les instructions propres à votre OS :

   • Mac

   • Windows

   • Linux

2. Créer un fichier nommé environnement.yml avec le contenu suivant :

   name: iceberg-lab
   channels:
     - conda-forge
   dependencies:
     - findspark=2.0.1
     - jupyter=1.0.0
     - pyspark=3.5.0
     - openjdk=11.0.13
   

   Copy

3. Pour créer l’environnement nécessaire, exécutez ce qui suit dans votre shell :

   conda env create -f environment.yml
   

   Copy

Création d’un compte Open Catalog¶

Un compte Open Catalog peut être créé uniquement par un ORGADMIN.

1. Dans Snowsight, dans le volet de navigation, sélectionnez Admin> Comptes.

2. Dans la liste déroulante + Compte, sélectionnez Créer un compte Snowflake Open Catalog.

3. Renseignez la boîte de dialogue Créer un compte Snowflake Open Catalog :

   • Cloud : fournisseur Cloud où vous souhaitez stocker les tables Apache Iceberg™.

   • Région : région dans laquelle vous souhaitez stocker les tables Iceberg.

   • Édition : édition pour votre compte Open Catalog.

4. Sélectionnez Suivant.

5. Dans la boîte de dialogue Créer un nouveau compte, remplissez les champs Nom du compte, Nom d’utilisateur, Mot de passe et E-mail.

6. Sélectionnez Créer un compte. Votre nouveau compte Open Catalog est créé et une boîte de confirmation apparaît.

7. Dans la boîte de confirmation, sélectionnez l”URL du localisateur de compte pour ouvrir l’URL du localisateur de compte dans votre navigateur Web.

8. Ajoutez l’URL du localisateur de compte à vos favoris. Lors de la connexion à Open Catalog, vous devez spécifier l’URL du localisateur de compte.

Connexion à l’interface Web Open Catalog¶

1. Cliquez sur l’URL du compte que vous avez reçue par e-mail après la création du compte, OR allez sur https://app.snowflake.com.

2. Cliquez sur Se connecter à un autre compte et connectez-vous avec le compte Open Catalog créé précédemment.

Créer une politique IAM qui accorde l’accès à votre emplacement S3¶

Si vous n’en avez pas déjà une, commencez par créer une politique IAM qui accorde l’accès à votre emplacement S3. Pour obtenir des instructions sur la création de cette politique, voir Créer une politique IAM qui accorde l’accès à votre emplacement S3.

Création d’un rôle IAM¶

Si vous n’en avez pas déjà un, créez un rôle AWS IAM pour Open Catalog qui accorde des privilèges sur le compartiment S3. Pour obtenir des instructions, voir Créer un rôle IAM. Lorsque les instructions vous invitent à sélectionner une politique, sélectionnez la politique IAM qui accorde l’accès à votre emplacement S3.

Création d’un catalogue interne dans Open Catalog¶

Vous pouvez utiliser un catalogue interne dans votre compte Open Catalog pour créer des tables, les interroger et exécuter des opérations DML dans les tables à l’aide d’Apache Spark™ ou d’autres moteurs de recherche.

1. Connectez-vous à votre nouveau compte Open Catalog.

2. Pour créer un nouveau catalogue, dans le volet de gauche, sélectionnez Catalogues.

3. Sélectionnez + Catalogue en haut à droite.

4. Dans la boîte de dialogue Créer un catalogue, saisissez les détails suivants :

   • Emplacement de base par défaut : emplacement où les données de la table seront stockées.

   • Emplacements supplémentaires (facultatif) : liste séparée par des virgules de plusieurs emplacements de stockage. Cette liste est principalement utilisée si vous devez importer des tables à partir de différents emplacements dans ce catalogue. Vous n’êtes pas obligé de la renseigner.

   • ARN du rôle S3 : rôle AWS qui dispose d’un accès en lecture et écriture aux emplacements de stockage. Saisissez l’ARN du rôle IAM que vous avez créé pour Open Catalog.

   • **ID externe : (facultatif) : ** secret que vous souhaitez indiquer lors de la création d’une relation de confiance entre l’utilisateur du catalogue et le compte de stockage. Si vous ignorez cette étape, elle sera générée automatiquement. Utilisez une chaîne simple comme abc123 pour ce tutoriel.

5. Sélectionnez Créer. Votre catalogue est créé et les valeurs suivantes sont ajoutées à votre catalogue :

   • arn de l’utilisateur IAM pour votre compte Open Catalog.

   • Si vous n’avez pas saisi d’ID externe, un ID externe est généré automatiquement pour votre catalogue.

   Vous aurez besoin de ces valeurs dans la section suivante lorsque vous créerez une relation de confiance.

Création d’une relation de confiance¶

Après avoir créé un catalogue, vous devez configurer une relation de confiance afin que le rôle S3 spécifié dans la configuration ci-dessus puisse lire et écrire des données dans l’emplacement de stockage. Notez que pour réaliser cette tâche, vous aurez besoin de l’arn de l’utilisateur IAM S3 et de l’ID externe pour votre catalogue.

1. Une fois le catalogue créé, sélectionnez votre catalogue dans la liste pour afficher l’arn de l’utilisateur IAM S3 et l’ID externe pour votre catalogue.

2. Pour créer la relation de confiance, exécutez Étape 5 : octroyer à l’utilisateur IAM des autorisations pour accéder à des objets de compartiment.

Dans l’objet JSON affiché dans ces instructions :

• Pour <open_catalog_user_arn>, utilisez la valeur sous arn de l’utilisateur IAM dans l’UI d’Open Catalog.

• Pour <open_catalog_external_id>, utilisez la valeur sous ID externe dans l’UI d’Open Catalog.

Création d’une nouvelle connexion pour Apache Spark™¶

Créez une nouvelle connexion (paire client_id/client_secret) pour qu’Apache Spark exécute des requêtes sur le catalogue que vous venez de créer.

1. Dans Open Catalog, dans le volet de gauche, sélectionnez l’onglet Connexions, puis sélectionnez + Connexion en haut à droite.

2. Dans la boîte de dialogue Configurer la connexion de service, créez un nouveau rôle principal ou choisissez l’un des rôles disponibles.

3. Sélectionnez Créer.

4. Dans la boîte de dialogue Configurer la connexion de service, pour copier l’ID client et le secret client dans un éditeur de texte, sélectionnez Copier dans le champ En tant que <CLIENT ID>:<SECRET>.

   Important

   Vous ne pourrez pas récupérer ces chaînes de texte à partir du service Open Catalog ultérieurement, vous devez donc les copier maintenant. Vous utilisez ces chaînes de texte lorsque vous configurez Spark.

Configuration des privilèges du catalogue pour la connexion¶

Vous accordez maintenant des privilèges à la connexion de service afin qu’elle puisse accéder au catalogue. Sans privilèges d’accès, la connexion de service ne peut exécuter aucune requête sur le catalogue.

1. Dans le volet de navigation, sélectionnez Catalogues, puis sélectionnez votre catalogue dans la liste.

2. Pour créer un nouveau rôle, sélectionnez l’onglet Rôles.

3. Sélectionnez + Rôle de catalogue.

4. Dans la boîte de dialogue Créer un rôle de catalogue, pour Nom, saisissez spark_catalog_role.

5. Pour Privilèges, sélectionnez CATALOG_MANAGE_CONTENT, puis sélectionnez Créer.

   Cette action permet d’attribuer au rôle les privilèges de créer, de lire et d’écrire dans les tables.

6. Sélectionnez Accorder au rôle principal.

7. Dans la boîte de dialogue Accorder le rôle de catalogue, pour Rôle principal recevant l’attribution, sélectionnez my_spark_admin_role.

8. Pour Rôle de catalogue à accorder, sélectionnez spark_catalog_role, puis sélectionnez Accorder.

À la suite de cette procédure, le rôle spark_catalog_role est accordé à my_spark_admin_role, ce qui attribue des privilèges d’administrateur pour la connexion Spark que vous avez créée dans la procédure précédente.

Configuration de Spark¶

Depuis votre terminal, exécutez les commandes suivantes pour activer l’environnement virtuel que vous avez créé lors de la configuration et ouvrez Jupyter Notebooks :

conda activate iceberg-lab
jupyter notebook

Mise en place de Spark¶

Pour configurer Spark, exécutez ces commandes dans Jupyter Notebook.

Pour plus d’informations, y compris les descriptions des paramètres, voir Enregistrement d’une connexion de service dans Spark.

import os
os.environ['SPARK_HOME'] = '/Users/<username>/opt/anaconda3/envs/iceberg-lab/lib/python3.12/site-packages/pyspark'

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
.config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.config('spark.sql.defaultCatalog', 'opencatalog') \
.config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
.config('spark.sql.catalog.opencatalog.type', 'rest') \
.config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
.config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog') \
.config('spark.sql.catalog.opencatalog.credential','<client_id>:<client_secret>') \
.config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
.config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
.getOrCreate()

#Show namespaces
spark.sql("show namespaces").show()

#Create namespace
spark.sql("create namespace spark_demo")

#Use namespace
spark.sql("use namespace spark_demo")

#Show tables; this will show no tables since it is a new namespace
spark.sql("show tables").show()

#create a test table
spark.sql("create table test_table (col1 int) using iceberg");

#insert a record in the table
spark.sql("insert into test_table values (1)");

#query the table
spark.sql("select * from test_table").show();

.config('spark.sql.catalog.opencatalog.client.region','<region_code>') \

import pyspark
from pyspark.sql import SparkSession

spark = SparkSession.builder.appName('iceberg_lab') \
.config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.config('spark.sql.defaultCatalog', 'opencatalog') \
.config('spark.sql.catalog.opencatalog', 'org.apache.iceberg.spark.SparkCatalog') \
.config('spark.sql.catalog.opencatalog.type', 'rest') \
.config('spark.sql.catalog.opencatalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
.config('spark.sql.catalog.opencatalog.uri','https://<open_catalog_account_identifier>.snowflakecomputing.com/polaris/api/catalog') \
.config('spark.sql.catalog.opencatalog.credential','<client_id>:<secret>') \
.config('spark.sql.catalog.opencatalog.warehouse','<catalog_name>') \
.config('spark.sql.catalog.opencatalog.scope','PRINCIPAL_ROLE:<principal_role_name>') \
.config('spark.sql.catalog.opencatalog.client.region','<region_code>') \
.getOrCreate()

Interrogation de tables à l’aide de Snowflake¶

Vous pouvez créer un objet d’intégration de catalogue dans Snowflake et créer une table Apache Iceberg™ dans Snowflake qui représente la table dans Open Catalog. Dans l’exemple suivant, vous créez une table Iceberg dans Snowflake qui représente la table Iceberg qui vient d’être créée par Spark dans le catalogue interne d’Open Catalog.

Vous pouvez utiliser les mêmes informations d’identification de connexion Spark ou créer une nouvelle connexion Snowflake. Si vous créez une nouvelle connexion, vous devez configurer les rôles et les privilèges en conséquence.

1. Création d’un objet d’intégration de catalogue :

   CREATE OR REPLACE CATALOG INTEGRATION demo_open_catalog_int 
   CATALOG_SOURCE=POLARIS 
   TABLE_FORMAT=ICEBERG 
   CATALOG_NAMESPACE='<catalog_namespace>' 
   REST_CONFIG = (
   CATALOG_URI ='https://<account>.snowflakecomputing.com/polaris/api/catalog' 
   WAREHOUSE = ‘<catalog_name>’
   )
   REST_AUTHENTICATION = (
   TYPE=OAUTH 
   OAUTH_CLIENT_ID='<client_id>' 
   OAUTH_CLIENT_SECRET='<secret>' 
   OAUTH_ALLOWED_SCOPES=('PRINCIPAL_ROLE:ALL') 
   ) 
   ENABLED=true;
   
   # the <catalog_namespace> created in previous step is spark_demo.
   # the <catalog_name> created in previous step is demo_catalog.
   

   Copy

2. Créez la représentation de table dans Snowflake à l’aide de l’intégration de catalogue créée ci-dessus et interrogez la table :

   create or replace iceberg table test_table
     catalog = 'demo_open_catalog_int'
     external_volume = '<external_volume>'
     catalog_table_name = 'test_table'
   
   select * from test_table;
   

   Copy

Création d’un catalogue externe dans Open Catalog¶

Les tables Iceberg de Snowflake peuvent être synchronisées dans un catalogue externe dans votre compte Open Catalog.

1. Connectez-vous à votre nouveau compte Open Catalog.

2. Pour créer un nouveau catalogue, dans le volet de gauche, sélectionnez Catalogues.

3. Sélectionnez + Catalogue en haut à droite.

4. Dans la boîte de dialogue Créer un catalogue, saisissez les détails suivants :

   • Nom : nommez le catalogue demo_catalog_ext.

   • Réglez le bouton bascule pour Externe sur Activé.

   • Emplacement de base par défaut : emplacement où les données de la table seront stockées.

     Remarque

     Vous devez utiliser un emplacement de stockage différent de celui du catalogue interne que vous avez créé lors du cas d’utilisation 1 de ce tutoriel. Pour garantir que les privilèges d’accès définis pour un catalogue sont appliqués correctement, deux catalogues différents ne peuvent pas avoir d’emplacements qui se chevauchent.

   • Emplacements supplémentaires (facultatif) : liste séparée par des virgules de plusieurs emplacements de stockage. Cette liste est principalement utilisée si vous devez importer des tables à partir de différents emplacements dans ce catalogue. Vous n’êtes pas obligé de la renseigner.

   • ARN du rôle S3 : rôle AWS qui dispose d’un accès en lecture et écriture aux emplacements de stockage.

   • **ID externe : (facultatif) : ** secret que vous souhaitez indiquer lors de la création d’une relation de confiance entre l’utilisateur du catalogue et le compte de stockage. Si vous ignorez cette étape, elle sera générée automatiquement. Utilisez une chaîne simple comme abc123 pour ce tutoriel.

5. Sélectionnez Créer. Les valeurs suivantes sont ajoutées à votre catalogue :

   • arn de l’utilisateur IAM pour votre compte Open Catalog.

   • Si vous n’avez pas saisi d’ID externe, un ID externe est généré automatiquement pour votre catalogue.

Création d’une connexion pour Snowflake¶

1. Dans Open Catalog, dans le volet de gauche, sélectionnez l’onglet Connexions, puis sélectionnez + Connexion en haut à droite.

2. Dans la boîte de dialogue Configurer la connexion de service, créez un nouveau rôle principal ou choisissez l’un des rôles disponibles.

3. Sélectionnez Créer.

4. Dans la boîte de dialogue Configurer la connexion de service, pour copier l’ID client et le secret client dans un éditeur de texte, sélectionnez Copier dans le champ En tant que <CLIENT ID>:<SECRET>.

   Important

   Vous ne pourrez pas récupérer ces chaînes de texte à partir du service Open Catalog ultérieurement, vous devez donc les copier maintenant. Vous utilisez ces chaînes de texte lorsque vous configurez Spark.

Configuration des privilèges du catalogue¶

Pour configurer des privilèges sur le catalogue externe afin que la connexion Snowflake dispose des privilèges appropriés pour un catalogue externe, procédez comme suit :

1. Dans le volet de navigation, sélectionnez Catalogues, puis sélectionnez votre catalogue externe dans la liste.

2. Pour créer un nouveau rôle, sélectionnez l’onglet Rôles.

3. Sélectionnez + Rôle de catalogue.

4. Dans la boîte de dialogue Créer un rôle de catalogue, pour Nom, saisissez spark_catalog_role.

5. Pour Privilèges, sélectionnez CATALOG_MANAGE_CONTENT, puis sélectionnez Créer.

   Cette action permet d’attribuer au rôle les privilèges de créer, de lire et d’écrire dans les tables.

6. Sélectionnez Accorder au rôle principal.

7. Dans la boîte de dialogue Accorder le rôle de catalogue, pour Rôle principal recevant l’attribution, sélectionnez my_spark_admin_role.

8. Pour Rôle de catalogue à accorder, sélectionnez spark_catalog_role, puis sélectionnez Accorder.

Création d’un objet d’intégration de catalogue dans Snowflake¶

1. Dans Snowflake, créez un objet d’intégration de catalogue à l’aide de la commande CREATE CATALOG INTEGRATION (Snowflake Open Catalog) :

   CREATE OR REPLACE CATALOG INTEGRATION demo_open_catalog_ext 
     CATALOG_SOURCE=POLARIS 
     TABLE_FORMAT=ICEBERG 
     CATALOG_NAMESPACE='default' 
     REST_CONFIG = (
       CATALOG_URI ='https://<account>.snowflakecomputing.com/polaris/api/catalog' 
       WAREHOUSE = '<catalog_name>'
     )
     REST_AUTHENTICATION = (
       TYPE=OAUTH 
       OAUTH_CLIENT_ID='<client_id>' 
       OAUTH_CLIENT_SECRET='<secret>' 
       OAUTH_ALLOWED_SCOPES=('PRINCIPAL_ROLE:ALL') 
     ) 
     ENABLED=true;
   
   # the <catalog_name> created in previous step is demo_catalog_ext.
   

   Copy

   Dans ce code, chaque fois qu’une table Iceberg gérée dans le schéma Snowflake polaris_demo.iceberg est modifiée, elle est synchronisée avec Open Catalog afin que d’autres moteurs puissent interroger ces tables.

2. Créez une table Iceberg gérée et synchronisez-la depuis Snowflake avec Open Catalog. Pour plus d’informations, voir :

   • Configuration d’un volume externe pour Amazon S3

   • CREATE ICEBERG TABLE (Snowflake comme catalogue Iceberg)

   Important

   L”STORAGE_BASE_URL pour le volume externe doit correspondre à l”emplacement de base par défaut pour le catalogue externe que vous avez créé dans Open Catalog.

   use database polaris_demo;
   use schema iceberg;
   
   # Note that the storage location for this external volume will be different than storage location for external volume in use case 1
   
   CREATE OR REPLACE EXTERNAL VOLUME snowflake_demo_ext
     STORAGE_LOCATIONS =
         (
           (
               NAME = '<storage_location_name>'
               STORAGE_PROVIDER = 'S3'
               STORAGE_BASE_URL = 's3://<s3_location>'
               STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::<aws_acct>:role/<rolename>'
               STORAGE_AWS_EXTERNAL_ID = '<external_id>'
           )
         );
   
   CREATE OR REPLACE ICEBERG TABLE test_table_managed (col1 int)
     CATALOG = 'SNOWFLAKE'
     EXTERNAL_VOLUME = 'snowflake_demo_ext'
     BASE_LOCATION = 'test_table_managed'
     CATALOG_SYNC = 'demo_open_catalog_ext'; 
   

   Copy

Remarque

Si la table ne parvient pas à se synchroniser avec Open Catalog, exécutez la fonction système SYSTEM$SEND_NOTIFICATIONS_TO_CATALOG pour diagnostiquer la raison de l’échec de la synchronisation. Pour plus d’informations, voir SYSTEM$SEND_NOTIFICATIONS_TO_CATALOG.

Ce que vous avez appris¶

• Créer un compte Open Catalog.

• Créer un catalogue interne dans votre compte Open Catalog.

• Utiliser Spark pour créer des tables sur le catalogue interne.

• Utiliser Snowflake pour créer une intégration de catalogue pour Open Catalog afin d’exécuter des requêtes sur une table créée sur un catalogue interne dans votre compte Open Catalog.

• Créer un catalogue externe dans votre compte Open Catalog.

• Créer une table Apache Iceberg™ gérée dans Snowflake et la synchroniser avec le catalogue externe dans votre compte Open Catalog.

Ressources associées¶

• Documentation des tables Snowflake Iceberg

• Référentiel GitHub Apache Polaris (incubation)

• Documentation Apache Iceberg