ALTER TABLE

發行項
04/18/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 目錄，您必須具有 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

變更屬性或數據行的位置。
DROP COLUMN

卸除 Delta Lake 數據表中的一或多個數據行或欄位。
重新命名數據行

重新命名 Delta Lake 數據表中的數據行或欄位。
ADD CONSTRAINT

將檢查條件約束、參考外鍵條件約束或參考主鍵條件約束加入數據表。

只有 Unity 目錄中的數據表不支援外鍵和主鍵，而不是 hive_metastore 目錄。
DROP CONSTRAINT

從數據表卸除主鍵、外鍵或檢查條件約束。
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。
- TRUNCATE HISTORY
  
  選擇性地可讓您在 24 小時後起始卸除讀取器加寫入器功能的第二個階段，方法是截斷執行調用命令時的數據表歷程記錄。
  
  截斷數據表歷程記錄會限制您執行 DESCRIBE HISTORY 和執行時間移動查詢的能力。
ADD PARTITION

將一或多個分割區新增至數據表。
DROP PARTITION

從數據表卸除一或多個分割區。
分區。。。SET LOCATION

設定數據分割的位置。
重新命名數據分割

取代數據分割的索引鍵。
復原分割區

指示 Azure Databricks 掃描數據表的位置，並將任何檔案新增至已直接新增至文件系統的數據表。
SETROW FILTER 子句

適用於：Databricks SQL Databricks Runtime 12.2 LTS 和更新版本僅限 Unity 目錄

重要

這項功能處於公開預覽狀態。

將數據列篩選函式加入至數據表。該數據表的所有未來查詢都會接收其數據列的子集，而此數據列會評估為布爾值 TRUE。這適用於細部訪問控制用途，其中函式可以檢查叫用使用者的身分識別和/或群組成員資格，以決定是否要篩選特定數據列。
DROP ROW FILTER

適用於： 僅限 Unity 目錄

重要

這項功能處於公開預覽狀態。

如果有的話，從數據表卸除數據列篩選。未來的查詢將會從數據表傳回所有數據列，而不需要任何自動篩選。
SET TBLPROPERTIES

設定或重設一或多個使用者定義的屬性。
UNSET TBLPROPERTIES

拿掉一或多個使用者定義的屬性。
SET LOCATION

移動數據表的位置。
```
SET LOCATION path
```
- LOCATION path
  
  path 必須是 STRING 常值。指定數據表的新位置。
  
  原始位置中的檔案將不會移至新位置。
[ SET ] OWNER TOprincipal

將資料表的擁有權轉移至 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 目錄

重要

這項功能處於公開預覽狀態。

將受控 Delta Lake 數據表變更為所需的預測優化設定。

根據預設，建立數據表時，行為是 INHERIT 來自架構。

明確啟用或繼承預測優化時，Azure Databricks 會視 Azure Databricks 所認為的適當方式自動叫用數據表上的 OPTIMIZE 和 VACUUM 。如需詳細資訊，請參閱： Delta Lake 的預測優化。

例子

如需 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 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

所需的權限

語法

參數

例子

相關文章

其他資源