ALTER ICEBERG TABLE¶

Syntaxe¶

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> { clusteringAction | tableColumnAction }

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> UNSET
  [ REPLACE_INVALID_CHARACTERS ]
  [ CONTACT <purpose> ]

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> searchOptimizationAction

Où :

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }

Copy

tableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
        [ inlineConstraint ]
        [ COLLATE '<collation_specification>' ]

   | RENAME COLUMN <col_name> TO <new_col_name>

   | ALTER | MODIFY [ ( ]
                          , [ COLUMN ] <col1_name> { [ SET ] NOT NULL | DROP NOT NULL }
                          , [ COLUMN ] <col1_name> [ [ SET DATA ] TYPE ] <type>
                          , [ COLUMN ] <col1_name> COMMENT '<string>'
                          , [ COLUMN ] <col1_name> UNSET COMMENT
                        [ , [ COLUMN ] <col2_name> ... ]
                        [ , ... ]
                    [ ) ]

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }

  inlineConstraint ::=
    [ NOT NULL ]
    [ CONSTRAINT <constraint_name> ]
    { UNIQUE | PRIMARY KEY | { [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ] } }
    [ <constraint_properties> ]

Copy

dataGovnPolicyTagAction ::=
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ROW ACCESS POLICY <policy_name>
    | DROP ROW ACCESS POLICY <policy_name> ,
        ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }
  |
  {
      SET AGGREGATION POLICY <policy_name>
        [ ENTITY KEY ( <col_name> [, ... ] ) ]
        [ FORCE ]
    | UNSET AGGREGATION POLICY
  }
  |
  {
      SET JOIN POLICY <policy_name>
        [ FORCE ]
    | UNSET JOIN POLICY
  }
  |
  ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
    [ [ WITH ] MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] ]
    [ [ WITH ] PROJECTION POLICY <policy_name> ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>'
          [ , <tag_name> = '<tag_value>' , ... ] ) ]
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET PROJECTION POLICY <policy_name>
          [ FORCE ]
      | UNSET PROJECTION POLICY
  }
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> SET TAG
      <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
      , [ COLUMN ] <col2_name> SET TAG
          <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                   , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]

Copy

searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON <search_method_with_target> [ , <search_method_with_target> ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON { <search_method_with_target> | <column_name> | <expression_id> }
          [ , ... ]
     ]
  }

Copy

Pour plus de détails, voir Actions d’optimisation de la recherche (searchOptimizationAction).

Paramètres¶

table_name

Identificateur de la table à modifier.

Si l’identificateur contient des espaces ou des caractères spéciaux, toute la chaîne doit être délimitée par des guillemets doubles. Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus d’informations, voir Exigences relatives à l’identificateur.

SET ...

Spécifie un(e) ou plusieurs paramètre(s)/propriété(s) à définir pour la table externe (séparée par des espaces, des virgules ou de nouvelles lignes) :

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

CATALOG_SYNC = 'snowflake_open_catalog_integration_name'

Spécifie le nom d’une intégration de catalogue configurée pour Snowflake Open Catalog. Snowflake synchronise la table avec un catalogue externe dans votre compte Snowflake Open Catalog. Pour plus d’informations sur la synchronisation des tables Iceberg gérées par Snowflake avec Open Catalog, voir Synchronisation d’une table gérée par Snowflake avec Snowflake Open Catalog.

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

DATA_RETENTION_TIME_IN_DAYS = integer

Spécifie la période de conservation de la table gérée par Snowflake 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 Compréhension et utilisation de la fonction Time Travel.

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

• Enterprise Edition : de 0 à 90 pour les tables permanentes

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.

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.

Pour les tables basées sur Delta, Snowflake interroge votre stockage Cloud externe pour obtenir des mises à jour.

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

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

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

Disponible pour tous les comptes.

Associez l’objet existant à un ou plusieurs contacts.

UNSET

Actuellement, vous ne pouvez désactiver que les paramètres suivants avec cette commande :

• REPLACE_INVALID_CHARACTERS

• CATALOG_SYNC

• CONTACT purpose

Actions de clustering (clusteringAction)¶

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

Spécifie (ou modifie) une ou plusieurs colonnes de table ou expressions de colonne en tant que clé de clustering pour la table. Il s’agit des colonnes/expressions pour lesquelles le clustering est assuré par le Clustering automatique.

Pour en savoir plus sur le clustering, voir Clés de clustering et tables en cluster.

SUSPEND | RESUME RECLUSTER

Active ou désactive Clustering automatique pour la table.

DROP CLUSTERING KEY

Détruit la clé de clustering pour la table.

Pour plus d’informations sur les clés de clustering et le reclustering à proprement parler, voir Fonctionnement des structures de table dans Snowflake.

Actions de la colonne de table (tableColumnAction)¶

ADD [ COLUMN ] [ IF NOT EXISTS ] col_name col_data_type . [ inlineConstraint ] [ COLLATE 'collation_specification' ] [ , ... ]

Ajoute une nouvelle colonne. Vous pouvez spécifier une contrainte en ligne ou une spécification de classement.

Pour plus d’informations sur les actions des colonnes de table, voir :

• CREATE | ALTER TABLE … CONSTRAINT

• CREATE MASKING POLICY

• CREATE TAG

Vous pouvez effectuer des opérations ADD COLUMN sur plusieurs colonnes dans la même commande.

Si vous n’êtes pas sûr que la colonne existe déjà, vous pouvez spécifier IF NOT EXISTS lors de l’ajout de la colonne. Si la colonne existe déjà, ADD COLUMN n’a aucun effet sur la colonne existante et n’entraîne pas d’erreur.

Note

Vous ne pouvez pas spécifier IF NOT EXISTS si vous spécifiez également l’un des éléments suivants pour la nouvelle colonne :

• AUTOINCREMENT ou IDENTITY

• UNIQUE, PRIMARY KEY ou FOREIGN KEY

RENAME COLUMN col_name to new_col_name

Renomme la colonne spécifiée en un nouveau nom qui n’est actuellement utilisé pour aucune autre colonne de la table.

Vous ne pouvez pas renommer une colonne qui fait partie d’une clé de clustering.

Lorsque vous renommez un objet (table, colonne, etc.), vous devez mettre à jour les autres objets qui y font référence avec le nouveau nom.

DROP COLUMN [ IF EXISTS ] col_name [ CASCADE | RESTRICT ]

Supprime la colonne spécifiée de la table.

Si vous n’êtes pas sûr que la colonne existe déjà, vous pouvez spécifier IF EXISTS lors de la suppression de la colonne. Si la colonne n’existe pas, DROP COLUMN n’a aucun effet et n’entraîne pas d’erreur.

La destruction d’une colonne est une opération comportant uniquement des métadonnées. Il ne réécrit pas immédiatement les micropartitions et ne libère donc pas immédiatement l’espace utilisé par la colonne. En règle générale, l’espace d’une micro-partition est libéré lors de la réécriture de la micro-partition, généralement lorsqu’une écriture est effectuée en raison d’une opération DML (INSERT, UPDATE, DELETE) ou un re-clustering.

Politique de gouvernance des données et actions de balises (dataGovnPolicyTagAction)¶

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.

policy_name

Identificateur de la politique ; doit être unique pour votre schéma.

Les clauses suivantes s’appliquent à tous les types de tables qui prennent en charge les politiques d’accès aux lignes, notamment les tables, les vues et les tables d’événements. Pour simplifier, les clauses font simplement référence à la « table ».

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

Ajoutez la politique d’accès aux lignes à la table.

Au moins un nom de colonne doit être spécifié. Des colonnes supplémentaires peuvent être spécifiées en séparant chaque nom de colonne par une virgule. Utilisez cette expression pour ajouter une politique d’accès aux lignes à la fois à une table d’événements et à une table externe.

DROP ROW ACCESS POLICY policy_name

Supprime une politique d’accès aux lignes de la table.

Utilisez cette clause pour supprimer la politique de la table.

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

Supprime la politique d’accès aux lignes définie sur la table et ajoute une politique d’accès aux lignes pour la même table en une seule instruction SQL.

DROP ALL ROW ACCESS POLICIES

Supprime toutes les associations de politique d’accès aux lignes d’une table.

Cette expression est utile lorsqu’une politique d’accès aux lignes est détruite d’un schéma avant de détruire la politique d’une table d’événements. Utilisez cette expression pour supprimer les associations de politiques d’accès aux ligne de la table.

SET AGGREGATION POLICY policy_name

[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]

Attribue une politique d’agrégation à la table.

Utilisez le paramètre ENTITY KEY facultatif pour définir les colonnes qui identifient de manière unique une entité dans la table. Pour plus d’informations, voir Mise en œuvre de la protection de la confidentialité au niveau de l’entité à l’aide de politiques d’agrégation.

Utilisez le paramètre facultatif FORCE pour remplacer atomiquement une politique d’agrégation existante par la nouvelle politique d’agrégation.

UNSET AGGREGATION POLICY

Détache une politique d’agrégation de la table.

SET JOIN POLICY policy_name

[ FORCE ]

Attribue une politique de jointure à la table.

Utilisez le paramètre facultatif FORCE pour remplacer de manière atomique une politique de jointure existante par la nouvelle politique de jointure.

UNSET JOIN POLICY

Détache une politique de jointure de la table.

{ ALTER | MODIFY } [ COLUMN ] ...

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.

FORCE

Remplace une politique de masquage ou de projection actuellement définie sur une colonne par une politique différente dans une seule instruction.

Notez que l’utilisation du mot-clé FORCE avec une politique de masquage exige que le type de données de la politique dans l’instruction ALTER TABLE (c’est-à-dire STRING) corresponde au type de données de la politique de masquage actuellement définie sur la colonne (c’est-à-dire STRING).

Si aucune politique de masquage n’est actuellement définie sur la colonne, la spécification de ce mot-clé n’a aucun effet.

Pour plus de détails, voir : Remplacez une politique de masquage sur une colonne ou Remplacement d’une politique de projection.

Actions d’optimisation de la recherche (searchOptimizationAction)¶

ADD SEARCH OPTIMIZATION

Ajoute l’optimisation de recherche pour la table entière ou, si vous spécifiez la clause ON facultative, pour des colonnes spécifiques.

Note

L’optimisation de la recherche peut être coûteuse à maintenir, en particulier si les données du tableau changent fréquemment. Pour plus d’informations, voir Optimisation de la recherche - Estimation et gestion des coûts.

ON search_method_with_target [, search_method_with_target ... ]

Indique que vous souhaitez configurer l’optimisation de la recherche pour des colonnes spécifiques (au lieu de la table entière).

Pour search_method_with_target, utilisez une expression avec la syntaxe suivante :

<search_method>( <target> [ , <target> , ... ] [ , ANALYZER => '<analyzer_name>' ] )

Copy

Où :

• search_method spécifie l’une des méthodes suivantes qui optimisent les requêtes pour un type particulier de prédicat :

  Méthode de recherche	Description
  FULL_TEXT	Prédicats utilisant les types VARCHAR (texte).
  EQUALITY	Prédicats d’égalité et IN
  SUBSTRING	Prédicats qui correspondent à des chaînes de caractères et à des expressions régulières (par exemple, [ NOT ] LIKE, [ NOT ] ILIKE, [ NOT ] RLIKE et REGEXP_LIKE).

• target spécifie la colonne ou un astérisque (*).

  En fonction de la valeur de search_method, vous pouvez spécifier une colonne de l’un des types suivants :

  Méthode de recherche	Cibles prises en charge
  FULL_TEXT	Colonnes de types de données VARCHAR (texte).
  EQUALITY	Colonnes de types de données numériques, chaînes et binaires.
  SUBSTRING	Colonnes de types de données VARCHAR (texte).

  Pour spécifier toutes les colonnes applicables de la tableau comme cibles, utilisez un astérisque (*).

  Notez que vous ne pouvez pas spécifier à la fois un astérisque et des noms de colonnes spécifiques pour une méthode de recherche donnée. Cependant, vous pouvez spécifier un astérisque dans différentes méthodes de recherche.

  Par exemple, vous pouvez spécifier les expressions suivantes :

  -- Allowed
  ON SUBSTRING(*)
  ON EQUALITY(*), SUBSTRING(*)
  

  Copy

  Vous ne pouvez pas spécifier les expressions suivantes :

  -- Not allowed
  ON EQUALITY(*, c1)
  ON EQUALITY(c1, *)
  ON EQUALITY(v1:path, *)
  ON EQUALITY(c1), EQUALITY(*)
  

  Copy

• ANALYZER => 'analyzer_name' spécifie le nom de l’analyseur de texte, si search_method est FULL_TEXT.

  Pour plus d’informations sur les analyseurs d’optimisation de la recherche, voir ALTER TABLE.

Pour spécifier plus d’une méthode de recherche sur une cible, utilisez une virgule pour séparer chaque méthode ultérieure et chaque cible :

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);

Copy

Si vous exécutez la commande ALTER ICEBERG TABLE … ADD SEARCH OPTIMIZATION ON … sur la même table, chaque commande suivante s’ajoute à la configuration existante pour la table. Par exemple, supposons que vous ayez exécuté la commande suivante :

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);

Copy

Cela ajoute des prédicats d’égalité pour les colonnes c1, c2, c3 et c4 à la configuration de la table. Ceci est équivalent à l’exécution de la commande :

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);

Copy

Pour des exemples, voir Configuration de l’optimisation de la recherche pour des colonnes spécifiques.

DROP SEARCH OPTIMIZATION

Supprime l’optimisation de recherche pour l’ensemble de la table ou, si vous spécifiez la clause ON facultative, pour des colonnes spécifiques.

Note

• Si une table a la propriété d’optimisation de recherche, alors le fait de supprimer et de rétablir la table préserve la propriété d’optimisation de recherche.

• La suppression de la propriété d’optimisation de recherche d’une table puis son rétablissement entraînent le même coût que lors du premier ajout.

ON search_method_with_target | column_name | expression_id [ , ... ]

Indique que vous souhaitez supprimer la configuration de l’optimisation de la recherche pour des colonnes spécifiques (au lieu de supprimer l’optimisation de la recherche pour l’ensemble de la table).

Pour identifier la configuration de la colonne à détruire, spécifiez l’un des éléments suivants :

• Pour search_method_with_target, spécifiez une méthode d’optimisation des requêtes pour une ou plusieurs colonnes spécifiques. Utilisez la syntaxe décrite précédemment.

• Pour column_name, spécifiez le nom de la colonne configurée pour l’optimisation de la recherche. En spécifiant le nom de la colonne, toutes les expressions relatives à cette colonne sont supprimées.

• Pour expression_id, spécifiez l’ID d’une expression figurant dans la sortie de la commande DESCRIBE SEARCH OPTIMIZATION.

Pour en spécifier plusieurs, utilisez une virgule entre les éléments.

Vous pouvez spécifier toute combinaison de méthodes de recherche avec des cibles, des noms de colonnes et des IDs d’expressions.

Pour des exemples, voir Suppression de l’optimisation de la recherche pour des colonnes spécifiques.

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.

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¶

• Seul le propriétaire de la table (c’est-à-dire le rôle doté du privilège OWNERSHIP sur la table) ou un niveau supérieur peut exécuter cette commande.

• Le clustering est pris en charge uniquement pour les tables qui utilisent Snowflake comme catalogue Iceberg. Pour ajouter un clustering à une table Iceberg, vous devez également disposer du privilège USAGE ou OWNERSHIP sur le schéma et la base de données qui contiennent la table.

• Vous pouvez utiliser des fonctions de métrique des données avec des tables Iceberg en exécutant une commande ALTER TABLE. Pour plus d’informations, voir Utilisation des fonctions de métrique des données pour effectuer des contrôles de qualité des données.

• Pour plus d’informations sur l’utilisation de l’optimisation de la recherche avec les tables Iceberg, y compris les limites, voir Prise en charge des tables Apache Iceberg™ dans la documentation sur l’optimisation de la recherche.

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

• Pour résoudre les problèmes liés à la modification du paramètre CATALOG_SYNC, voir Vous ne pouvez pas modifier une table Iceberg lorsque vous spécifiez le paramètre CATALOG_SYNC.

Exemples¶

L’exemple suivant définit une balise (my_tag) avec une valeur customer sur une table Iceberg.

ALTER ICEBERG TABLE my_iceberg_table SET TAG my_tag = 'customer';

L’exemple suivant permet d’activer l”actualisation automatique pour une table existante gérée en externe :

ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = TRUE;

Les exemples suivants ajoutent et suppriment l’optimisation de la recherche pour une table Iceberg :

ALTER ICEBERG TABLE my_iceberg_table ADD SEARCH OPTIMIZATION ON SUBSTRING(C6);

ALTER ICEBERG TABLE my_iceberg_table DROP SEARCH OPTIMIZATION ON EQUALITY(C7, C8);