ALTER TABLE (Databricks SQL)

更改表的架构或属性。

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

若要更改表的注释,请使用 COMMNENT on

如果对表进行缓存,则该命令将清除该表及其引用的所有依赖项的缓存数据。 下次访问表或依赖项时,将延迟填充缓存。

语法

ALTER TABLE table_name
   { RENAME clause |
     ADD COLUMN clause |
     ALTER COLUMN clause |
     ADD CONSTRAINT clause |
     DROP CONSTRAINT clause |
     SET LOCATION clause |
     ADD PARTITION clause |
     DROP PARTITION clause |
     RENAME PARTITION clause |
     RECOVER PARTITIONS clause |
     SET TBLPROPERTIES clause |
     UNSET TBLPROPERTIES clause |
     SET LOCATION clause }

参数

  • table_name

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

  • 重命名为 to_table_name

    将表重命名为同一数据库中的新表。

  • 添加列

    数据源不支持此子句 JDBC

    将一个或多个列添加到表中,或添加到增量 Lake 表中的现有列。

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

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

      除非 FIRST 指定或,否则 AFTER name 将在末尾追加列或字段。

    • field_name

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

    • 注释注释

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

    • FIRST

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

    • 标识符

      如果指定,则将在字段或列的后面立即添加列或字段 identifier

  • 更改列

    更改属性或列的位置。

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

      要更改的列的名称。

    • field_name

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

    • 注释注释

      更改列的说明 column_namecomment 必须是字符串文本。

    • FIRSTAFTER 标识符

      将列从其当前位置移动到前面 (FIRST) 或立即移动 AFTERidentifier 。 仅当是增量表时才支持此子句 table_name

    • 设置 NOT nullDROP not null

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

  • 添加约束 constraint_name 检查 ( 条件 )

    向增量 Lake 表添加 check 约束。

    • constraint_name

      在表中唯一的标识符。

    • 检查 ( 条件 )

      返回布尔值的确定性表达式。

      condition可能由文本、表中的列标识符和确定性的内置 SQL 函数或运算符组成,但除外:

      condition 不得包含任何 condition

      要使检查约束满足要求 Azure Databricks 它必须计算为 true

      增量 Lake 验证检查约束对新数据和现有数据的有效性。 如果任何现有行违反约束,则会引发错误。

  • DROP CONSTRAINT constraint_name

    从增量 Lake 表中删除 check 约束。

  • ADD PARTITION

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

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

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

    • PARTITION 子句

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

    • 位置路径

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

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

      如果文件在填充分区的位置存在,则必须与 data_source 表的和选项兼容。

  • DROP PARTITION

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

    增量 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
    
  • 恢复分区

    此子句不适用于 Delta Lake 表。

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

  • SET TBLPROPERTIES

    设置表的一个或多个用户定义属性。 属性是键值对。 如果属性的键存在,则对应的值将替换为新的值。 如果属性的键不存在,则键值对将被添加到属性中。

    SET TBLPROPERTIES ( { property_key = property_val } [, ...] )
    
    • property_key

      属性键。 键可以包含由点分隔的 个或多个标识符或字符串文本。

      属性键必须唯一。

    • property_val

      属性的新值。 该值必须是 BOOLEAN、STRING、INTEGER 或 DECIMAL 文本。

  • UNSET TBLPROPERTIES

    删除 的一个或多个用户定义属性 table_name

    UNSET TBLPROPERTIES [ IF EXISTS ] ( property_key [, ...] )
    
    • IF EXISTS

      除非 IF EXISTS 指定 ,否则如果未设置 属性,则会进行 raided。

    • property_key

      键可以包含由点分隔的 个或多个标识符或字符串文本。

      属性键必须唯一。

  • SET LOCATION

    移动分区或表的位置。

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

    [ PARTITION clause ] SET LOCATION path
    
    • PARTITION 子句

      (可选)标识要更改其位置的分区。 如果省略对分区Azure Databricks将移动表的位置。

    • LOCATION 路径

      path 必须是 STRING 文本。 指定分区或表的新位置。

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

示例

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

-- RENAME table
> DESC 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
> DESC 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
> DESC 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
> DESC 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
> DESC 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
> DESC 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

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