Catégories :: Table, vue et séquence DDL

ALTER EXTERNAL TABLE¶

Modifie les propriétés, les colonnes ou les contraintes d’une table externe existante.

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

Dans ce chapitre :

Syntaxe
Paramètres
- Ajout et suppression manuels de partitions
Exigences en matière de contrôle d’accès
Notes sur l’utilisation
Exemples

Syntaxe¶

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> REFRESH [ '<relative-path>' ]

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> ADD FILES ( '<path>/[<filename>]' [ , '<path>/[<filename>'] ] )

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> REMOVE FILES ( '<path>/[<filename>]' [ , '<path>/[<filename>]' ] )

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> SET
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ] ]

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> UNSET
  TAG <tag_name> [ , <tag_name> ... ]

Partitions ajoutées et supprimées manuellement

ALTER EXTERNAL TABLE <name> [ IF EXISTS ] ADD PARTITION ( <part_col_name> = '<string>' [ , <part_col_name> = '<string>' ] ) LOCATION '<path>'

ALTER EXTERNAL TABLE <name> [ IF EXISTS ] DROP PARTITION LOCATION '<path>'

Paramètres¶

name

Identificateur de la table externe à 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.

REFRESH [ 'relative-path' ]

Accède aux fichiers de données mis en zone de préparation, et référencés dans la définition de table externe et met à jour les métadonnées de la table :

Les nouveaux fichiers dans le chemin sont ajoutés aux métadonnées de la table.
Les modifications apportées aux fichiers dans le chemin sont mises à jour dans les métadonnées de la table.
Les fichiers qui ne figurent plus dans le chemin sont supprimés des métadonnées de la table.

Spécifiez éventuellement un chemin relatif pour actualiser les métadonnées pour un sous-ensemble spécifique des fichiers de données.

L’utilisation de ce paramètre ne doit être effectuée qu’une seule fois, lors de la création de la table externe. Cette étape synchronise les métadonnées avec le dernier ensemble de fichiers associés dans la zone de préparation et le chemin dans la définition de la table externe. De plus, cette zone de préparation permet de s’assurer que la table externe peut lire les fichiers de données dans la zone de préparation et le chemin spécifiés, et qu’aucun fichier n’a été oublié dans la définition de la table externe.

Note

Ce paramètre n’est pas pris en charge par les tables externes partitionnées lorsque les partitions sont ajoutées manuellement par le propriétaire de l’objet (c’est-à-dire lorsque PARTITION_TYPE = USER_SPECIFIED).
Si TABLE_FORMAT = DELTA est défini sur la table externe, REFRESH ne prend pas en charge un chemin relatif pour actualiser les métadonnées pour un sous-ensemble spécifique de fichiers de données.

ADD FILES

Ajoute la liste de fichiers séparés par des virgules spécifiée aux métadonnées de la table externe. En règle générale, les paramètres ADD FILES et REMOVE FILES sont utilisés pour actualiser manuellement les métadonnées d’une table externe (c’est-à-dire lorsque AUTO_REFRESH = FALSE). Les références de fichier sont exprimées sous forme de chemins relatifs vers [WITH] LOCATION dans la définition de table externe. Pour plus d’informations, voir CREATE EXTERNAL TABLE.

Répertoriez le chemin et le nom de fichier de chaque fichier.

L’instruction ALTER EXTERNAL TABLE actualise automatiquement les métadonnées de la table externe et ajoute les fichiers, s’ils sont présents dans l’emplacement de stockage spécifié.

Ce paramètre n’est pas pris en charge par les tables externes partitionnées lorsque les partitions sont ajoutées manuellement par le propriétaire de l’objet (c’est-à-dire lorsque PARTITION_TYPE = USER_SPECIFIED).

REMOVE FILES

Supprime la liste de fichiers séparés par des virgules spécifiée des métadonnées de la table externe. En règle générale, les paramètres ADD FILES et REMOVE FILES sont utilisés pour actualiser manuellement les métadonnées d’une table externe (c’est-à-dire lorsque AUTO_REFRESH = FALSE). Les références de fichier sont exprimées sous forme de chemins relatifs vers [WITH] LOCATION dans la définition de table externe. Pour plus d’informations, voir CREATE EXTERNAL TABLE.

Répertoriez le chemin et le nom de fichier de chaque fichier.

L’instruction ALTER EXTERNAL TABLE actualise automatiquement les métadonnées de la table externe et supprime les fichiers.

Ce paramètre n’est pas pris en charge par les tables externes partitionnées lorsque les partitions sont ajoutées manuellement par le propriétaire de l’objet (c’est-à-dire lorsque PARTITION_TYPE = USER_SPECIFIED).

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

AUTO_REFRESH = TRUE | FALSE

Spécifie si Snowflake doit activer le déclenchement des actualisations automatiques des métadonnées de la table externe lorsque de nouveaux fichiers de données ou des fichiers de données mis à jour sont disponibles dans la zone de préparation externe nommée spécifiée dans le paramètre [ WITH ] LOCATION =.

Note

Vous devez configurer une notification d’événement pour votre emplacement de stockage pour notifier Snowflake lorsque des données nouvelles ou mises à jour sont disponibles pour être lues dans les métadonnées de la table externe. Pour plus d’informations, consultez les instructions relatives à votre service de stockage dans le Cloud :
- Amazon S3
  
  Actualisation automatique des tables externes Amazon S3
- Google Cloud Storage
  
  Actualisation automatique des tables externes pour Google Cloud Storage
- Microsoft Azure
  
  Actualisation automatique des tables externes pour Azure Blob Storage
Actuellement, la possibilité d’actualiser automatiquement les métadonnées n’est pas disponible pour les tables externes faisant référence à des zones de préparation de Google Cloud Storage.

Comme solution de contournement, nous suggérons de suivre nos bonnes pratiques pour mettre en zone de préparation vos fichiers de données et d’exécuter de façon intermittente une instruction ALTER EXTERNAL TABLE … REFRESH pour enregistrer les fichiers manquants. Pour des performances satisfaisantes, nous recommandons également d’utiliser un préfixe de chemin sélectif avec ALTER EXTERNAL TABLE pour réduire le nombre de fichiers qui doivent être répertoriés et vérifiés s’ils ont déjà été enregistrés (par exemple, bucket_name/YYYY/MM/DD/ ou même bucket_name/YYYY/MM/DD/HH/ en fonction de votre volume).
Ce paramètre n’est pas pris en charge par les tables externes partitionnées lorsque les partitions sont ajoutées manuellement par le propriétaire de l’objet (c’est-à-dire lorsque PARTITION_TYPE = USER_SPECIFIED).

TRUE: Snowflake permet de déclencher des actualisations automatiques des métadonnées de la table externe.
FALSE: Snowflake n’active pas le déclenchement d’actualisations automatiques des métadonnées de la table externe. Vous devez actualiser manuellement les métadonnées de la table externe avec ALTER EXTERNAL TABLE … REFRESH pour synchroniser les métadonnées avec la liste actuelle des fichiers dans le chemin de la zone de préparation.

Par défaut : TRUE

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 de détails sur la spécification des balises dans une instruction, voir Quotas de balises pour les objets et les colonnes.

UNSET

TAG tag_name [ , tag_name ... ]

Ajout et suppression manuels de partitions¶

Utilisez les paramètres suivants pour ajouter ou supprimer des partitions lorsque le type de partition de la table externe est spécifié par l’utilisateur (c’est-à-dire PARTITION_TYPE = USER_SPECIFIED) :

ADD PARTITION ( <part_col_name> = '<string>' [ , <part_col_name> = '<string>' , ... ] ) LOCATION '<path>'

Ajoutez manuellement une partition pour une ou plusieurs colonnes de partition définies pour la table externe dans un emplacement spécifié (c’est-à-dire un chemin).

Note

La longueur maximale des noms de colonnes de partition spécifiés par l’utilisateur est de 32 caractères.

L’ajout d’une partition ajoute également tout fichier nouveau ou mis à jour dans l’emplacement vers les métadonnées de la table externe.

DROP PARTITION LOCATION '<path>'

Détruisez manuellement toutes les partitions dans un emplacement spécifié (c’est-à-dire un chemin).

La destruction d’une partition supprime également tous les fichiers de l’emplacement des métadonnées de la table externe.

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 externe	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	Zone de préparation	Nécessaire pour actualiser manuellement les métadonnées de la table externe.
USAGE	Format de fichier	Nécessaire pour actualiser manuellement les métadonnées de la table externe.

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 Contrôle d’accès dans Snowflake.

Notes sur l’utilisation¶

Seul le propriétaire de la table externe (c’est-à-dire le rôle doté du privilège OWNERSHIP sur la table externe) ou d’un niveau supérieur peut exécuter cette commande.
Les commandes suivantes peuvent être utilisées dans des transactions explicites (en utilisant BEGIN … COMMIT) :
- ALTER EXTERNAL TABLE ... REFRESH
- ALTER EXTERNAL TABLE ... ADD FILES
- ALTER EXTERNAL TABLE ... REMOVE FILES
Les transactions explicites peuvent être utilisées pour garantir un état cohérent lors du remplacement manuel de fichiers mis à jour dans des métadonnées d’une table externe.
Ajoutez ou supprimez des colonnes dans une table externe à l’aide de la syntaxe suivante :
Ajouter une colonne
ALTER TABLE <name> ADD COLUMN ( <col_name> <col_type> AS <expr> ) [, ...]
Renommer une colonne
ALTER TABLE <name> RENAME COLUMN <col_name> to <new_col_name>
Détruire une colonne
ALTER TABLE <name> DROP COLUMN <col_name>
Note

Les colonnes VALUE et METADATA$FILENAME par défaut ne peuvent pas être détruites.
Voir la rubrique ALTER TABLE pour consulter des exemples.
Pour ajouter et supprimer une politique d’accès aux lignes sur une table externe, utilisez la commande ALTER TABLE .
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¶

Actualiser manuellement les métadonnées¶

Actualiser manuellement l’ensemble des métadonnées de table externe en fonction des modifications apportées aux fichiers de données référencés :

ALTER EXTERNAL TABLE exttable_json REFRESH;

Semblable au premier exemple, mais actualiser manuellement seulement un chemin des métadonnées pour une table externe :

CREATE OR REPLACE STAGE mystage
  URL='<cloud_platform>://twitter_feed/logs/'
  .. ;

-- Create the external table
-- 'daily' path includes paths in </YYYY/MM/DD/> format
CREATE OR REPLACE EXTERNAL TABLE daily_tweets
  WITH LOCATION = @twitter_feed/daily/;

-- Refresh the metadata for a single day of data files by date
ALTER EXTERNAL TABLE exttable_part REFRESH '2018/08/05/';

Ajouter ou supprimer des fichiers manuellement¶

Ajouter une liste explicite de fichiers aux métadonnées d’une table externe :

ALTER EXTERNAL TABLE exttable1 ADD FILES ('path1/sales4.json.gz', 'path1/sales5.json.gz');

Supprimer une liste explicite de fichiers des métadonnées d’une table externe :

ALTER EXTERNAL TABLE exttable1 REMOVE FILES ('path1/sales4.json.gz', 'path1/sales5.json.gz');

Remplacer un fichier journal mis à jour en décembre 2019 dans les métadonnées d’une table externe dans une transaction explicite :

BEGIN;

ALTER EXTERNAL TABLE extable1 REMOVE FILES ('2019/12/log1.json.gz');

ALTER EXTERNAL TABLE extable1 ADD FILES ('2019/12/log1.json.gz');

COMMIT;

Ajouter ou supprimer manuellement des partitions¶

Ajouter manuellement des partitions dans un emplacement spécifié pour les colonnes de partition :

ALTER EXTERNAL TABLE et2 ADD PARTITION(col1='2022-01-24', col2='a', col3='12') LOCATION '2022/01';

Snowflake ajoute les partitions aux métadonnées de la table externe. L’opération ajoute également aux métadonnées tout nouveau fichier de données se trouvant dans l’emplacement spécifié.

Supprimer manuellement les partitions d’un emplacement spécifié :

ALTER EXTERNAL TABLE et2 DROP PARTITION LOCATION '2022/01';

Snowflake supprime les partitions des métadonnées de la table externe. L’opération supprime également des métadonnées tous les fichiers de données se trouvant dans l’emplacement spécifié.