ALTER TABLE

適用対象: Databricks SQL Databricks Runtime

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

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

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

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

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

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 ]

  Applies to: 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 LTS 以降 Unity Catalog のみ

  行フィルター関数をテーブルに追加します。 テーブルに対する後続のすべてのクエリは、関数がブール値 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.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 Catalog のみ

  重要

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

  マネージド Delta Lake テーブルを目的の予測最適化設定に変更します。

  既定では、テーブルが作成されると動作はスキーマからの INHERIT に行われます。

  予測最適化が明示的に有効になっているか、有効 にされた OPTIMIZE として継承されると、Azure Databricks によって適切と見なされたテーブルに対して VACUUM が自動的に呼び出されます。 詳細については、「Unity Catalog 管理テーブルの予測最適化」を参照してください。

例

Delta Lake での制約の追加と変更の例については、以下を参照してください。

• 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