Tutoriel : Créez votre première table Apache Iceberg™¶

Ce que vous apprendrez¶

Dans ce tutoriel, vous apprendrez à effectuer ce qui suit :

• Créer et configurer un volume externe pour les tables Iceberg gérées par Snowflake. À des fins de démonstration, ce tutoriel crée un volume externe pour Amazon S3.

• Créer deux tables Iceberg qui utilisent Snowflake comme catalogue Iceberg (tables gérées par Snowflake).

• Insérer des données dans des tables Iceberg.

• Effectuer des requêtes dans les tables Iceberg.

• Supprimer des lignes d’une table Iceberg.

Conditions préalables¶

Avant de commencer, vous devez vous familiariser avec les éléments suivants :

• Identificateurs d’objets Snowflake et leurs exigences.

• Tables Apache Iceberg et Iceberg dans Snowflake. Pour plus d’informations, voir Tables Apache Iceberg™.

• Stockage d’objets dans le cloud.

• Si vous utilisez S3, vous devez connaître AWS Identity and Access Management (IAM) et les éléments de politiques IAM.

Vous avez besoin des éléments suivants :

• Un utilisateur de Snowflake avec un rôle qui a les privilèges pour effectuer les actions suivantes :

  • CREATE WAREHOUSE

  • CREATE DATABASE

  • CREATE EXTERNAL VOLUME

  • CREATE ICEBERG TABLE

  Si vous utilisez un compte d’essai de 30 jours, vous pouvez vous connecter en tant qu’utilisateur créé pour ce compte. Cet utilisateur a le rôle avec les privilèges nécessaires pour créer les objets.

  Si vous n’avez pas d’utilisateur ayant les autorisations nécessaires, demandez à quelqu’un qui les a d’en créer un pour vous. Les utilisateurs ayant le rôle ACCOUNTADMIN peuvent créer de nouveaux utilisateurs et leur accorder les privilèges requis.

• Accès administrateur pour votre fournisseur de stockage dans le Cloud afin de configurer un volume externe.

• Un compartiment de stockage (ou conteneur) chez le même fournisseur Cloud, dans la même région que celui qui héberge votre compte Snowflake.

• Accès à la base de données SNOWFLAKE_SAMPLE_DATA de votre compte. Par défaut, Snowflake crée la base de données d’exemple dans les nouveaux comptes. Si la base de données n’a pas été créée dans votre compte, voir Utilisation de la base de données d’échantillon.

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

Pour configurer les autorisations d’accès à Snowflake dans la Console de gestion AWS, procédez comme suit :

1. Connectez-vous à la console de gestion AWS.

2. Depuis le tableau de bord d’accueil, recherchez et sélectionnez IAM.

3. Dans le volet de navigation de gauche, sélectionnez Account settings.

4. Dans Security Token Service (STS), dans la liste Endpoints, recherchez la région Snowflake dans laquelle se trouve votre compte. Si STS status est inactif, placez la bascule sur Active.

5. Dans le volet de navigation de gauche, sélectionnez Policies.

6. Sélectionnez Create Policy.

   

7. Pour Policy editor, sélectionnez JSON.

8. Ajoutez une politique pour fournir à Snowflake les autorisations nécessaires pour lire et écrire des données sur votre emplacement S3.

   L’exemple de politique suivant accorde l’accès à tous les emplacements du compartiment spécifié.

   Note

   • Remplacez my_bucket par le nom de votre compartiment. Vous pouvez également spécifier un chemin dans le compartiment ; par exemple, my_bucket/path.

   • Si vous attribuez la valeur ["*"] à la condition "s3:prefix":, vous aurez accès à tous les préfixes du compartiment spécifié ; si vous attribuez la valeur ["path/*"], vous aurez accès à un chemin spécifié du compartiment.

   • Pour les compartiments des régions gouvernementales, les ARNs de compartiments utilisent le préfixe arn:aws-us-gov:s3:::.

   {
      "Version": "2012-10-17",
      "Statement": [
            {
               "Effect": "Allow",
               "Action": [
                  "s3:PutObject",
                  "s3:GetObject",
                  "s3:GetObjectVersion",
                  "s3:DeleteObject",
                  "s3:DeleteObjectVersion"
               ],
               "Resource": "arn:aws:s3:::<my_bucket>/*"
            },
            {
               "Effect": "Allow",
               "Action": [
                  "s3:ListBucket",
                  "s3:GetBucketLocation"
               ],
               "Resource": "arn:aws:s3:::<my_bucket>",
               "Condition": {
                  "StringLike": {
                        "s3:prefix": [
                           "*"
                        ]
                  }
               }
            }
      ]
   }
   

   Copy

9. Sélectionnez Next.

10. Saisissez un Policy name (par exemple, snowflake_access) et une Description facultative.

11. Sélectionnez Create policy.

Création d’un rôle IAM¶

Créez un rôle AWS IAM qui accorde des privilèges sur le compartiment S3 contenant vos fichiers de données.

1. Dans le volet de navigation gauche du tableau de bord de la gestion des identités et des accès (IAM), sélectionnez Roles.

2. Sélectionnez Create role.

3. Comme type d’entité de confiance, sélectionnez AWS account.

4. Sous An AWS account, sélectionnez This account. Dans une étape ultérieure, vous modifierez la relation de confiance et accorderez l’accès à Snowflake.

5. Sélectionnez l’option Require external ID. Saisissez un ID externe de votre choix. Par exemple, iceberg_table_external_id.

   Un ID externe est utilisé pour accorder l’accès à vos ressources AWS (telles que des compartiments S3) à un tiers comme Snowflake.

   

6. Sélectionnez Next.

7. Sélectionnez la politique que vous avez créée pour le volume externe, puis sélectionnez Next.

8. Saisissez un Role name et une description pour le rôle, puis sélectionnez Create role.

   Vous avez maintenant créé une politique IAM pour un emplacement S3, créé un rôle IAM et vous avez associé la politique au rôle.

9. Sélectionnez View role pour voir la page de résumé du rôle. Localisez et enregistrez la valeur de ARN (Amazon Resource Name) pour le rôle.

   

Créer un volume externe dans Snowflake¶

Créez un volume externe via la commande CREATE EXTERNAL VOLUME. L’exemple suivant crée un volume externe nommé iceberg_external_volume qui définit un emplacement de stockage Amazon S3 avec chiffrement.

CREATE OR REPLACE EXTERNAL VOLUME iceberg_external_volume
   STORAGE_LOCATIONS =
      (
         (
            NAME = 'my-s3-us-west-2'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://<my_bucket>/'
            STORAGE_AWS_ROLE_ARN = '<arn:aws:iam::123456789012:role/myrole>'
            STORAGE_AWS_EXTERNAL_ID = 'iceberg_table_external_id'
         )
      );

L’exemple spécifie l’ID de volume externe (iceberg_table_external_id) associé au rôle IAM que vous avez créé pour le volume externe. La spécification d’un ID externe vous permet d’utiliser le même rôle IAM (et ID externe) sur plusieurs volumes externes.

Récupérer l’utilisateur AWS IAM de votre compte Snowflake¶

1. Récupérez l’ARN de l’utilisateur IAM AWS automatiquement créé pour votre compte Snowflake avec la commande DESCRIBE EXTERNAL VOLUME. Indiquez le nom de votre volume externe.

   L’exemple suivant décrit un volume externe nommé iceberg_external_volume :

   DESC EXTERNAL VOLUME iceberg_external_volume;
   

   Copy

2. Enregistrez la valeur de la propriété STORAGE_AWS_IAM_USER_ARN, qui est l’utilisateur AWS IAM créé pour votre compte Snowflake ; par exemple, arn:aws:iam::123456789001:user/abc1-b-self1234.

   Snowflake provisionne un seul utilisateur IAM pour l’intégralité de votre compte Snowflake. Tous les volumes externes S3 de votre compte utilisent cet utilisateur IAM.

   Note

   Si vous n’avez pas spécifié d’ID externe (STORAGE_AWS_EXTERNAL_ID) lors de la création d’un volume externe, Snowflake génère un ID à utiliser. Enregistrez la valeur afin de pouvoir mettre à jour votre politique de confiance du rôle IAM avec l’ID de rôle externe généré.

Accorder des autorisations d’utilisateurs IAM pour accéder à des objets de compartiment¶

Dans cette étape, vous configurez les autorisations qui permettent à l’utilisateur IAM de votre compte Snowflake d’accéder aux objets de votre compartiment S3.

1. Connectez-vous à la console de gestion AWS.

2. Depuis le tableau de bord d’accueil, recherchez et sélectionnez IAM.

3. Dans le volet de navigation de gauche, sélectionnez Roles.

4. Sélectionnez le rôle IAM que vous avez créé pour votre volume externe.

5. Sélectionnez l’onglet Trust relationships.

6. Sélectionnez Edit trust policy.

7. Modifiez le document de politique en y ajoutant les valeurs de sortie DESC EXTERNAL VOLUME que vous avez enregistrées.

   

   Document de politique pour le rôle IAM

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<snowflake_user_arn>"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "<iceberg_table_external_id>"
           }
         }
       }
     ]
   }
   

   Copy

   Où :

   • snowflake_user_arn est la valeur STORAGE_AWS_IAM_USER_ARN que vous avez enregistrée.

   • iceberg_table_external_id est votre ID externe. Si vous avez déjà spécifié un ID externe lors de la création du rôle et que vous avez utilisé le même ID pour créer votre volume externe, laissez la valeur telle quelle. Sinon, mettez à jour sts:ExternalId avec la valeur que vous avez enregistrée.

   Note

   Vous devez mettre à jour ce document de politique si vous créez un nouveau volume externe (ou si vous recréez un volume externe existant via la syntaxe CREATE OR REPLACE EXTERNAL VOLUME) et que vous ne fournissez pas votre propre ID externe. Pour des raisons de sécurité, un volume externe nouveau ou recréé a un ID externe différent et ne peut pas résoudre la relation de confiance à moins que vous ne mettiez à jour cette politique de confiance.

8. Sélectionnez Update policy pour enregistrer vos modifications.

Créer un tableau en utilisant la syntaxe standard¶

Tout d’abord, créez une table Iceberg en utilisant la syntaxe standard CREATE ICEBERG TABLE.

Spécifiez CATALOG = 'SNOWFLAKE' pour que la table utilise Snowflake comme catalogue Iceberg.

Pour indiquer à Snowflake où écrire les données et métadonnées de la table, spécifiez une valeur pour le paramètre BASE_LOCATION. L’exemple définit le nom de table (customer_iceberg) comme BASE_LOCATION. De cette façon, Snowflake écrit les données et les métadonnées sous un répertoire portant le même nom que la table dans l’emplacement de votre volume externe.

CREATE OR REPLACE ICEBERG TABLE customer_iceberg (
    c_custkey INTEGER,
    c_name STRING,
    c_address STRING,
    c_nationkey INTEGER,
    c_phone STRING,
    c_acctbal INTEGER,
    c_mktsegment STRING,
    c_comment STRING
)
    CATALOG = 'SNOWFLAKE'
    EXTERNAL_VOLUME = 'iceberg_external_volume'
    BASE_LOCATION = 'customer_iceberg';

Plus loin dans le tutoriel, vous chargerez des données dans cette table à partir de la table snowflake_sample_data.tpch_sf1.customer de la base de données SNOWFLAKE_SAMPLE_DATA. Les définitions des colonnes dans l’instruction CREATE ICEBERG TABLE correspondent à la table d’exemple.

Définir l’intégration du catalogue et le volume externe de la base de données¶

Ensuite, définissez les paramètres CATALOG et EXTERNAL_VOLUME pour la iceberg_tutorial_db que vous avez créée dans ce tutoriel. La définition des paramètres indique à Snowflake d’utiliser le catalogue et le volume externe spécifiques que vous avez choisis pour toutes les tables Iceberg créées après la modification.

ALTER DATABASE iceberg_tutorial_db SET CATALOG = 'SNOWFLAKE';
ALTER DATABASE iceberg_tutorial_db SET EXTERNAL_VOLUME = 'iceberg_external_volume';

Pour vérifier, consultez les paramètres de la base de données actuelle (iceberg_tutorial_db) :

SHOW PARAMETERS IN DATABASE ;

Créer une table en utilisant CTAS¶

Enfin, créez une deuxième table Iceberg appelée nation_iceberg en utilisant la syntaxe CREATE ICEBERG TABLE … AS SELECT. Nous baserons la nouvelle table sur la table snowflake_sample_data.tpch_sf1.nation de la base de données d’exemple Snowflake.

CREATE OR REPLACE ICEBERG TABLE nation_iceberg (
  n_nationkey INTEGER,
  n_name STRING
)
  BASE_LOCATION = 'nation_iceberg'
  AS SELECT
    N_NATIONKEY,
    N_NAME
  FROM snowflake_sample_data.tpch_sf1.nation;