CREATE ICEBERG TABLE (AWS Glue comme catalogue Iceberg)

Crée ou remplace une table Apache Iceberg dans le schéma actuel/spécifié à l’aide d’une table Iceberg enregistrée dans le catalogue de données AWS Glue. Ce type de table Iceberg nécessite une intégration de catalogue pour connecter Snowflake à AWS Glue.

Cette rubrique fait référence aux tables Iceberg en les appelant simplement « tables », sauf lorsque le fait de préciser tables Iceberg permet d’éviter toute confusion.

Note

Avant de créer une table, vous devez créer le volume externe dans lequel sont stockés les métadonnées et les fichiers de données Iceberg. Pour obtenir des instructions, voir Configurer un volume externe.

Vous avez également besoin d’une intégration de catalogue pour la table. Pour en savoir plus, voir Configurer une intégration de catalogue pour AWS Glue.

Voir aussi :

ALTER ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE , UNDROP ICEBERG TABLE

Syntaxe

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
Copy

Paramètres requis

table_name

Indique l’identificateur (le nom) de la table ; doit être unique pour le schéma dans lequel la table est créée.

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_TABLE_NAME = 'catalog_table_name'

Spécifie le nom de table tel qu’il est reconnu par le catalogue de données AWS Glue. Pour un exemple d’utilisation de CATALOG_TABLE_NAME lors de la création d’une table Iceberg, voir Exemples (dans cette rubrique).

Ce paramètre ne peut pas être modifié après la création de la table.

Paramètres facultatifs

EXTERNAL_VOLUME = 'external_volume_name'

Spécifie l’identificateur (le nom) du volume externe dans lequel la table Iceberg stocke ses fichiers de métadonnées et ses données au format Parquet. Les métadonnées et les fichiers manifestes Iceberg stockent le schéma de la table, les partitions, les instantanés et d’autres métadonnées.

Si vous ne spécifiez pas ce paramètre, la table Iceberg utilise par défaut le volume externe du schéma, de la base de données ou du compte. Le schéma est prioritaire sur la base de données, et la base de données est prioritaire sur le compte.

CATALOG = 'catalog_integration_name'

Spécifie l’identificateur (le nom) de l’intégration de catalogue de cette table. Vous devez spécifier une intégration de catalogue que vous avez configurée pour AWS Glue. Pour plus d’informations, voir Configurer une intégration de catalogue pour AWS Glue.

Si cette valeur n’est pas spécifiée, la table Iceberg utilise par défaut l’intégration de catalogue du schéma, de la base de données ou du compte. Le schéma est prioritaire sur la base de données, et la base de données est prioritaire sur le compte.

CATALOG_NAMESPACE = 'catalog_namespace'

Spécifie éventuellement l’espace de noms (par exemple, my_glue_database) de la source du catalogue de données AWS Glue et remplace l’espace de noms de catalogue par défaut spécifié avec l’intégration de catalogue. En spécifiant un espace de noms au niveau de la table, vous pouvez utiliser une seule intégration de catalogue pour AWS Glue pour créer des tables Iceberg dans différentes bases de données.

Si cette valeur n’est pas spécifiée, la table utilise l’espace de noms de catalogue par défaut associé à l’intégration de catalogue.

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

Spécifie s’il faut remplacer les caractères UTF-8 non valides par le caractère de remplacement Unicode (�) dans les résultats de requête. Vous ne pouvez définir ce paramètre que pour les tables qui utilisent un catalogue Iceberg externe.

  • TRUE remplace les caractères UTF-8 non valides par le caractère de remplacement Unicode.

  • FALSE laisse les caractères UTF-8 non valides inchangés. Snowflake renvoie un message d’erreur utilisateur lorsqu’il rencontre des caractères UTF-8 non valides dans un fichier de données Parquet.

Si cette valeur n’est pas spécifiée, la table Iceberg utilise par défaut la valeur de paramètre du schéma, de la base de données ou du compte. Le schéma est prioritaire sur la base de données, et la base de données est prioritaire sur le compte.

Par défaut : FALSE

AUTO_REFRESH = { TRUE | FALSE }

Spécifie si Snowflake doit interroger automatiquement le catalogue Iceberg externe associé à la table pour les mises à jour de métadonnées lorsque vous utilisez l”actualisation automatique. Si aucune valeur n’est spécifiée pour le paramètre REFRESH_INTERVAL_SECONDS sur l’intégration du catalogue, Snowflake utilise un intervalle d’actualisation par défaut de 30 secondes.

Par défaut : FALSE

COMMENT = 'string_literal'

Spécifie un commentaire pour la table.

Par défaut : aucune valeur

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

Spécifie le nom de la balise et la valeur de la chaîne de la balise.

La valeur de la balise est toujours une chaîne de caractères et le nombre maximum de caractères pour la valeur de la balise est 256.

Pour plus d’informations sur la spécification des balises dans une instruction, voir Quotas de balises pour les objets et les colonnes.

Exigences en matière de contrôle d’accès

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

Privilège

Objet

Remarques

CREATE ICEBERG TABLE

Schéma

CREATE EXTERNAL VOLUME

Compte

Nécessaire pour créer un nouveau volume externe.

USAGE

Volume externe

Nécessaire pour référencer un volume externe existant.

CREATE INTEGRATION

Compte

Nécessaire pour créer une nouvelle intégration de catalogue.

USAGE

Intégration de catalogue

Nécessaire pour référencer une intégration de catalogue existante.

Notez que l’exploitation d’un objet dans un schéma requiert également le privilège USAGE sur la base de données et le schéma parents.

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

  • Considérations relatives à l’exécution de cette commande :

    • Si vous avez créé votre volume externe ou votre intégration de catalogue à l’aide d’un identificateur entre guillemets doubles, vous devez spécifier l’identificateur exactement tel qu’il a été créé (y compris les guillemets doubles) dans votre instruction CREATE ICEBERG TABLE. Le fait de ne pas inclure de guillemets peut entraîner une erreur Object does not exist (ou un type d’erreur similaire).

      Pour un exemple, voir la section Exemples (dans cette rubrique).

  • Considérations pour créer des tables :

    • Un schéma ne peut pas contenir de tables et/ou de vues portant le même nom. Lors de la création d’une table :

      • Si une vue portant le même nom existe déjà dans le schéma, une erreur est renvoyée et la table n’est pas créée.

      • Si une table portant le même nom existe déjà dans le schéma, une erreur est renvoyée et la table n’est pas créée, sauf si le mot clé facultatif OR REPLACE est inclus dans la commande.

    • 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.

      Cela signifie que toutes les requêtes simultanées à l’opération CREATE OR REPLACE ICEBERG TABLE utilisent soit l’ancienne soit la nouvelle version de la table.

    • Comme les mots clés réservés, les noms de fonctions réservés ANSI (CURRENT_DATE, CURRENT_TIMESTAMP, etc.) ne peuvent pas être utilisés comme noms de colonnes.

    • La recréation d’une table (en utilisant le mot clé OR REPLACE facultatif) détruit son historique, ce qui rend tout flux sur la table périmé. Un flux périmé est illisible.

  • 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.

Exemples

Créer une table Iceberg avec AWS Glue comme catalogue

Cet exemple crée une table Iceberg qui utilise le catalogue de données AWS Glue. Pour remplacer l’espace de noms de catalogue par défaut et définir un espace de noms de catalogue pour la table, l’instruction utilise le paramètre CATALOG_NAMESPACE facultatif.

CREATE ICEBERG TABLE glue_iceberg_table
  EXTERNAL_VOLUME='glue_catalog_volume'
  CATALOG='glue_catalog_integration'
  CATALOG_TABLE_NAME='my_glue_catalog_table'
  CATALOG_NAMESPACE='icebergcatalogdb2';
Copy

Spécifier un volume externe ou une intégration de catalogue avec un identificateur placé entre guillemets doubles

Cet exemple crée une table Iceberg avec un volume externe et une intégration de catalogue dont les identificateurs contiennent des guillemets doubles. Les identificateurs entre guillemets doubles sont sensibles à la casse et contiennent souvent des caractères spéciaux.

Les identificateurs "glue_volume_1" et "glue_catalog_integration_1" sont spécifiés exactement tels qu’ils ont été créés (y compris avec les guillemets doubles). Le fait de ne pas inclure de guillemets peut entraîner une erreur Object does not exist (ou un type d’erreur similaire).

Pour en savoir plus, voir Identificateurs entre guillemets doubles.

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"glue_volume_1"'
  CATALOG = '"glue_catalog_integration_1"'
  CATALOG_TABLE_NAME='my_glue_catalog_table'
  CATALOG_NAMESPACE='icebergcatalogdb2';
Copy