ALTER ICEBERG TABLE¶

Modifie les propriétés telles que les options de clustering et les balises d’une table Apache Iceberg existante.

Vous pouvez également utiliser une instruction ALTER ICEBERG TABLE pour actualiser une table, convertir une table ou modifier une colonne de type structuré. La syntaxe de ces opérations varie considérablement. Pour voir la syntaxe, la description des paramètres, les notes sur l’utilisation et des exemples d’actualisation ou de conversion d’une table Iceberg, voir les pages suivantes :

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.

Voir aussi :: CREATE ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE

Syntaxe¶

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]

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

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

Copy

Où :

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

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> [ FORCE ]
      | UNSET AGGREGATION POLICY
  }
  |
  {
    { 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

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, voir Synchronisation d’une table gérée par Snowflake avec Snowflake Open Catalog.

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

UNSET

Actuellement, cette commande permet uniquement de désactiver le paramètre suivant :

REPLACE_INVALID_CHARACTERS

Actions de clustering (`clusteringAction`)¶

Note

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

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.

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 Quotas de balises pour les objets et les colonnes.

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.

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

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
OWNERSHIP	Table Iceberg	OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).
USAGE	Volume externe
USAGE	Intégration de catalogue	Nécessaire si la table utilise une intégration de catalogue.

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¶

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 de fonctions de métrique des données.
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';

Copy

ALTER ICEBERG TABLE¶

Syntaxe¶

Paramètres¶

Actions de clustering (clusteringAction)¶

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

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

Notes sur l’utilisation¶

Exemples¶

Actions de clustering (`clusteringAction`)¶

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