ALTER TABLE

S’applique à : Databricks SQL Databricks Runtime

Modifie le schéma ou les propriétés d’une table.

Pour les modifications de type ou le changement de nom des colonnes dans Delta Lake, consultez Réécrire les données.

Pour modifier le commentaire d’une table, vous pouvez également utiliser COMMENT ON.

Pour modifier un STREAMING TABLE, utilisez ALTER STREAMING TABLE.

Si la table est mise en cache, la commande efface les données mises en cache de la table et tous ses dépendants qui y font référence. Le cache est rempli de manière différée lors de l’accès suivant à la table ou aux dépendants.

Remarque

Lorsque vous ajoutez une colonne à une table Delta existante, vous ne pouvez pas définir une valeur DEFAULT. Toutes les colonnes ajoutées aux tables Delta sont traitées comme NULL pour les lignes existantes. Après avoir ajouté une colonne, vous pouvez éventuellement lui définir une valeur par défaut, mais elle est appliquée uniquement pour les nouvelles lignes insérées dans la table. Utilisez la syntaxe suivante :

ALTER TABLE table_name ALTER COLUMN column_name SET DEFAULT default_expression

Sur les tables sources contenant une clé étrangère, vous ne pouvez effectuer que les opérations ALTER TABLE SET OWNER et ALTER TABLE RENAME TO.

Autorisations requises

Si vous utilisez le catalogue Unity, vous devez avoir MODIFY l’autorisation de :

• ALTER COLUMN
• AJOUTER UNE COLONNE
• ANNULER LA COLONNE
• SET TBLPROPERTIES
• UNSET TBLPROPERTIES
• modify PREDICTIVE OPTIMIZATION

Toutes les autres opérations nécessitent la propriété de la table.

Syntaxe

ALTER TABLE table_name
   { RENAME TO clause |
     ADD COLUMN clause |
     ALTER COLUMN clause |
     DROP COLUMN clause |
     RENAME COLUMN clause |
     ADD CONSTRAINT clause |
     DROP CONSTRAINT clause |
     DROP FEATURE clause |
     ADD PARTITION clause |
     DROP PARTITION clause |
     PARTITION SET LOCATION clause |
     RENAME PARTITION clause |
     RECOVER PARTITIONS clause |
     SET { ROW FILTER clause } |
     DROP ROW FILTER |
     SET TBLPROPERTIES clause |
     UNSET TBLPROPERTIES clause |
     SET SERDE clause |
     SET LOCATION clause |
     SET OWNER TO clause |
     SET SERDE clause |
     SET TAGS clause |
     UNSET TAGS clause |
     CLUSTER BY clause }
     PREDICTIVE OPTIMIZATION clause}

Paramètres

• table_name

  Identifie la table en cours de modification. Le nom ne doit pas inclure une spécification temporelle. Si la table est introuvable, Azure Databricks génère une erreur TABLE_OR_VIEW_NOT_FOUND.

• RENAME TOto_table_name

  Renomme la table dans le même schéma.

  • to_table_name

    Identifie le nouveau nom de la table. Le nom ne doit pas inclure une spécification temporelle.

• ADD COLUMN

  Ajoute une ou plusieurs colonnes à la table.

• ALTER COLUMN

  Modifie une propriété ou l’emplacement d’une colonne.

• DROP COLUMN

  Déposez une ou plusieurs colonnes ou champs dans une table Delta Lake.

• RENAME COLUMN

  Renomme une colonne ou un champ dans une table Delta Lake.

• ADD CONSTRAINT

  Ajoute une contrainte de validation, une contrainte de clé étrangère d’information ou une contrainte de clé primaire d’information à la table.

  Les clés étrangères et les clés primaires sont prises en charge seulement pour les tables dans Unity Catalog, et non pour le catalogue hive_metastore.

• DROP CONSTRAINT

  Supprime une contrainte de clé primaire, de clé étrangère ou de validation dans la table.

• DROP FEATURE feature_name [ TRUNCATE HISTORY ]

  S’applique à : Databricks SQL Databricks Runtime 14.1 et versions ultérieures

  Supprime une fonctionnalité d’une table Delta Lake.

  La suppression des fonctionnalités qui affectent à la fois les lecteurs et les enregistreurs nécessite un processus en deux étapes :

  • Le premier appel efface toutes les traces de la fonctionnalité et vous informe de la réussite partielle.

  • Vous devez ensuite attendre que la période de rétention soit terminée et réexécuter l’instruction pour terminer la suppression.

    Si vous lancez le deuxième appel trop tôt, Azure Databricks déclenche DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD ou DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST.

  Pour plus de détails, consultez Que sont les fonctionnalités de table ?.

  • feature_name

    Nom d’une fonctionnalité sous la forme d’un littéral STRING ou d’un identificateur, qui doit être compris par Azure Databricks et pris en charge sur la table.

    Les feature_names prises en charge sont les suivantes :

    • ‘deletionVectors’ ou deletionvectors
      • ‘v2Checkpoint’ ou v2checkpoint

    Si la fonctionnalité n’est pas présente dans la table, Azure Databricks déclenche DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT.

  • TRONQUER L’HISTORIQUE

    Cette option vous permet de lancer la deuxième phase de l’abandon d’une fonction de lecture et d’écriture après 24 heures en tronquant l’historique de la table au moment où la commande d’appel a été exécutée.

    Tronquer l’historique des tables limite votre capacité à exécuter DÉCRIRE L’HISTORIQUE et à exécuter des requêtes de voyage dans le temps.

• ADD PARTITION

  Ajoute une ou plusieurs partitions à la table.

• DROP PARTITION

  Supprime une ou plusieurs partitions de la table.

• PARTITION … SET LOCATION

  Définit l’emplacement d’une partition.

• RENAME PARTITION

  Remplace les clés d’une partition.

• RECOVER PARTITIONS

  Demande à Azure Databricks d’analyser l’emplacement de la table et d’ajouter des fichiers à la table qui ont été ajoutés directement au système de fichiers.

• SETClause ROW FILTER

  S’applique à : Databricks SQL Databricks Runtime 12.2 LTS et versions ultérieures Unity Catalog uniquement

  Permet d’ajouter une fonction de filtre de ligne à la table. Toutes les requêtes ultérieures sur la table reçoivent un sous-ensemble des lignes où la fonction évalue à la valeur booléenne TRUE. Cela peut être utile à des fins de contrôle d’accès plus précis, où la fonction peut inspecter l’identité et/ou l’appartenance à un groupe de l’utilisateur appelant afin de décider s’il convient de filtrer certaines lignes.

• DROP ROW FILTER

  S’applique à : Unity Catalog uniquement

  Permet d’annuler le filtre de colonne d’une table, le cas échéant. Les requêtes futures retourneront toutes les lignes de la table sans aucun filtrage automatique.

• SET TBLPROPERTIES

  Définit ou redéfinit une ou plusieurs propriétés définies par l’utilisateur.

• UNSET TBLPROPERTIES

  Supprime une ou plusieurs propriétés définies par l’utilisateur.

• SET LOCATION

  Déplace l’emplacement d’une table.

  SET LOCATION path
  

  • LOCATION path

    path doit être un littéral STRING. Spécifie le nouvel emplacement de la table.

    Les fichiers situés à l’emplacement d’origine ne seront pas déplacés vers le nouvel emplacement.

• [ SET ] OWNER TOprincipal

  Transfère la propriété de la table vers principal.

  S’applique à : Databricks SQL Databricks Runtime 11.3 LTS et ultérieur

  SET est autorisé en tant que mot clé facultatif.

• SET TAGS ( { tag_name = tag_value } [, ...] )

  S’applique à : Databricks SQL Databricks Runtime 13.3 LTS et versions ultérieures

  Appliquer des balises à la table. Vous devez disposer d’une autorisation APPLY TAG pour ajouter des balises à la table.

  • tag_name

    Un STRING littéral. Le tag_name nom doit être unique dans la table ou la colonne.

  • tag_value

    Un STRING littéral.

• UNSET TAGS ( tag_name [, ...] )

  S’applique à : Databricks SQL Databricks Runtime 13.3 LTS et versions ultérieures

  Supprimer des balises de la table. Vous devez disposer d’une autorisation APPLY TAG pour supprimer des balises de la table.

  • tag_name

    Un STRING littéral. Le tag_name nom doit être unique dans la table ou la colonne.

• CLUSTER BY, clause

  S’applique à : Databricks SQL Databricks Runtime 13.3 LTS et versions ultérieures

  Ajoute, modifie ou supprime la stratégie de clustering pour une table Delta Lake.

• { ENABLE | DISABLE | INHERIT } PREDICTIVE OPTIMIZATION

  S’applique à : Databricks SQL Databricks Runtime 12.2 LTS et versions ultérieures Unity Catalog uniquement

  Important

  Cette fonctionnalité est disponible en préversion publique.

  Modifie la table Delta Lake gérée au paramètre d’optimisation prédictive souhaité.

  Par défaut, lorsque des tables sont créées, le comportement est INHERIT sur le schéma.

  Lorsque l’optimisation prédictive est explicitement activée ou héritée en tant qu’activée, OPTIMIZE et VACUUM sont automatiquement appelés sur la table, comme prévu par Azure Databricks. Pour plus d’informations, consultez Optimisation prédictive pour les tables managées Unity Catalog.

Exemples

Pour obtenir des exemples Delta Lake d’ajout de contraintes et de modification de colonne, consultez

• Mettre à jour un schéma de table Delta Lake
• Contraintes sur Azure Databricks

-- RENAME table
> DESCRIBE student;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

> ALTER TABLE Student RENAME TO StudentInfo;

-- After Renaming the table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

-- RENAME partition
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=10
    age=11
    age=12

> ALTER TABLE default.StudentInfo PARTITION (age='10') RENAME TO PARTITION (age='15');

-- After renaming Partition
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

-- Add new columns to a table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

> ALTER TABLE StudentInfo ADD columns (LastName string, DOB timestamp);

-- After Adding New columns to the table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

-- Add a new partition to a table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18);

-- After adding a new partition to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18

-- Drop a partition from the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18

> ALTER TABLE StudentInfo DROP IF EXISTS PARTITION (age=18);

-- After dropping the partition of the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

-- Adding multiple partitions to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18) PARTITION (age=20);

-- After adding multiple partitions to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18
    age=20

-- ALTER or CHANGE COLUMNS
> DESCRIBE StudentInfo;
                col_name data_type comment
+-----------------------+---------+-------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

ALTER TABLE StudentInfo ALTER COLUMN name COMMENT "new comment";

--After ALTER or CHANGE COLUMNS
> DESCRIBE StudentInfo;
                col_name data_type     comment
 ----------------------- --------- -----------
                    name    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL
 # Partition Information
              # col_name data_type     comment
                     age       int        NULL

-- RENAME COLUMN
> ALTER TABLE StudentInfo RENAME COLUMN name TO FirstName;

--After RENAME COLUMN
> DESCRIBE StudentInfo;
                col_name data_type     comment
 ----------------------- --------- -----------
               FirstName    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL
 # Partition Information
              # col_name data_type     comment
                     age       int        NULL

-- Change the file Location
> ALTER TABLE dbx.tab1 PARTITION (a='1', b='2') SET LOCATION '/path/to/part/ways';

-- SET SERDE/ SERDE Properties (DBR only)
> ALTER TABLE test_tab SET SERDE 'org.apache.hadoop.hive.serde2.columnar.LazyBinaryColumnarSerDe';

> ALTER TABLE dbx.tab1 SET SERDE 'org.apache.hadoop' WITH SERDEPROPERTIES ('k' = 'v', 'kay' = 'vee');

-- SET TABLE PROPERTIES
> ALTER TABLE dbx.tab1 SET TBLPROPERTIES ('winner' = 'loser');

-- DROP TABLE PROPERTIES
> ALTER TABLE dbx.tab1 UNSET TBLPROPERTIES ('winner');

-- Drop the "deletion vectors" from a Delta table
> ALTER TABLE my_table DROP FEATURE deletionVectors;

-- 24 hours later
> ALTER TABLE my_table DROP FEATURE deletionVectors TRUNCATE HISTORY;

-- Applies three tags to the table named `test`.
> ALTER TABLE test SET TAGS ('tag1' = 'val1', 'tag2' = 'val2', 'tag3' = 'val3');

-- Removes three tags from the table named `test`.
> ALTER TABLE test UNSET TAGS ('tag1', 'tag2', 'tag3');

-- Applies three tags to table `main.schema1.test` column `col1`.
> ALTER TABLE main.schema1.test ALTER COLUMN col1 SET TAGS ('tag1' = 'val1', 'tag2' = 'val2', 'tag3' = 'val3');

-- Removes three tags from table `main.schema1.test` column `col1`.
> ALTER TABLE main.schema1.test ALTER COLUMN col1 UNSET TAGS ('tag1', 'tag2', 'tag3');

-- Enables predictive optimization for my_table
> ALTER TABLE my_table ENABLE PREDICTIVE OPTIMIZATION;

Articles connexes

• ADD CONSTRAINT

• ALTER STREAMING TABLE

• ALTER VIEW

• CLUSTER BY

• COMMENT ON

• CREATE TABLE

• DROP CONSTRAINT

• DROP TABLE

• gérer COLUMN

• gérer PARTITION

• REPAIR TABLE

• PARTITION