CREATE ICEBERG TABLE (catalogue Iceberg REST)¶

Syntaxe¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<rest_catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ PARTITION BY ( partitionExpression [ , partitionExpression , ... ] ) ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

Où :

partitionExpression ::=
  <col_name> -- identity transform
  | BUCKET ( <num_buckets> , <col_name> )
  | TRUNCATE ( <width> , <col_name> )
  | YEAR ( <col_name> )
  | MONTH ( <col_name> )
  | DAY ( <col_name> )
  | HOUR ( <col_name> )

Syntaxe des variantes¶

CREATE ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [
    --Column definition
    <col_name> <col_type>
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]
  ]
  [ PARTITION BY ( partitionExpression [ , partitionExpression , ... ] ) ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

partitionExpression ::=
  <col_name> -- identity transform
  | BUCKET ( <num_buckets> , <col_name> )
  | TRUNCATE ( <width> , <col_name> )
  | YEAR ( <col_name> )
  | MONTH ( <col_name> )
  | DAY ( <col_name> )
  | HOUR ( <col_name> )

Paramètres requis¶

table_name

Indique l’identificateur (le nom) de la table dans Snowflake ; 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.

Note

Pour récupérer une liste de tables ou d’espaces de noms dans votre catalogue distant, vous pouvez utiliser les fonctions suivantes :

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

CATALOG_TABLE_NAME = 'rest_catalog_table_name'

Spécifie le nom de table tel qu’il est reconnu par votre catalogue externe. Ce paramètre ne peut pas être modifié après la création de la table.

Note

Ne spécifiez pas d’espace de noms avec le nom de la table (mynamespace.mytable). Pour spécifier un espace de noms pour cette table et remplacer l’espace de noms défini par défaut pour l’intégration du catalogue, utilisez le paramètre CATALOG_NAMESPACE.

col_name

Pour créer une table dans une base de données liée au catalogue (prévisualisation).

Indique un identificateur 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

Pour créer une table dans une base de données liée au catalogue (prévisualisation).

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 Apache Iceberg™.

Paramètres facultatifs¶

PARTITION BY = ( partitionExpression [ , partitionExpression , ... ] )

Spécifie un ou plusieurs expressions de partition.

MASKING POLICY = policy_name

Pour créer une table dans une base de données liée au catalogue (prévisualisation).

Spécifie la politique de masquage à définir sur une colonne. La politique de masquage doit appartenir à une base de données Snowflake standard (et non à la base de données liée au catalogue).

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 vous ne spécifiez pas ce paramètre, la table Iceberg utilise par défaut l’intégration de catalogue pour le schéma, la base de données ou le 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_database) pour la source de catalogue REST. En spécifiant un espace de noms avec l’intégration de catalogue puis au niveau de la table, vous pouvez utiliser une seule intégration de catalogue REST afin de créer des tables Iceberg dans différentes bases de données. Si vous ne spécifiez pas d’espace de noms avec la table, celle-ci utilise l’espace de noms par défaut du catalogue associé à l’intégration du catalogue.

• Si un espace de noms par défaut n’est pas spécifié avec l’intégration du catalogue, vous devez spécifier l’espace de noms pour la source de catalogue REST afin de définir un espace de noms de catalogue pour la table.

Note

Pour récupérer une liste de tables ou d’espaces de noms dans votre catalogue distant, vous pouvez utiliser les fonctions suivantes :

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }'

Fonctionnalité en avant-première — En accès libre

Disponible pour tous les comptes.

Spécifie une taille de fichier Parquet cible pour la table.

• '{ 16MB | 32MB | 64MB | 128MB }' spécifie une taille de fichier cible fixe pour la table.

• 'AUTO' fonctionne différemment, selon le type de table :

  • Tables gérées par Snowflake : AUTO spécifie que Snowflake doit choisir la taille du fichier de la table en fonction de caractéristiques de la table telles que la taille, les modèles DML, la charge de travail d’ingestion et la configuration du clustering. Snowflake ajuste automatiquement la taille du fichier, à partir de 16 MB, pour de meilleures performances en lecture et en écriture dans Snowflake. Utilisez cette option pour optimiser les performances des tables dans Snowflake.

  • Tables gérées en externe : AUTO spécifie que Snowflake doit être mis à l’échelle de manière dynamique jusqu’à la plus grande taille de fichier (128 MB).

Pour plus d’informations, voir Définir une taille de fichier cible.

Par défaut : AUTO

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.

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.

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.

Pour plus d’informations, voir la section actualisation automatique.

Par défaut : FALSE

Note

L’utilisation de AUTO_REFRESH avec INFER_SCHEMA n’est pas prise en charge.

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

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

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 Quota de balise pour les objets.

WITH CONTACT ( purpose = contact [ , purpose = contact ...] )

Associez le nouvel objet à un ou plusieurs contacts.

Paramètres d’expression de partition (partitionExpression)¶

Pour plus d’informations sur le partitionnement des tables Iceberg, consultez Partitionnement Iceberg.

col_name

Spécifie l’ identificateur (le nom) de la colonne source à partitionner.

Lorsqu’il est utilisé seul, sans transformation comme YEAR, spécifie une transformation d’identité sur la colonne source. Pour plus d’informations, consultez l’identité.

BUCKET

Spécifie une transformation de compartiment. Pour plus d’informations, consultez Détails de la transformation du compartiment.

num_buckets est le nombre de compartiments dans lesquels regrouper les données.

TRUNCATE

Spécifie une transformation tronquée, qui partitionne les données en fonction des valeurs tronquées de la colonne source spécifiée. Pour plus d’informations, consultez Tronquer les détails de la transformation.

YEAR

Spécifie une transformation d’année, qui extrait l’année d’une valeur de colonne source de date ou d’horodatage. Pour plus d’informations, consultez Transformations de partition.

MONTH

Spécifie une transformation de mois. Pour plus d’informations, consultez Transformations de partition.

DAY

Spécifie une transformation de jour, qui extrait le jour d’une valeur de colonne source de date ou d’horodatage. Pour plus d’informations, consultez Transformations de partition.

HOUR

Spécifie une transformation d’heure, qui extrait l’heure d’une valeur de colonne source d’horodatage. Pour plus d’informations, consultez Transformations de partition.

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

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

Le privilège USAGE relatif à la base de données et au schéma parents est exigé pour effectuer des opérations sur tout objet d’un schéma. Notez qu’un rôle doté d’un privilège quelconque sur un schéma permet à ce rôle de résoudre le schéma. Par exemple, un rôle doté du privilège CREATE sur un schéma peut créer des objets sur ce schéma sans également avoir le privilège USAGE attribué sur ce schéma.

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¶

• 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 créer une table Iceberg avec prise en charge de l’écriture (prévisualisation) :

  • Si vous utilisez une base de données Snowflake standard, vous devez d’abord créer une table Iceberg dans votre catalogue distant. Par exemple, vous pouvez utiliser Spark pour écrire une table Iceberg dans Open Catalog. Ne spécifiez pas de définitions de colonnes dans votre instruction CREATE ICEBERG TABLE.

  • Si vous utilisez une base de données liée au catalogue, vous devez spécifier les définitions des colonnes lorsque vous créez la table. Vous pouvez également écrire dans des tables Iceberg que Snowflake découvre automatiquement dans votre catalogue distant.

• La propriété TARGET_FILE_SIZE n’est prise en charge que pour les tables avec prise en charge de l’écriture (prévisualisation).

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

  • Les clauses OR REPLACE et IF NOT EXISTS s’excluent mutuellement. Elles ne peuvent pas être utilisées dans la même instruction.

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

• Utilisation de la syntaxe de variante :

  • CREATE ICEBERG TABLE … LIKE:

    • Pour les tables Iceberg partitionnées, le partitionnement du tableau source est ignoré. Pour ignorer ce comportement, spécifiez la clause PARTITION BY avec la commande.

  • CREATE ICEBERG TABLE … CLONE:

    • Pour les tables Iceberg partitionnées, la table clonée conserve les informations de partitionnement du tableau source.

• 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 OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table'
  AUTO_REFRESH = TRUE;

CREATE ICEBERG TABLE open_catalog_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'open_catalog_int'
  CATALOG_TABLE_NAME = 'my_open_catalog_table'
  AUTO_REFRESH = TRUE;

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

USE DATABASE my_catalog_linked_db;

USE SCHEMA 'my_namespace';

CREATE OR REPLACE ICEBERG TABLE iceberg_partitioned_date_time (start_date timestamp)
  PARTITION BY (DAY(start_date));

INSERT INTO iceberg_partitioned_date_time (start_date)
  VALUES
    (to_timestamp_ntz('2023-01-02 00:00:00')),
    (to_timestamp_ntz('2023-02-03 00:00:00')),
    (to_timestamp_ntz('2023-01-02 01:00:00')),
    (to_timestamp_ntz('2023-02-03 02:00:00'));