CREATE ICEBERG TABLE (Fichiers Iceberg dans le stockage d’objets)¶

Syntaxe¶

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

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.

METADATA_FILE_PATH = 'metadata_file_path'

Spécifie le chemin d’accès relatif au fichier de métadonnées Iceberg à utiliser pour les définitions de colonne.

Par exemple, si s3://mybucket_us_east_1/metadata/v1.metadata.json est le chemin complet à votre fichier de métadonnées et si l’emplacement de stockage du volume externe est s3://mybucket_us_east_1/, indiquez metadata/v1.metadata.json comme valeur pour METADATA_FILE_PATH.

Avant la version 7.34 de Snowflake, ce paramètre était appelé METADATA_FILE_NAME.

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.

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.

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

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 :

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

  • Avec les versions 7.34 et ultérieures de Snowflake, vous n’indiquez pas d”BASE_LOCATION pour créer une table à partir de fichiers Iceberg dans le stockage d’objets.

    Avant la version 7.34, un paramètre nommé BASE_LOCATION (également appelé FILE_PATH dans les versions précédentes) était nécessaire pour créer une table à partir de fichiers Iceberg dans le stockage d’objets. Le paramètre spécifiait un chemin d’accès relatif à partir de l’emplacement du EXTERNAL_VOLUME.

    Vous pouvez continuer à exécuter un script ou une instruction qui utilise la version antérieure de la syntaxe. Dans ce cas, les remarques suivantes s’appliquent :

    • Les fichiers de données Parquet et les fichiers de métadonnées Iceberg pour la table doivent se trouver dans BASE_LOCATION.

    • Pour actualiser la table, vous devez spécifier un chemin relatif à BASE_LOCATION. Par exemple, si le chemin d’accès complet à votre fichier de métadonnées est s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json, indiquez metadata/v1.metadata.json comme metadata-file-relative-path.

      Pour plus d’informations, voir ALTER ICEBERG TABLE … REFRESH.

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

CREATE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME='my_external_volume'
  CATALOG='my_catalog_integration'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"external_volume_1"'
  CATALOG = '"catalog_integration_1"'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';