ALTER TABLE

2025-05-20

S’applique à : case cochée oui 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 ou d’une colonne, 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 étrangères, 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
ADD COLUMN
DROP COLUMN
SET TBLPROPERTIES
UNSET TBLPROPERTIES
modifier PREDICTIVE OPTIMIZATION

Si vous utilisez le catalogue Unity, vous devez disposer de la propriété ou de l’autorisation MANAGE de :

SET OWNER TO

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 |
      DEFAULT COLLATION 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 de spécification temporelle ou de spécification d’options. Si la table est introuvable, Azure Databricks génère une erreur TABLE_OR_VIEW_NOT_FOUND.
RENAME TO to_table_name

Renomme la table.
- to_table_name
  
  Identifie le nouveau nom de la table. Le nom ne doit pas inclure de spécification temporelle ou de spécification d’options.
  
  Pour les tables de catalogue Unity, il to_table_name doit se trouver dans le même catalogue que table_name. Pour les autres tables, le to_table_name doit se trouver dans le même schéma que table_name.
  
  Si to_table_name n'est pas qualifié, il est implicitement qualifié avec le schéma actuel.
AJOUTER COLUMN

Ajoute une ou plusieurs colonnes à la table.

MODIFIERCOLUMN

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

Déposez une ou plusieurs colonnes ou champs dans une table Delta Lake.
renommer 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.
DEFAULT COLLATION collation_name

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

Modifie le classement par défaut de la table pour les nouvelles colonnes STRING. Les colonnes existantes ne sont pas affectées par cette clause. Pour modifier le classement d’une colonne existante, utilisez ALTER TABLE ... ALTER COLUMN ... COLLATE collation_name.

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 Runtime 14.3 LTS et versions ultérieures

Le support hérité pour DROP FEATURE est disponible à partir de Databricks Runtime 14.3 LTS. Pour obtenir de la documentation sur les fonctionnalités héritées, consultez Les fonctionnalités de table Drop Delta (héritées).

S’applique à : Databricks SQL Databricks Runtime 16.3 et versions ultérieures
Azure Databricks recommande d’utiliser Databricks Runtime 16.3 et versions ultérieures pour toutes les DROP FEATURE commandes, qui remplacent le comportement hérité.

Supprime une fonctionnalité d’une table Delta Lake.

La suppression d’une fonctionnalité peut entraîner l’ajout de la fonctionnalité checkpointProtection writer au sein du protocole de table. Pour plus d’informations, consultez Fonctionnalités des tables Delta Drop et les fonctionnalités de table pour la compatibilité du protocole.
- 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.
  
  Si la fonctionnalité n’est pas présente dans la table, Azure Databricks déclenche DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT.
- HISTORIQUE TRUNCATE
  
  Suppression des fonctionnalités en tronquant l’historique. Cela nécessite un processus en deux étapes :

La suppression des fonctionnalités en tronquant l’historique nécessite un processus en deux étapes :

Le premier appel efface les traces de la fonctionnalité et vous informe de la réussite partielle.
Ensuite, attendez que la période de rétention se termine avant la réexécution de l’instruction pour terminer la suppression complète.

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.

Tronquer l’historique des tables limite votre capacité à exécuter DESCRIBE HISTORY et à exécuter des requêtes de voyage dans le temps.
AJOUTER PARTITION

Ajoute une ou plusieurs partitions à la table.
GOUTTE PARTITION

Supprime une ou plusieurs partitions de la table.
PARTITION ... SET EMPLACEMENT

Définit l’emplacement d’une partition.
renommer PARTITION

Remplace les clés d’une partition.
RÉCUPÉRER DES PARTITIONS

Indique à 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.
SET ROW FILTER clause

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

Permet d’ajouter une fonction de filtre de lignes à la table. Toutes les requêtes ultérieures de la table reçoivent un sous-ensemble des lignes dans lesquelles la fonction prend 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 TO principal

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 doit être unique dans la colonne ou la table.
- tag_value
  
  Un STRING littéral.
UNSET TAGS ( tag_name [, ...] )

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

Supprimer les 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 doit être unique dans la colonne ou la table.
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

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 seront automatiquement appelés sur la table, selon ce qu’Azure Databricks juge approprié. Pour plus d’informations, consultez Optimisation prédictive pour les tables managées Unity Catalog.

Exemples

Pour des exemples de l'ajout de contraintes et de modification de colonnes dans Delta Lake, consultez

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

-- Alter multiple columns in a single statement
-- Create a table with 3 columns
> CREATE TABLE my_table (num INT, str STRING, bool BOOLEAN) TBLPROPERTIES('delta.feature.allowColumnDefaults' = 'supported')
> DESCRIBE TABLE my_table;
  col_name    data_type     comment
  --------    ---------     -------
       num          int        null
       str       string        null
       bool      boolean       null

-- Update comments on multiple columns
> ALTER TABLE table ALTER COLUMN
   num COMMENT 'number column',
   str COMMENT 'string column';

> DESCRIBE TABLE my_table;
  col_name    data_type      comment
  --------    ---------   -------------
       num          int   number column
       str       string   string column
      bool      boolean            null

-- Can mix different types of column alter
> ALTER TABLE table ALTER COLUMN
   bool COMMENT 'boolean column',
   num AFTER bool,
   str AFTER num,
   bool SET DEFAULT true;

> DESCRIBE TABLE my_table;
  col_name    data_type      comment
  --------    ---------   --------------
      bool      boolean   boolean column
       num          int    number column
       str       string    string column

ADD CONSTRAINT

ALTER STREAMING TABLE

Partager via

ALTER TABLE

Autorisations requises

Syntaxe

Paramètres

Exemples

Articles connexes

Commentaires

Ressources supplémentaires