修改表

2025/05/29

适用于：勾选“是” Databricks SQL Databricks Runtime

更改表的架构或属性。

有关 Delta Lake 中的类型更改或重命名列，请参阅重写数据。

若要更改表或列的注释，还可以使用 COMMENT ON。

若要更改 STREAMING TABLE，请使用 ALTER STREAMING TABLE。

如果已缓存表，则该命令将清除该表及其引用的所有依赖项的缓存数据。在下次访问该表或这些依赖项时，将会延迟填充缓存。

备注

向现有 Delta 表添加列时，无法定义 DEFAULT 值。对于现有行，添加到 Delta 表的所有列均视为 NULL。添加列后，你可以有选择地定义列的默认值，但这仅适用于插入表中的新行。使用以下语法：

ALTER TABLE table_name ALTER COLUMN column_name SET DEFAULT default_expression

在外表上，只能执行 ALTER TABLE SET OWNER 和 ALTER TABLE RENAME TO。

所需的权限

如果使用 Unity Catalog，则必须具有 MODIFY 权限：

ALTER COLUMN
ADD COLUMN
DROP COLUMN
SET TBLPROPERTIES
UNSET TBLPROPERTIES
修改 PREDICTIVE OPTIMIZATION

如果您使用 Unity Catalog，则必须对以下内容拥有 MANAGE 权限或所有权：

SET OWNER TO

所有其他操作都需要表的所有权。

语法

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}

参数

table_name

标识要更改的表。名称不得包含时态规范或选项规范。如果找不到表，Azure Databricks 会引发 TABLE_OR_VIEW_NOT_FOUND 错误。
RENAME TO to_table_name

重命名表。
- to_table_name
  
  标识新的表名称。名称不得包含时态规范或选项规范。
  
  对于 Unity 目录表，该 to_table_name 表必须位于同 table_name一目录中。对于其他表，to_table_name 必须位于与 table_name 相同的模式中。
  
  如果 to_table_name 不符合条件，则使用当前架构隐式限定。
ADD COLUMN

向表中添加一个或多个列。

ALTER COLUMN

更改属性或列的位置。
删除列

删除 Delta Lake 表中的一列或多列或字段。
重命名列

重命名 Delta Lake 表中的列或字段。

添加约束

向表添加 CHECK 约束、信息性外键约束或信息性主键约束。

只有 Unity Catalog 中的表支持外键和主键，而 hive_metastore 目录不支持。
DEFAULT COLLATION collation_name

适用于： Databricks SQL Databricks Runtime 16.3 及更高版本

更改新 STRING 列的表的默认排序规则。现有列不受此子句的影响。若要更改现有列的排序规则，请使用 ALTER TABLE ... ALTER COLUMN ... COLLATE collation_name。

删除约束

从表中删除主键、外键或 CHECK 约束。
DROP FEATURE feature_name [ TRUNCATE HISTORY ]

适用于： Databricks Runtime 14.3 LTS 及更高版本

从 Databricks Runtime 14.3 LTS 开始，提供对 DROP FEATURE 的遗留支持。有关旧功能的文档，请参阅删除 Delta 表功能（旧版）。

适用于： Databricks SQL Databricks Runtime 16.3 及更高版本
Azure Databricks 建议对所有 DROP FEATURE 命令使用 Databricks Runtime 16.3 及更高版本，这将取代旧行为。

从 Delta Lake 表中删除功能。

删除功能可能会导致在表协议中添加 checkpointProtection 编写器功能。有关详细信息，请参阅 Drop Delta 表功能和表功能，了解协议兼容性。
- feature_name
  
  采用 STRING 文本或标识符形式的功能名称，必须为 Azure Databricks 所理解并在表中受支持。
  
  如果 Azure Databricks 表中不存在该功能，则会引发 DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT。
- 截断历史记录
  
  通过截断历史记录移除功能。这需要两个阶段过程：

通过截断历史记录来移除功能需要执行两个步骤：

第一个调用会清除功能的痕迹，且更通知你部分成功。
然后，等待保留期结束，然后重新执行语句以完成删除。

如果太早启动第二次调用，Azure Databricks 会引发 DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD 或 DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST。

截断表历史记录会限制执行 DESCRIBE HISTORY 和执行时按时间顺序查看查询的能力。
添加分区

向表中添加一个或多个分区。
删除分区

从表中删除一个或多个分区。
分区……设置位置

设置分区的位置。
RENAME PARTITION

替换分区的键。
RECOVER PARTITIONS

指示 Azure Databricks 扫描表的位置，并将已直接添加到文件系统的任何文件添加到表中。
SET ROW FILTER 子句

适用于： Databricks SQL Databricks Runtime 12.2 LTS 及更高版本仅 Unity Catalog

向表中添加行筛选器函数。对表的所有后续查询都会收到函数计算结果为布尔值 TRUE 的行子集。这对于细粒度的访问控制目的非常有用，在这种情况下，该函数可以检查调用用户的身份或组成员身份，以决定是否筛选特定行。
DROP ROW FILTER

适用于：仅 Unity Catalog

从表中删除行筛选器（如果有）。未来查询将返回表中的所有行，而无任何自动筛选。
SET TBLPROPERTIES

设置或重置一个或多个用户定义的属性。
UNSET TBLPROPERTIES

移除一个或多个用户定义的属性。
SET LOCATION

移动表的位置。
```
SET LOCATION path
```
- LOCATION path
  
  path 必须是 STRING 文本。指定表的新位置。
  
  原始位置中的文件不会移动到新位置。
[ SET ] OWNER TO 主体

将表的所有权转移给 principal。

适用于： Databricks SQL Databricks Runtime 11.3 LTS 及更高版本

允许使用 SET 作为可选关键字。
SET TAGS ( { tag_name = tag_value } [, ...] )

适用于： Databricks SQL Databricks Runtime 13.3 LTS 及更高版本

将标记应用于表。需要具有 APPLY TAG 权限才能向表添加标记。
- tag_name
  
  文本 STRING。 tag_name 在表或列中必须唯一。
- tag_value
  
  文本 STRING。
UNSET TAGS ( tag_name [, ...] )

适用于： Databricks SQL Databricks Runtime 13.3 LTS 及更高版本

从表中删除标记。需要具有 APPLY TAG 权限才能从表中删除标记。
- tag_name
  
  文本 STRING。 tag_name 在表或列中必须唯一。
CLUSTER BY 子句

适用于： Databricks SQL Databricks Runtime 13.3 LTS 及更高版本

添加、更改或删除 Delta Lake 表的聚类策略。
{ ENABLE | DISABLE | INHERIT } PREDICTIVE OPTIMIZATION

适用于： Databricks SQL Databricks Runtime 12.2 LTS 及更高版本仅 Unity Catalog

将托管 Delta Lake 表更改为所需的预测优化设置。

默认情况下，创建表时，行为是从架构INHERIT。

当预测优化被显式启用或继承为启用时，Azure Databricks 会根据其认为适当的方式自动在表上调用 OPTIMIZE 和 VACUUM。

示例

有关 Delta Lake 的 add constraint 和 alter column 的示例，请参阅

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

通过

修改表

所需的权限

语法

参数

示例

相关文章

其他资源