ALTER TABLE

项目
12/02/2024

适用于：勾选“是” 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
修改预测优化

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

语法

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}

参数

table_name

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

重命名同一架构中的表。
- to_table_name
  
  标识新的表名称。名称不得包含时态规范或选项规范。
ADD COLUMN

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

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

删除 Delta Lake 表中的一列或多列或字段。
RENAME COLUMN

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

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

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

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

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

从 Delta Lake 表中删除功能。

要删除会影响读取器和编写器的功能，需要执行两阶段过程：
- 第一个调用会清除该功能的任何跟踪，并通知你部分成功。
- 然后，需要等到保留期结束，并重新执行语句才能完成删除。
  
  如果太早启动第二次调用，Azure Databricks 会引发 DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD 或 DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST。
有关详细信息，请参阅什么是表功能？。
- feature_name
  
  采用 STRING 文本或标识符形式的功能名称，必须为 Azure Databricks 所理解并在表中受支持。
  
  支持的 feature_names 包括：
  - “deletionVectors”或 deletionvectors
    - “v2Checkpoint”或 v2checkpoint
  如果 Azure Databricks 表中不存在该功能，则会引发 DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT。
- 截断历史记录
  
  （可选）允许在 24 小时后启动删除读取器加编写器功能的第二个阶段，方法是截断执行调用命令时的表历史记录。
  
  截断表历史记录会限制执行 DESCRIBE HISTORY 和执行时按时间顺序查看查询的能力。
ADD PARTITION

向表中添加一个或多个分区。
DROP PARTITION

从表中删除一个或多个分区。
PARTITION … SET LOCATION

设置分区的位置。
RENAME PARTITION

替换分区的键。
RECOVER PARTITIONS

指示 Azure Databricks 扫描表的位置，并将已直接添加到文件系统的任何文件添加到表中。
SETROW 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 TABLE

所需的权限

语法

参数

示例

其他资源

通过

ALTER TABLE

所需的权限

语法

参数

示例

相关文章

其他资源