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;
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.
Vous pouvez définir une taille de fichier cible pour les fichiers Parquet d’une table. Pour plus d’informations, voir Définir une taille de fichier cible.
Workflow¶
Utilisez le workflow de cette section pour commencer à utiliser cette fonctionnalité :
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;
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 :
Configurez une intégration au catalogue pour AWS Glue Iceberg REST. Utilisez les autorisations dans la politique d’exemple de lecture et d’écriture IAM.
Note
Si vous utilisez actuellement une intégration de catalogue pour AWS Glue, vous devez créer une nouvelle intégration de catalogue REST pour le point de terminaison REST Iceberg AWS Glue.
Configuration d’une intégration de catalogue pour Snowflake Open Catalog
Configuration d’une intégration de catalogue pour les catalogues Apache Iceberg™ REST
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';
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';
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';
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 :
Si vous utilisez une base de données liée à un catalogue, vous pouvez utiliser CREATE ICEBERG TABLE (base de données liée au catalogue) pour créer une table et l’enregistrer dans votre catalogue distant. Pour obtenir des instructions, voir Créer une table Iceberg dans une base de données liée à un catalogue.
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. Ensuite, vous pouvez utiliser la syntaxe CREATE ICEBERG TABLE (catalogue Iceberg REST) pour créer une table Iceberg dans Snowflake et écrire dedans. Pour obtenir des instructions, voir Créer une table Iceberg dans une base de données Snowflake standard.
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';
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';
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;
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 :
COPY INTO <table>. Pour plus d’informations, voir Charger des données dans les tables Apache Iceberg™.
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');
UPDATE¶
Utilisez UPDATE pour mettre à jour les valeurs d’une table Iceberg :
UPDATE my_iceberg_table
SET a = 10
WHERE b = 'b';
DELETE¶
Utilisez DELETE pour supprimer des valeurs d’une table Iceberg :
DELETE my_iceberg_table
WHERE b = 'a';
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 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;
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;
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}")
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ù |
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 |