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}

参数

• 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 及更高版本 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 SQL 仓库版本 2022.35 或更高版本 Databricks Runtime 11.2 及更高版本

  允许使用 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 及更高版本 仅 Unity Catalog

  重要

  此功能目前以公共预览版提供。

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

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

  当预测优化被显式启用或继承为启用时，Azure Databricks 会根据其认为适当的方式自动在表上调用 OPTIMIZE 和 VACUUM。 有关更多详细信息，请参阅：Delta Lake 的预测优化。

示例

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

• 更新 Delta Lake 表架构
• Azure Databricks 的约束

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

相关文章

• ADD CONSTRAINT

• ALTER STREAMING TABLE

• ALTER VIEW

• CLUSTER BY

• COMMENT ON

• CREATE TABLE

• DROP CONSTRAINT

• DROP TABLE

• 管理 COLUMN

• 管理 PARTITION

• REPAIR TABLE

• PARTITION