ALTER TABLE (Databricks SQL)

更改表的架构或属性。

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

若要更改表的注释,请使用 COMMENT ON

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

所需的权限

如果使用 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 |
     ADD PARTITION clause |
     DROP PARTITION clause |
     RENAME PARTITION clause |
     RECOVER PARTITIONS clause |
     SET TBLPROPERTIES clause |
     UNSET TBLPROPERTIES clause |
     SET LOCATION clause |
     OWNER TO clause }

参数

  • table_name

    标识要更改的表。 名称不得包含时态规范

  • 重命名为 to_table_name

    重命名同一架构中的表。

  • ADD COLUMN

    JDBC 数据源不支持此子句。

    向表添加一列或多列,或将字段添加到 Delta Lake 表中的现有列。

    { ADD [COLUMN | COLUMNS ]
      ( { {column_identifier | field_name} data_type [COMMENT comment] [FIRST | AFTER identifier] } [, ...] ) }
    
    • column_identifier

      要添加的列的名称。 名称在表中必须唯一。

      除非指定了 FIRSTAFTER name,否则列或字段将追加到末尾。

    • field_name

      要添加到现有列的字段的完全限定名称。 嵌套字段的路径的所有组件都必须存在,并且字段名称本身必须唯一。

    • COMMENT 注释

      描述添加的列或字段的可选字符串字面量。

    • FIRST

      如果指定,则列将添加为表的第一列,或者该字段将添加为包含结构中的 的第一个字段。

    • AFTER 标识符

      如果指定,则列或字段将立即添加到字段或列 identifier 之后。

  • ALTER COLUMN

    更改属性或列的位置。

    { { ALTER | CHANGE } [COLUMN] { column_identifier | field_name }
      { COMMENT comment |
        { FIRST | AFTER column_identifier } |
        { SET | DROP } NOT NULL |
        SYNC IDENTITY } }
    
    • column_identifier

      要更改的列的名称。

    • field_name

      要更改的字段的完全限定名称。 嵌套字段的路径的所有组件都必须存在。

    • COMMENT 注释

      更改 column_name 列的说明。 comment 必须是字符串字面量。

    • FIRST 或 AFTER 标识符

      将列从当前位置移到前面(FIRST)或立即移动到 identifier 之后(AFTER)。 只有 table_name 为 Delta 表时才支持此子句。

    • SET NOT NULL 或 DROP NOT NULL

      更改有效列值的域以排除 null(SET NOT NULL)或包含 null(DROP NOT NULL)。 只有 Delta Lake 表支持此选项。 Delta Lake 将确保约束对所有现有和新数据有效。

    • SYNC IDENTITY

      将标识列的元数据与实际数据同步。 将自己的值写入标识列时,它可能与元数据不一致。 此选项可评估状态并更新元数据,以使其与实际数据保持一致。 在此命令后,下一个自动分配的标识值将从 start + (n + 1) * step 开始,其中 n 是满足 start + n * step >= max() 的最小值(针对正步骤)。

      仅 Delta Lake 表上的标识列支持此选项。

  • 删除列

    重要

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

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

    删除列或字段时,必须删除相关检查约束和生成的列。

    有关要求,请参阅 Azure Databricks 上的列映射

    DROP [COLUMN | COLUMNS] [ IF EXISTS ] ( { {column_identifier | field_name} [, ...] )
    
    • IF EXISTS

      指定 IF EXISTS 时,Databricks SQL 会忽略删除不存在的列的尝试。 否则,删除不存在的列将导致错误。

    • column_identifier

      现有列的名称。

    • field_name

      现有字段的完全限定名称。

  • RENAME COLUMN

    重要

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

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

    重命名列或字段时,还需要更改相关检查约束和生成的列。 将删除使用该列的任何主键和外键。 对于外键,必须拥有在其中定义外键的表。

    有关要求,请参阅 Azure Databricks 上的列映射

    RENAME COLUMN { column_identifier TO to_column_identifier|
                    field_name TO to_field_identifier }
    
  • ADD CONSTRAINT

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

    hive_metastore 目录中的表不支持外键和主键。

  • DROP CONSTRAINT

    从表中删除主键、外键或 CHECK 约束。

  • ADD PARTITION

    如果指定,则向表中添加一个或多个分区。 Delta Lake 表不支持添加分区。

    ADD [IF NOT EXISTS] { PARTITION clause [ LOCATION path ] } [...]
    
    • IF NOT EXISTS

      一个可选子句,指示 Databricks SQL 如果分区已存在,则忽略语句。

    • PARTITION 子句

      要添加的分区。 分区键必须与表的分区匹配,并且必须与值关联。 如果分区已存在,则会引发错误,除非已指定 IF NOT EXISTS

    • LOCATION 路径

      path 必须是表示指向分区的可选位置的字符串字面量。

      如果未指定位置,则位置将派生自表和分区键的位置。

      如果位置存在文件,则这些文件将填充分区,并且必须与表及其选项的 data_source 兼容。

  • DROP PARTITION

    如果指定,此子句会从表中删除一个或多个分区,可以选择删除分区位置的任何文件。

    Delta Lake 表不支持删除分区。

    DROP [ IF EXISTS ] PARTITION clause [, ...] [PURGE]
    
    • IF EXISTS

      指定 IF EXISTS 时,Azure Databricks 将忽略删除不存在的分区的尝试。 否则,不存在的分区将导致错误。

    • PARTITION 子句

      指定要删除的分区。 如果仅部分标识了分区,则删除分区的切片。

    • PURGE

      如果设置此项,则即使目录已配置了回收文件夹,表目录也必须通过跳过该文件夹来删除分区数据。 此选项仅适用于托管表。 它只在以下情况下有效:

      文件系统支持回收站文件夹。 目录已配置为将已删除的分区移动到回收站文件夹。 AWS S3 中没有任何回收站文件夹,因此它无效。

      删除分区后,无需手动删除文件。

  • RENAME PARTITION

    替换分区的键。

    Delta Lake 表不支持重命名分区。

    from_partition_clause RENAME TO to_partition_clause
    
  • RECOVER PARTITIONS

    此子句不适用于 Delta Lake 表。

    指示 Databricks SQL 扫描表的位置,并将所有文件添加到已直接添加到文件系统的表中。

  • SET TBLPROPERTIES

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

  • UNSET TBLPROPERTIES

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

  • SET LOCATION

    移动分区或表的位置。

    Delta Lake 不支持移动 Delta Lake 表的单个分区。

    [ PARTITION clause ] SET LOCATION path
    
    • PARTITION 子句

      可以选择性地标识要更改位置的分区。 如果省略对分区命名的操作,Azure Databricks 会移动表的位置。

    • LOCATION 路径

      path 必须是字符串字面量。 指定分区或表的新位置。

      原始位置中的文件不会移动到新位置。

  • OWNER TO 主体

    将表的所有权转移给 principal

示例

有关 Delta Lake 添加列和更改列的示例,请参阅

-- 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 TABLE PROPERTIES
> ALTER TABLE dbx.tab1 SET TBLPROPERTIES ('winner' = 'loser');

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