CREATE ICEBERG TABLE¶

Syntaxe¶

• Snowflake comme catalogue Iceberg

• Catalogue Iceberg externe

-- Snowflake as the Iceberg catalog
CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name> (
    -- Column definition
    <col_name> <col_type>
      [ inlineConstraint ]
      [ NOT NULL ]
      [ COLLATE '<collation_specification>' ]
      [ { DEFAULT <expr>
          | { AUTOINCREMENT | IDENTITY }
            [ { ( <start_num> , <step_num> )
                | START <num> INCREMENT <num>
              } ]
        } ]
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT '<string_literal>' ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]

    -- Out-of-line constraints
    [ , outoflineConstraint [ ... ] ]
  )
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  BASE_LOCATION = '<relative_path_from_external_volume>'
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , <col_name> ... ] ) ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

-- External Iceberg catalog
CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  externalCatalogParams
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ COMMENT = '<string_literal>' ]

Syntaxe des variantes¶

La syntaxe des variantes suivante est prise en charge pour la création de tables Iceberg qui utilisent Snowflake comme catalogue.

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.

col_name

Indique l’identificateur (le nom) de colonne. Toutes les exigences relatives aux identificateurs de table s’appliquent également aux identificateurs de colonne.

Pour plus d’informations, voir Exigences relatives à l’identificateur et Mots clés réservés et limités.

Note

En plus des mots clés réservés standard, les mots clés suivants ne peuvent pas être utilisés comme identificateurs de colonnes, car ils sont réservés aux fonctions de contexte standard ANSI :

• CURRENT_DATE

• CURRENT_ROLE

• CURRENT_TIME

• CURRENT_TIMESTAMP

• CURRENT_USER

Pour la liste des mots clés réservés, voir Mots clés réservés et limités.

col_type

Spécifie le type de données pour la colonne.

Pour plus d’informations sur les types de données qui peuvent être spécifiés pour les colonnes de la table, voir Types de données des tables Iceberg.

query

Sous-requête qui appelle la fonction INFER_SCHEMA et formate la sortie sous forme de tableau.

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.

CONSTRAINT ...

Définit une contrainte en ligne ou hors ligne pour la ou les colonnes spécifiées dans la table.

Pour des informations sur la syntaxe, voir CREATE | ALTER TABLE … CONSTRAINT. Pour plus d’informations sur les contraintes, voir Contraintes.

COLLATE 'collation_specification'

Spécifie le classement à utiliser pour des opérations de colonne telles que la comparaison de chaînes. Cette option s’applique uniquement aux colonnes de texte (VARCHAR, STRING, TEXT, etc.). Pour plus d’informations, voir Spécifications de classement.

DEFAULT ... ou . AUTOINCREMENT ...

Indique si une valeur par défaut est automatiquement insérée dans la colonne lorsqu’une valeur n’est pas spécifiée explicitement via une instruction INSERT ou CREATE TABLE AS SELECT :

DEFAULT expr

La valeur par défaut de la colonne est définie par l’expression spécifiée, qui peut être l’une des suivantes :

• Valeur constante.

• Référence de séquence (seq_name.NEXTVAL).

• Expression simple qui renvoie une valeur scalaire.

  L’expression simple peut inclure une UDF (fonction définie par l’utilisateur) SQL si l’UDF n’est pas une UDF sécurisée.

  Note

  Si une expression par défaut fait référence à une UDF SQL, la fonction est remplacée par sa définition au moment de la création de la table. Si la fonction définie par l’utilisateur est redéfinie à l’avenir, cela ne mettra pas à jour l’expression par défaut de la colonne.

  L’expression simple ne peut pas contenir des références à :

  • Sous-requêtes.

  • Agrégats.

  • Des fonctions de fenêtre.

  • Des UDFs sécurisées.

  • Des UDFs écrites dans des langages autres que SQL (par exemple, Java, JavaScript).

  • Fonctions externes.

{ AUTOINCREMENT | IDENTITY } [ { ( start_num , step_num ) | START num INCREMENT num } ]

AUTOINCREMENT et IDENTITY sont synonymes. Lorsque l’un ou l’autre est utilisé, la valeur par défaut de la colonne commence par un nombre spécifié et chaque valeur successive augmente automatiquement de la somme spécifiée.

Prudence

Snowflake utilise une séquence pour générer les valeurs d’une colonne auto-incrémentée. Les séquences ont des limites ; voir Sémantique de séquence.

La valeur par défaut pour le démarrage et les paliers/incréments est de 1.

AUTOINCREMENT et IDENTITY ne peuvent être utilisés que pour les colonnes dont le type de données est numérique.

Par défaut : aucune valeur (la colonne n’a pas de valeur par défaut)

Note

DEFAULT et AUTOINCREMENT s’excluent mutuellement ; une seule des deux peut être spécifiée pour une colonne.

MASKING POLICY = policy_name

Spécifie la politique de masquage à définir sur une colonne.

COMMENT 'string_literal'

Spécifie un commentaire pour la colonne.

(Notez que les commentaires peuvent être spécifiés au niveau de la colonne ou de la table. La syntaxe de chacun est légèrement différente).

USING ( col_name , cond_col_1 ... )

Spécifie les arguments à passer dans l’expression SQL de la politique de masquage conditionnelle.

La première colonne de la liste spécifie la colonne pour les conditions de la politique de masquage ou de tokenisation des données et doit correspondre à la colonne à laquelle la politique de masquage est définie.

Les colonnes supplémentaires spécifient les colonnes à évaluer pour déterminer s’il faut masquer ou tokeniser les données de chaque ligne du résultat de la requête lorsqu’une requête est effectuée sur la première colonne.

Si la clause USING est omise, Snowflake traite la politique de masquage conditionnelle comme une politique de masquage normale.

CLUSTER BY ( expr [ , expr , ... ] )

Spécifie une ou plusieurs colonnes ou expressions de colonne dans la table comme clés de clustering. Pour plus d’informations, voir Clés de clustering et tables en cluster.

Par défaut : aucune valeur (aucune clé de clustering n’est définie pour la table)

Important

Le clustering est pris en charge uniquement pour les tables qui utilisent Snowflake comme catalogue Iceberg.

Les clés de clustering ne sont pas recommandées ni conçues pour toutes les tables. Elles sont généralement intéressantes pour les tables très importantes (de plusieurs téraoctets).

Avant de spécifier une clé de clustering pour une table, vous devez comprendre ce que sont les micro-partitions. Pour plus d’informations, voir Fonctionnement des structures de table dans Snowflake.

DATA_RETENTION_TIME_IN_DAYS = integer

Spécifie la période de conservation de la table pour que les actions Time Travel (SELECT, CLONE, UNDROP) puissent être effectuées sur les données historiques de la table. Pour plus d’informations, voir Comprendre et utiliser la fonction « Time Travel » et Utilisation de tables temporaires et transitoires.

Pour une description détaillée de ce paramètre de niveau objet, ainsi que plus d’informations sur les paramètres d’objet, voir Paramètres.

Valeurs :

• Édition Standard : 0 ou 1

• Édition Enterprise :

  • 0 à 90 pour les tables permanentes

  • 0 ou 1 pour les tables temporaires et transitoires

Par défaut :

• Édition Standard : 1

• Édition Enterprise (ou supérieure) : 1 (sauf si une valeur par défaut différente a été spécifiée au niveau du compte, du schéma ou de la base de données)

Note

Une valeur de 0 désactive effectivement Time Travel pour la table.

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Paramètre d’objet qui spécifie le nombre maximum de jours pendant lesquels Snowflake peut prolonger la période de conservation des données de la table, afin d’éviter que les flux sur la table ne deviennent obsolètes.

Pour une description détaillée de ce paramètre, voir MAX_DATA_EXTENSION_TIME_IN_DAYS.

CHANGE_TRACKING = { TRUE | FALSE }

Spécifie s’il faut activer le suivi des modifications sur la table.

• TRUE active le suivi des modifications sur la table. Ce paramètre ajoute une paire de colonnes masquées à la table source et commence à stocker les métadonnées de suivi des modifications dans les colonnes. Ces colonnes consomment une petite quantité de stockage.

  Les métadonnées de suivi des modifications peuvent être interrogées à l’aide de la clause CHANGES pour les instructions SELECT, ou en créant et en interrogeant un ou plusieurs flux sur la table.

• FALSE n’active pas le suivi des modifications sur la table.

Par défaut : FALSE

DEFAULT_DDL_COLLATION = 'collation_specification'

Spécifie une spécification de classement par défaut pour les colonnes de la table, y compris les colonnes ajoutées à la table à l’avenir.

Pour plus d’informations sur ce paramètre, voir DEFAULT_DDL_COLLATION.

COPY GRANTS

Spécifie de conserver les privilèges d’accès de la table d’origine lorsqu’une nouvelle table est créée à l’aide de l’une des variables CREATE TABLE suivantes :

• CREATE OR REPLACE TABLE

• CREATE TABLE … LIKE

• CREATE TABLE … CLONE

Ce paramètre copie tous les privilèges, excepté OWNERSHIP, de la table existante vers la nouvelle table. La nouvelle table n’hérite pas des attributions futures définies pour le type d’objet dans le schéma. Par défaut, le rôle qui exécute l’instruction CREATE TABLE possède la nouvelle table.

Si le paramètre n’est pas inclus dans l’instruction CREATE ICEBERG TABLE, la nouvelle table n’hérite pas des privilèges d’accès explicites accordés sur la table d’origine, mais des attributions futures définies pour le type d’objet dans le schéma.

Remarque :

• Avec le partage des données :

  • Si la table existante a été partagée avec un autre compte, la table de remplacement est également partagée.

  • Si la table existante a été partagée avec votre compte en tant que consommateur de données et que l’accès a été accordé à d’autres rôles dans le compte (en utilisant GRANT IMPORTED PRIVILEGES sur la base de données mère), l’accès est également accordé à la table de remplacement.

• La sortie SHOW GRANTS pour la table de remplacement liste le concessionnaire des privilèges copiés comme le rôle qui a exécuté l’instruction CREATE ICEBERG TABLE avec l’horodatage courant lorsque l’instruction a été exécutée.

• L’opération de copie des accords s’effectue atomiquement dans la commande CREATE ICEBERG TABLE (c’est-à-dire dans la même transaction).

COMMENT = 'string_literal'

Spécifie un commentaire pour la table.

Par défaut : aucune valeur

(Notez que les commentaires peuvent être spécifiés au niveau de la colonne ou de la table. La syntaxe de chacun est légèrement différente).

ROW ACCESS POLICY policy_name ON ( col_name [ , col_name ... ] )

Spécifie la politique d’accès aux lignes à définir sur une table.

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.

Paramètres du catalogue Snowflake¶

CATALOG = 'SNOWFLAKE'

Spécifie Snowflake comme catalogue Iceberg. Snowflake prend en charge la maintenance tout au long du cycle de vie de la table, comme le compactage.

BASE_LOCATION = 'relative_path_from_external_volume'

Spécifie un chemin d’accès relatif au répertoire à partir de l’emplacement du EXTERNAL_VOLUME de la table auquel Snowflake peut écrire les données et les métadonnées de la table.

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

Paramètres de catalogue externe (externalCatalogParams)¶

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.

AWS Glue

CATALOG_TABLE_NAME = 'catalog_table_name'

Spécifie le nom de table tel qu’il est reconnu par votre 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.

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.

Fichiers Iceberg dans le stockage d’objets

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.

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¶

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

• Les tables Iceberg inter-Cloud et interrégionales ne sont actuellement pas prises en charge lorsque vous utilisez Snowflake comme catalogue Iceberg. Si CREATE ICEBERG TABLE renvoie un message d’erreur tel que "External volume <nom_du_volume> must have a STORAGE_LOCATION defined in the local region ...", assurez-vous que votre volume externe utilise un emplacement de stockage dans la même région que celle de votre compte Snowflake.

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

• CREATE TABLE … LIKE :

  • Si la table source a des clés de clustering, la nouvelle table a elle aussi des clés de clustering. Par défaut, le clustering automatique n’est pas suspendu pour la nouvelle table, même si le clustering automatique a été suspendu pour la table source.

• CREATE TABLE … AS SELECT (CTAS):

  • Lorsque les clés de clustering sont spécifiées dans une instruction CTAS :

    • Les définitions des colonnes sont obligatoires et doivent être explicitement spécifiées dans l’instruction.

    • Par défaut, le clustering automatique n’est pas suspendu pour la nouvelle table, même si le clustering automatique est suspendu pour la table source.

    La sous-clause ORDER BY d’une instruction CREATE TABLE n’affecte pas l’ordre des lignes retournées par les futures instructions SELECT sur cette table. Pour spécifier l’ordre des lignes dans les futures instructions SELECT, utilisez une sous-clause ORDER BY dans ces instructions.

• 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 Snowflake comme catalogue

Cet exemple crée une table Iceberg avec Snowflake comme catalogue Iceberg. La table obtenue est gérée par Snowflake et prend en charge l’accès en lecture et en écriture. L’instruction spécifie une valeur pour le paramètre BASE_LOCATION. Cela indique à Snowflake où écrire les données et métadonnées de la table dans le volume externe.

CREATE ICEBERG TABLE my_iceberg_table (amount int)
  CATALOG='SNOWFLAKE'
  EXTERNAL_VOLUME='my_external_volume'
  BASE_LOCATION='my/relative/path/from/extvol';

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';

Créer une table Iceberg à partir de métadonnées Iceberg dans le stockage d’objets

Cet exemple crée une table Iceberg à partir de métadonnées Iceberg stockées dans un stockage Cloud externe. Il spécifie également un chemin d’accès relatif aux métadonnées de la table dans le volume externe.

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

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 "exvol_lower" et "catint_lower" 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 = '"exvol_lower"'
  CATALOG = '"catint_lower"'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';