ALTER TABLE
适用于: 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}
参数
-
标识要更改的表。 名称不得包含时态规范。 如果找不到表,Azure Databricks 会引发 TABLE_OR_VIEW_NOT_FOUND 错误。
RENAME TO
to_table_name重命名同一架构中的表。
-
标识新的表名称。 名称不得包含时态规范。
-
ADD COLUMN
向表中添加一个或多个列。
ALTER COLUMN
更改属性或列的位置。
-
删除 Delta Lake 表中的一列或多列或字段。
-
重命名 Delta Lake 表中的列或字段。
-
向表添加 CHECK 约束、信息性外键约束或信息性主键约束。
只有 Unity Catalog 中的表支持外键和主键,而
hive_metastore
目录不支持。 -
从表中删除主键、外键或 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
- “v2Checkpoint”或
如果 Azure Databricks 表中不存在该功能,则会引发 DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT。
- “deletionVectors”或
截断历史记录
(可选)允许在 24 小时后启动删除读取器加编写器功能的第二个阶段,方法是截断执行调用命令时的表历史记录。
截断表历史记录会限制执行 DESCRIBE HISTORY 和执行时按时间顺序查看查询的能力。
-
向表中添加一个或多个分区。
-
从表中删除一个或多个分区。
-
设置分区的位置。
RENAME PARTITION
替换分区的键。
RECOVER PARTITIONS
指示 Azure Databricks 扫描表的位置,并将已直接添加到文件系统的任何文件添加到表中。
-
适用于: 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
在表或列中必须唯一。
-
适用于: 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;