ALTER TABLE

[アーティクル]
04/17/2024

適用対象: 「はい」のチェックマーク Databricks SQL Databricks Runtime

テーブルのスキーマまたはプロパティを変更します。

Delta Lake での型の変更または列の名前変更については、データの書き換えに関するページを参照してください。

テーブルのコメントを変更するには、COMMENT ON を使用することもできます。

STREAMING TABLE を変更するには、ALTER STREAMING TABLE を使用します。

テーブルがキャッシュされている場合、このコマンドは、テーブルのキャッシュされたデータとそのテーブルを参照するすべての依存をクリアします。テーブルまたは依存が次回アクセスされるときに、キャッシュは遅れてフィルされます。

Note

既存の 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

テーブルに 1 つ以上の列を追加します。
ALTER COLUMN

プロパティまたは列の場所を変更します。
DROP COLUMN

Delta Lake テーブルに 1 つ以上の列またはフィールドを削除します。
RENAME COLUMN

Delta Lake テーブルの列またはフィールドの名前を変更します。
ADD CONSTRAINT

チェック制約、情報外部キー制約、または情報主キー制約をテーブルに追加します。

外部キーと主キーは、Unity カタログ内のテーブルでのみサポートされており、hive_metastore カタログ内のテーブルではサポートされていません。
DROP CONSTRAINT

テーブルから、主キー制約、外部キー制約、またはチェック制約を削除します。
DROP FEATURE feature_name [ TRUNCATE HISTORY ]

適用対象: Databricks SQL Databricks Runtime 14.1 以降

Delta Lake テーブルからフィーチャを削除します。

リーダーとライターの両方に影響する機能を削除するには、次の 2 つのステージプロセスが必要です。
- 最初の呼び出しで機能のトレースが消去され、部分的な成功が通知されます。
- その後、保持期間が終了するまで待機し、ステートメントを再実行して削除を完了する必要があります。
  
  2 回目の呼び出しの開始が早すぎると、Azure Databricks では、DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD または DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST が発生します。
詳細については、「テーブル機能とは何ですか?」を参照してください。
- feature_name
  
  Azure Databricks で認識され、テーブルでサポートされる必要がある、STRING リテラルまたは識別子の形式の機能の名前。
  
  サポート対象 feature_names は次のとおりです:
  - 'deletionVectors' または deletionvectors
    - 'v2Checkpoint' または v2checkpoint
  この機能がテーブルに存在しない場合、Azure Databricks では、DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT が発生します。
- TRUNCATE HISTORY
  
  必要に応じて、呼び出しコマンドの実行時にテーブル履歴を切り詰めることで、24 時間後にリーダープラスライター機能を削除する 2 番目のフェーズを開始できます。
  
  テーブル履歴を切り詰めると、DESCRIBE HISTORY を実行したり、タイムトラベルクエリを実行したりする機能が制限されます。
ADD PARTITION

テーブルに 1 つまたは複数のパーティションが追加されます。
DROP PARTITION

テーブルから 1 つ以上のパーティションを削除します。
PARTITION … SET LOCATION

パーティションの場所を設定します。
RENAME PARTITION

パーティションのキーを置き換えます。
RECOVER PARTITIONS

テーブルの場所をスキャンし、ファイルシステムに直接追加されたテーブルにファイルを追加するように Azure Databricks に指示します。
SETROW FILTER 句

適用対象: Databricks SQL Databricks Runtime 12.2 以上 Unity Catalog のみ

重要

この機能はパブリックプレビュー段階にあります。

行フィルター関数をテーブルに追加します。今後そのテーブルからのすべてのクエリでは、関数が Boolean TRUE に評価される行のサブセットを受け取ります。これは、関数が特定の行をフィルタリングするかどうかを決定するために呼び出したユーザーの ID やグループメンバーシップを関数で検査できる、きめ細かいアクセス制御に役立ちます。
DROP ROW FILTER

適用対象: Unity Catalog のみ

重要

この機能はパブリックプレビュー段階にあります。

行フィルターがある場合は、テーブルからドロップします。今後のクエリでは、自動のフィルタリングなしにテーブルからすべての行が返されます。
SET TBLPROPERTIES

1 つ以上のユーザー定義プロパティを設定またはリセットします。
UNSET TBLPROPERTIES

1 つ以上のユーザー定義プロパティを削除します。
SET LOCATION

テーブルの位置を移動します。
```
SET LOCATION path
```
- LOCATION path
  
  path は、STRING リテラルを指定する必要があります。テーブルの新しい場所を指定します。
  
  元の場所にあるファイルは、新しい場所に移動されません。
[ SET ] OWNER TOプリンシパル

テーブルの所有権を principal に転送します。

適用対象: Databricks SQL 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 に行われます。

予測最適化が明示的に有効になっているか、有効にされた OPTIMIZE として継承されると、Azure Databricks によって適切と見なされたテーブルに対して 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

必要なアクセス許可

構文

パラメーター

例

関連記事

その他のリソース