Prise en charge de l’écriture des tables Apache Iceberg™ gérées en externe

La prise en charge de l’écriture des Tables Apache Iceberg™ gérées en externe vous permet d’effectuer des opérations d’écriture sur des tables gérées par un catalogue REST Iceberg externe. La table Iceberg dans Snowflake est liée à une table dans votre catalogue distant. Lorsque vous apportez des modifications à la table dans Snowflake, Snowflake valide les mêmes modifications dans votre catalogue distant.

Cette fonction de prévisualisation étend l’interopérabilité entre Snowflake et les systèmes tiers, vous permettant d’utiliser Snowflake pour les charges de travail d’ingénierie des données avec Iceberg, même lorsque vous utilisez un catalogue Iceberg externe.

Les principaux cas d’utilisation sont les suivants :

  • Création de pipelines d’ingénierie des données complexes avec des tables Iceberg : L’écriture dans des tables Iceberg dans des catalogues externes à partir de Snowflake vous permet d’utiliser Snowpark ou Snowflake SQL pour créer des pipelines complexes qui ingèrent, transforment et traitent les données des tables Iceberg. Vous pouvez interroger les données en utilisant Snowflake ou d’autres moteurs. De même, vous pouvez utiliser les outils partenaires de Snowflake pour construire vos pipelines d’ingénierie des données Iceberg.

  • Mise à disposition de vos données pour l’écosystème Iceberg : La possibilité d’écrire dans des tables Iceberg dans les catalogues externes vous permet de mettre vos données à la disposition de l’écosystème Iceberg. Vous pouvez interroger des données déjà présentes dans Snowflake et les écrire dans des tables Iceberg. Pour que vos tables Iceberg restent synchronisées avec vos tables Snowflake, vous pouvez utiliser des opérations comme INSERT INTO … SELECT FROM pour effectuer les actions suivantes :

    • Copier des données existantes d’une table Snowflake standard vers une table Iceberg

    • Insérer des données avec des flux Snowflake

Considérations

Tenez compte des points suivants lorsque vous utilisez la prise en charge de l’écriture des tables Iceberg gérées en externe :

  • Snowflake fournit des commandes de langage de définition de données (DDL) et de langage de manipulation de données (DML) pour les tables gérées en externe. Cependant, vous configurez les métadonnées et la conservation des données à l’aide de votre catalogue externe et des outils fournis par votre fournisseur de stockage externe. Pour plus d’informations, voir Tables utilisant un catalogue externe.

    Pour les écritures, Snowflake s’assure que les modifications sont validées dans votre catalogue distant avant de mettre à jour la table dans Snowflake.

  • Si vous utilisez une base de données liée à un catalogue, vous pouvez utiliser la syntaxe CREATE ICEBERG TABLE avec des définitions de colonnes pour créer une table dans Snowflake et dans votre catalogue distant. Si vous utilisez une base de données Snowflake standard (non liée à un catalogue), vous devez d’abord créer une table dans votre catalogue distant. Après cela, vous pouvez utiliser la syntaxe CREATE ICEBERG TABLE (catalogue Iceberg REST) pour créer une table Iceberg dans Snowflake et écrire dedans.

  • Pour le Catalogue de données AWS Glue : La suppression d’une table gérée en externe via Snowflake ne supprime pas les fichiers de table sous-jacents. Ce comportement est spécifique à la mise en œuvre du Catalogue de données AWS Glue.

  • Si vous avez participé à la prévisualisation privée de cette fonctionnalité, les suppressions au niveau des lignes de position peuvent être activées par défaut dans votre compte. Pour le vérifier, exécutez la commande suivante :

    SHOW PARAMETERS LIKE 'ENABLE_ICEBERG_MERGE_ON_READ' IN ACCOUNT;
    
    Copy

    Si le paramètre est visible dans votre compte (quelle que soit sa valeur), les suppressions de position sont activées. Pour désactiver les suppressions de position, définissez le paramètre ENABLE_ICEBERG_MERGE_ON_READ sur FALSE au niveau de la table, du schéma ou de la base de données.

  • L’écriture dans des tables gérées en externe avec les types de données Iceberg suivants n’est pas prise en charge :

    • uuid

    • fixed(L)

  • Les fonctionnalités suivantes ne sont actuellement pas prises en charge lorsque vous utilisez Snowflake pour écrire dans des tables Iceberg gérées en externe :

    • Identifiants de connexion distribués par le catalogue

    • Chiffrement côté serveur (SSE) pour les volumes externes GCS ou Azure

    • Transactions à plusieurs instructions. Snowflake ne prend en charge que les transactions à validation automatique.

    • Conversion en tables gérées par Snowflake

    • Catalogues Iceberg externes non conformes au protocole REST Iceberg

    • Suppressions au niveau des lignes (fusion en lecture)

    • Utilisation de l’option OR REPLACE lors de la création d’une table

    • Utilisation de la syntaxe CREATE TABLE … AS SELECT si vous utilisez AWS Glue comme catalogue distant

  • Pour la création de schémas dans une base de données liée à un catalogue, tenez compte des points suivants :

    • La commande CREATE SCHEMA crée un espace de noms correspondant dans votre catalogue distant uniquement lorsque vous utilisez une base de données liée au catalogue.

    • Les options ALTER et CLONE ne sont pas prises en charge.

    • Les délimiteurs ne sont pas pris en charge pour les noms de schéma. Seuls les noms de schéma alphanumériques sont pris en charge.

Workflow

Utilisez le workflow de cette section pour commencer à utiliser cette fonctionnalité :

  1. Configurer un volume externe

  2. Créer une intégration de catalogue

  3. Choisissez parmi les options suivantes :

    • Créer une base de données liée à un catalogue Avec cette option, vous pouvez écrire dans des tables Iceberg découvertes automatiquement dans votre catalogue ou utiliser la base de données liée au catalogue pour créer des tables Iceberg supplémentaires.

    • Créer une table Iceberg (dans une base de données liée à un catalogue ou dans une base de données Snowflake standard) Avec cette option, vous devez d’abord créer une table dans votre catalogue distant avant de créer une table Iceberg gérée en externe dans Snowflake.

Une fois ces étapes achevées, vous pouvez exécuter des opérations d’écriture sur vos tables Iceberg.

Configuration d’un volume externe pour des écritures dans des tables gérées en externe

Pour activer les écritures dans des tables gérées en externe, vous devez utiliser un volume externe configuré avec des autorisations de lecture et d’écriture pour le principal de service Snowflake (les mêmes autorisations que celles requises pour les tables gérées par Snowflake).

Indiquez l’emplacement de stockage (STORAGE_BASE_URL) où votre catalogue REST Iceberg écrit des données et des métadonnées Iceberg.

Par exemple, l’instruction suivante crée un volume externe pour S3 avec un chiffrement qui permet un accès en écriture à un compartiment nommé my-iceberg-tables :

CREATE OR REPLACE EXTERNAL VOLUME my_external_volume
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-s3-us-west-2'
        STORAGE_PROVIDER = 'S3'
        STORAGE_BASE_URL = 's3://my-iceberg-tables/'
        STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-write-access-role'
        ENCRYPTION = ( TYPE = 'AWS_SSE_S3' )
      )
    )
  ALLOW_WRITES = TRUE;
Copy

Note

Vous devez configurer le volume externe avec des autorisations de lecture et d’écriture et définir le paramètre ALLOW_WRITES sur TRUE.

Pour obtenir des instructions, reportez-vous aux rubriques suivantes :

Pour plus d’informations sur les autorisations requises, consultez Accord à Snowflake l’accès à votre stockage.

Configuration d’une intégration de catalogue

Pour l’écriture dans des tables Iceberg gérées en externe, vous devez configurer une intégration de catalogue pour connecter Snowflake à votre catalogue distant.

Votre catalogue distant doit être conforme à la spécification open source `Apache REST Iceberg OpenAPI<https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml>`_, par exemple Open Catalog, ou au catalogue REST Iceberg AWS Glue.

Pour créer une intégration de catalogue, consultez les instructions des rubriques suivantes :

Créer une base de données liée à un catalogue

Snowflake prend en charge la création de tables gérées en externe et accessibles en écriture dans une base de données liée à un catalogue, qui est une base de données Snowflake que vous synchronisez avec un catalogue REST Iceberg externe. Vous pouvez également écrire dans des tables Iceberg que Snowflake découvre automatiquement dans votre catalogue distant. Pour plus d’informations, voir Utiliser une base de données liée à un catalogue pour les tables Apache Iceberg™.

Note

Vous pouvez également créer des tables Iceberg gérées en externe et accessibles en écriture dans une base de données Snowflake standard.

L’exemple suivant utilise la commande CREATE DATABASE (liée à un catalogue) pour créer une base de données liée à un catalogue qui utilise un volume externe :

CREATE DATABASE my_catalog_linked_db
  LINKED_CATALOG = (
    CATALOG = 'glue_rest_catalog_int'
  ),
  EXTERNAL_VOLUME = 'my_external_vol';
Copy

Utiliser CREATE SCHEMA pour créer des espaces de noms dans votre catalogue externe

Pour créer un espace de noms pour l’organisation des tables Iceberg dans votre catalogue externe, vous pouvez utiliser la commande CREATE SCHEMA avec une base de données liée au catalogue. Cette commande crée un espace de noms dans votre catalogue REST Iceberg lié et un schéma correspondant dans votre base de données Snowflake.

CREATE SCHEMA 'my_namespace';
Copy

Note

Les noms des schémas doivent être alphanumériques et ne peuvent pas inclure de délimiteurs.

DROP SCHEMA

Vous pouvez également utiliser la commande DROP SCHEMA pour supprimer simultanément un schéma de votre base de données liée au catalogue et son espace de noms correspondant dans votre catalogue distant.

DROP SCHEMA 'my_namespace';
Copy

Créer une table Iceberg

La création d’une table Iceberg gérée en externe dans laquelle vous pouvez écrire à partir de Snowflake varie en fonction du type de base de données que vous utilisez :

Créer une table Iceberg dans une base de données liée à un catalogue

Pour créer une table dans Snowflake et dans votre catalogue externe en même temps, utilisez la commande CREATE ICEBERG TABLE (base de données liée au catalogue).

L’exemple suivant crée une table Iceberg accessible en écriture en utilisant le volume externe précédemment créé et l’intégration de catalogue pour AWS Glue REST.

USE DATABASE my_catalog_linked_db;

USE SCHEMA my_namespace;

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name string,
  last_name string,
  amount int,
  create_date date
)
TARGET_FILE_SIZE = '64MB';
Copy

Lorsque vous exécutez la commande, Snowflake crée une nouvelle table Iceberg dans votre catalogue distant et une table liée, gérée en externe et accessible en écriture dans Snowflake.

Créer une table Iceberg dans une base de données Snowflake standard

Si vous utilisez une base de données Snowflake standard, vous devez d’abord créer une table dans votre catalogue distant. Par exemple, vous pouvez utiliser Spark pour écrire une table Iceberg dans Open Catalog.

Après avoir créé la table dans votre catalogue distant, utilisez la commande CREATE ICEBERG TABLE (catalogue Iceberg REST) pour créer un objet de table Iceberg dans Snowflake. Pour le CATALOG_TABLE_NAME, spécifiez le nom de la table tel qu’il apparaît dans votre catalogue distant.

Par exemple :

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table_name';
Copy

Lorsque vous exécutez la commande, Snowflake crée une table gérée en externe et accessible en écriture dans Snowflake qui est liée à la table existante dans votre catalogue distant.

Suppression d’une table Iceberg

Vous pouvez supprimer simultanément une table Iceberg gérée en externe et accessible en écriture de Snowflake et de votre catalogue distant en utilisant la commande DROP ICEBERG TABLE.

DROP ICEBERG TABLE my_iceberg_table;
Copy

Snowflake supprime la table et appelle également votre catalogue Iceberg distant, en lui demandant de supprimer la table et les données et métadonnées sous-jacentes de celle-ci.

Snowflake ne supprime la table qu’après avoir vérifié que celle-ci a bien été supprimée du catalogue distant.

Note

Si vous utilisez le Catalogue de données AWS Glue comme catalogue externe, la suppression d’une table gérée en externe via Snowflake ne supprime pas les fichiers de table sous-jacents. Ce comportement est spécifique à la mise en œuvre du Catalogue de données AWS Glue.

Écriture dans des tables Iceberg gérées en externe

Vous pouvez utiliser les commandes DML suivantes pour les tables Iceberg gérées en externe :

Vous pouvez également utiliser l’API Snowpark pour traiter des tables Iceberg.

Exemples

Vous pouvez utiliser les exemples de base suivants pour commencer à écrire dans des tables Iceberg.

INSERT

Utilisez INSERT pour insérer des valeurs dans une table Iceberg :

INSERT INTO my_iceberg_table VALUES (1, 'a');
INSERT INTO my_iceberg_table VALUES (2, 'b');
INSERT INTO my_iceberg_table VALUES (3, 'c');
Copy

UPDATE

Utilisez UPDATE pour mettre à jour les valeurs d’une table Iceberg :

UPDATE my_iceberg_table
  SET a = 10
  WHERE b = 'b';
Copy

DELETE

Utilisez DELETE pour supprimer des valeurs d’une table Iceberg :

DELETE my_iceberg_table
  WHERE b = 'a';
Copy

MERGE

Utilisez MERGE sur une table Iceberg :

MERGE INTO my_iceberg_table USING my_snowflake_table
  ON my_iceberg_table.a = my_snowflake_table.a
  WHEN MATCHED THEN
      UPDATE SET my_iceberg_table.b = my_snowflake_table.b
  WHEN NOT MATCHED THEN
      INSERT VALUES (my_snowflake_table.a, my_snowflake_table.b);
Copy

COPY INTO <table>

Utilisez COPY INTO <table> pour charger des données dans une table Iceberg.

COPY INTO customer_iceberg_ingest
  FROM @my_parquet_stage
  FILE_FORMAT = 'my_parquet_format'
  LOAD_MODE = ADD_FILES_COPY
  PURGE = TRUE
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;
Copy

Pour plus d’informations, consultez Charger des données dans les tables Apache Iceberg™.

Capture des données de changement à l’aide de flux

Un flux de table suit les modifications apportées aux lignes d’une table source pour la capture des données de changement (CDC). La table source peut être une table Snowflake standard, une table Iceberg gérée par Snowflake ou une table Iceberg gérée en externe. Vous pouvez insérer les modifications dans une table Iceberg gérée en externe à l’aide de la commande INSERT INTO… SELECT FROM…

Note

Si votre table source est une table Iceberg gérée en externe, vous devez utiliser INSERT_ONLY = TRUE lorsque vous créez le flux.

CREATE OR REPLACE STREAM my_stream ON TABLE my_snowflake_table;

//...

INSERT INTO my_iceberg_table(id,name)
  SELECT id, name
  FROM my_stream;
Copy

Utilisation de Snowpark

Créez une fonction pour copier des données dans une table Iceberg à partir d’une table Snowflake en utilisant Snowpark Python.

def copy_into_iceberg():

  try:
      df = session.table("my_snowflake_table")

      df.write.save_as_table("my_iceberg_table")

  except Exception as e:
      print(f"Error processing {table_name}: {e}")
Copy

Résolution des problèmes

Si un problème survient lorsque Snowflake tente de valider les modifications de table dans votre catalogue externe, Snowflake renvoie l’un des messages d’erreur suivants :

Erreur

004185=SQL Execution Error: Failed while committing transaction to external catalog. Error:''{0}''

Ou :

004185=SQL Execution Error: Failed while committing transaction to external catalog with unresolvable commit conflicts. Error:''{0}''

Cause

Une validation dans le catalogue externe a échoué, où {0} est l’exception renvoyée par le catalogue externe (si disponible) ; sinon, Snowflake indique Exception unavailable comme cause. Le message d’erreur comprend with unresolvable commit conflicts si Snowflake a rencontré un conflit de validation impossible à résoudre lors de la tentative de validation d’une transaction dans le catalogue externe.

Erreur

004500=SQL Execution Error: Cannot verify the status of transaction from external catalog. The statement ''{0}'' with transaction id {1} may or may not have committed to external catalog. Error:''{2}''

Cause

Une validation dans le catalogue externe n’a entraîné aucune réponse du catalogue externe. Le message inclut l’exception renvoyée par le catalogue externe (si disponible) ; sinon, Snowflake indique Exception unavailable comme cause.