ALTER TABLE

S’applique à :case cochée oui Databricks SQL case cochée oui Databricks Runtime

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

Les tables temporaires prennent en charge ALTER TABLE ... SET TBLPROPERTIES et ALTER TABLE ... UNSET TBLPROPERTIES dans le calcul serverless, Databricks Runtime 18.2 et versions ultérieures, et Databricks SQL 2026.15 et versions ultérieures. Les autres ALTER TABLE clauses ne sont pas prises en charge sur les tables temporaires et retournent une erreur. 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.

Les tables étrangères supportent un ensemble limité d’opérations ALTER TABLE , incluant ALTER TABLE SET OWNER, ALTER TABLE RENAME TO, ALTER TABLE SET MANAGED { MOVE | COPY }, et ALTER TABLE SET EXTERNAL. SET MANAGED et SET EXTERNAL nécessitent une table étrangère fédérée utilisant Hive Metastore et Glue Federation, et SET MANAGED nécessitent également le format Delta Lake. Voir les tables étrangères et Convertir une table étrangère en une table Unity Catalog externe.

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

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

  • SET OWNER TO
  • PREDICTIVE OPTIMIZATION

Toutes les autres opérations nécessitent la propriété de la table, y compris SET MANAGED et UNSET MANAGED.

SET EXTERNAL et la forme à table étrangère de SET MANAGED nécessite CREATE également une permission sur le EXTERNAL LOCATION. Pour les prérequis complets de chaque conversion, voir Prérequis et Prérequis.

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 EXTERNAL clause |
      SET MANAGED clause |
      UNSET MANAGED clause |
      SET OWNER TO clause |
      SET TAGS clause |
      UNSET TAGS clause |
      CLUSTER BY clause |
      REPLACE PARTITIONED BY WITH 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.

    > ALTER TABLE student RENAME TO student_info;

  • AJOUTER COLUMN

    Ajoute une ou plusieurs colonnes à la table.

    Lorsque vous ajoutez une colonne à une table Delta Lake existante, vous ne pouvez pas définir de DEFAULT valeur. Toutes les colonnes ajoutées aux tables Delta Lake sont traitées comme NULL pour les lignes existantes. Après avoir ajouté une colonne, vous pouvez éventuellement définir une valeur par défaut pour les nouvelles lignes à l’aide ALTER COLUMNde .

    > DESCRIBE StudentInfo;
                col_name data_type comment
----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     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

-- Optionally set a default value for new rows
> ALTER TABLE StudentInfo ALTER COLUMN LastName SET DEFAULT 'unknown';

  • MODIFIERCOLUMN

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

    > DESCRIBE StudentInfo;
                col_name data_type comment
----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL

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

-- After altering the column
> DESCRIBE StudentInfo;
                col_name data_type     comment
----------------------- --------- -----------
                    name    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL

    Modifiez plusieurs colonnes dans une seule instruction :

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

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

    > ALTER TABLE StudentInfo RENAME COLUMN name TO FirstName;

-- After renaming the column
> DESCRIBE StudentInfo;
                col_name data_type     comment
----------------------- --------- -----------
               FirstName    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL

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

    S’applique à :coché oui Databricks SQL coché oui 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 à :check marqué oui 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 à :coché oui Databricks SQL coché oui 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 Les fonctionnalités de table Drop Delta et les versions de protocole et 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.

      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.

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

  • AJOUTER PARTITION

    Ajoute une ou plusieurs partitions à la 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

-- Adding multiple partitions to the table
> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18) PARTITION (age=20);

> SHOW PARTITIONS StudentInfo;
partition
---------
    age=11
    age=12
    age=15
    age=18
    age=20

  • GOUTTE PARTITION

    Supprime une ou plusieurs partitions de la 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

  • PARTITION ... SET EMPLACEMENT

    Définit l’emplacement d’une partition.

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

  • renommer PARTITION

    Remplace les clés d’une 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

  • 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 à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime 12.2 LTS et versions ultérieures coche marquée oui 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 à :coche marquée oui 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.

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

  • PROPRIÉTÉS TBL NON DÉFINIES

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

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

  • SET SERDE

    S’applique à :case cochée oui Databricks Runtime

    Spécifie la classe sérialiseur/désérialiseur (SerDe) utilisée pour lire et écrire des données dans une table de format Hive. Vous pouvez également configurer des propriétés SerDe avec WITH SERDEPROPERTIES.

    > 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 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 EXTERNAL [ DRY RUN ]

    S’applique à :check marqué oui Databricks Runtime 17.3 et versions ultérieures , cochez uniquement le catalogue Unity oui

    Convertit une table étrangère en une table externe du catalogue Unity, conservant l’historique et les configurations de la table, y compris le nom, les paramètres, les permissions et les vues. Pris en charge uniquement sur des tables étrangères fédérées via le métastore de la Ruche et la Fédération de la Colle.

    Nécessite OWNER ou MANAGE autoriser sur la table et CREATE autorisation sur le EXTERNAL LOCATION.

    Pour annuler la conversion, retirez la table. Azure Databricks la réfédére en tant que table étrangère lors de la prochaine synchronisation du catalogue.

    • DRY RUN

      Vérifie si la table source peut être convertie, sans la convertir. La commande retourne DRY_RUN_SUCCESS si la table peut être convertie.

    Pour les prérequis et les conseils spécifiques au format, voir Convertir une table étrangère en une table Unity Catalog externe.

    -- Check whether a foreign table can be converted
> ALTER TABLE hms_federated_catalog.my_schema.my_table SET EXTERNAL DRY RUN;

-- Convert a foreign table to an external table
> ALTER TABLE hms_federated_catalog.my_schema.my_table SET EXTERNAL;

  • SET MANAGED

    S’applique à :coche oui Databricks Runtime 17.3 LTS et au-dessus coché oui uniquement Unity Catalogue

    Convertit une table Delta Lake externe ou étrangère du catalogue Unity en une table gérée par le catalogue Unity. La conversion conserve le nom de la table, les paramètres, les permissions, les vues et l’historique.

    Les tables externes et étrangères utilisent différentes formes de la proposition, comme le montre la syntaxe suivante :

    SET MANAGED [ TRUNCATE UNIFORM HISTORY ]  -- external tables
SET MANAGED { MOVE | COPY }               -- foreign tables

    Pour les tables externes, omettez MOVE et COPY. Si vous incluez l’un ou l’autre, Azure Databricks augmente DELTA_ALTER_TABLE_SET_MANAGED_UNSUPPORTED_COPY_MOVE_SYNTAX.

    Pour les tables étrangères, spécifiez soit MOVECOPY. Si vous omettez les deux, Azure Databricks augmente DELTA_ALTER_TABLE_SET_MANAGED_COPY_OR_MOVE_REQUIRED. Pour choisir entre les deux formes, voir Choisir la bonne commande pour votre table source.

    • TRUNCATE UNIFORM HISTORY

      Cela s’applique aux tables externes qui activent les lectures Apache Iceberg . Si la table active les lectures Iceberg et que vous omettez cette option, Azure Databricks relance DELTA_ALTER_TABLE_SET_MANAGED_DOES_NOT_SUPPORT_UNIFORM_ICEBERG.

      TRUNCATE UNIFORM HISTORY tronque l’histoire de l’iceberg UniForm et n’enlève pas l’histoire de Delta Lake. La troncature provoque un court temps d’arrêt de lecture et d’écriture de l’iceberg.

    • MOVE

      Convertit une table étrangère en gestion et désactive l’accès à la table source dans le catalogue externe. Après conversion, l’accès via le catalogue externe et l’accès basé sur chemin échouent, donc tous les lecteurs et auteurs doivent utiliser l’espace de noms du catalogue Unity.

    • COPY

      Convertit une table étrangère en gestionnaire sans modifier ni désactiver l’accès à la table source dans le catalogue externe. La conversion copie les données dans le lieu de stockage géré, créant ainsi deux copies distinctes des données. Vous êtes responsable de désactiver les lectures et écritures de la table source et de migrer les charges de travail vers la table gérée.

    Pour les prérequis, estimations de temps d’arrêt et dépannage, voir Convertir les tables Delta Lake externes ou étrangères en tables gérées par le catalogue Unity.

    -- Convert an external table
> ALTER TABLE main.default.my_external_table SET MANAGED;

-- Convert an external table that has Iceberg reads enabled
> ALTER TABLE main.default.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;

-- Convert a foreign table and disable access to the source table
> ALTER TABLE hms_federated_catalog.my_schema.my_table SET MANAGED MOVE;

  • UNSET MANAGED

    S’applique à :coche oui Databricks Runtime 17.3 LTS et au-dessus coché oui uniquement Unity Catalogue

    Convertit une table SET MANAGED vers une table externe en mettant à jour les métadonnées de la table pour pointer vers l’emplacement externe d’origine. Azure Databricks conserve les écritures effectuées vers le lieu géré après conversion. Pour une table externe convertie, vous pouvez revenir en arrière dans les 14 jours suivant la conversion.

    UNSET MANAGED [ TRUNCATE UNIFORM HISTORY ]

    Les commits effectués entre conversion et rollback supportent le voyage dans le temps par version, mais pas par horodatage.

    Pour créer une table étrangère convertie avec MOVE retour en une table étrangère, exécuter UNSET MANAGED puis supprimer la table externe résultante, ce qui la ré-fédére lors de la prochaine synchronisation du catalogue. Une table étrangère convertie avec COPY n’a pas besoin UNSET MANAGEDde , car la conversion a laissé la table source non modifiée.

    Warning

    Si vous avez converti une table étrangère avec MOVE, ne supprimez pas la table gérée avant d’avoir exécuté UNSET MANAGED. L’abandonner en premier peut entraîner une perte de données ou des incohérences.

    Pour des instructions complètes de rollback, voir Rollback a managed table conversion.

    -- Roll a converted managed table back to an external table
> ALTER TABLE main.default.my_managed_table UNSET MANAGED;

  • [ SET ] OWNER TO Principal

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

    S’applique à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime 11.3 LTS et ultérieur

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

    Note

    La modification du propriétaire n’est pas disponible sur les jeux de données gérés par un pipeline d’espace de travail.

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

    S’applique à :case cochée oui Databricks SQL case cochée oui 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.

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

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

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

    S’applique à :case cochée oui Databricks SQL case cochée oui 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.

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

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

  • Clause CLUSTER BY

    S’applique à :case cochée oui Databricks SQL case cochée oui Databricks Runtime 13.3 LTS et versions ultérieures

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

  • REPLACE PARTITIONED BY WITH CLUSTER BY [( <clustering_columns> ) | AUTO]

    S’applique à :check marqué oui Databricks SQL check marqué oui Databricks Runtime 18.1 et versions ultérieures

    Convertit une table Delta Lake partitionnée existante en clustering liquide en clustering liquide, avec un temps d’arrêt minimal du lecteur et de l’enregistreur. La CLUSTER BY clause accepte des colonnes de clustering explicites, AUTO pour déléguer la sélection de clé à l’optimisation prédictive ou peut être omise pour utiliser les colonnes de partition existantes.

    Consultez Convertir une table partitionnée en clustering liquide.

  • { ENABLE | DISABLE | INHERIT } PREDICTIVE OPTIMIZATION

    S’applique à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime 12.2 LTS et versions ultérieures coche marquée oui 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.

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

Exemples supplémentaires

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

  • Last updated on