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
• 変更する PREDICTIVE OPTIMIZATION

Unity Catalogを使用する場合は、次の動作を行うためにMANAGEのアクセス許可または所有権が必要です。

• SET OWNER TO

その他すべての操作では、テーブルの所有権が必要です。

構文

ALTER TABLE table_name
    { RENAME TO clause |
      ADD COLUMN clause |
      ALTER COLUMN clause |
      DROP COLUMN clause |
      RENAME COLUMN clause |
      DEFAULT COLLATION 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 TO to_table_name

  テーブルの名前を変更します。

  • to_table_name

    新しいテーブル名を識別します。 名前には、 時仕様またはオプション指定を含めてはなりません。

    Unity カタログ テーブルの場合、 to_table_name は table_nameと同じカタログ内にある必要があります。 他のテーブルの場合、 to_table_name は table_nameと同じスキーマ内にある必要があります。

    to_table_nameが修飾されていない場合、現在のスキーマで暗黙的に修飾されます。

• を に追加する

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

• 変更する COLUMN

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

• 落とす COLUMN

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

• 名前を変更 COLUMN

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

• ADD CONSTRAINT

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

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

• DEFAULT COLLATION collation_name

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

  新しい STRING 列のテーブルの既定の照合順序を変更します。 既存の列は、この句の影響を受けません。 既存の列の照合順序を変更するには、ALTER TABLE ... ALTER COLUMN ... COLLATE collation_nameを使用します。

• DROP CONSTRAINT

  テーブルから、主キー制約、外部キー制約、またはチェック制約を削除します。

• DROP FEATURE feature_name [ TRUNCATE HISTORY ]

  適用対象: Databricks Runtime 14.3 LTS 以上

  databricks Runtime 14.3 LTS 以降では、 DROP FEATURE のレガシ サポートを利用できます。 レガシー機能のドキュメントについては、Deltaテーブル機能の削除（レガシー）を参照してください。

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

• Azure Databricks では、従来の動作に代わるすべての DROP FEATURE コマンドに Databricks Runtime 16.3 以降を使用することをお勧めします。

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

  機能を削除すると、テーブル プロトコルに checkpointProtection ライター機能が追加される可能性があります。 詳細については、「Drop Delta テーブル機能」と「プロトコル互換性のためのテーブル機能」を参照してください。

  • feature_name

    Azure Databricks で認識され、テーブルでサポートされる必要がある、STRING リテラルまたは 識別子の形式の機能の名前。

    この機能がテーブルに存在しない場合、Azure Databricks では、DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT が発生します。

  • 履歴を削除

    履歴を切り捨てることによる特徴の削除。 これには、次の 2 つのステージ プロセスが必要です。

履歴を切り捨てることで特徴を削除するには、次の 2 段階のプロセスが必要です。

• 最初の呼び出しで、機能の痕跡がクリアされ、部分的な成功があなたに通知されます。

• 次に、保持期間が終了するまで待ってから、ステートメントを再実行して削除を完了します。

  2 回目の呼び出しの開始が早すぎると、Azure Databricks では、DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD または DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST が発生します。

  テーブル履歴を切り捨てると、DESCRIBE HISTORY を実行してタイム トラベル クエリを実行する機能が制限されます。

• を に追加する

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

• 落とす PARTITION

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

• PARTITION ... SET 場所

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

• 名前を変更 PARTITION

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

• パーティションを復元

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

• SET ROW 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としてデフォルトで行われます。

  予測最適化が明示的に有効になっている場合、または有効として継承された場合、Azure Databricks が適切と判断したテーブルで OPTIMIZE および 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;

-- Alter multiple columns in a single statement
-- Create a table with 3 columns
> CREATE TABLE my_table (num INT, str STRING, bool BOOLEAN) TBLPROPERTIES('delta.feature.allowColumnDefaults' = 'supported')
> DESCRIBE TABLE my_table;
  col_name    data_type     comment
  --------    ---------     -------
       num          int        null
       str       string        null
       bool      boolean       null

-- Update comments on multiple columns
> ALTER TABLE table ALTER COLUMN
   num COMMENT 'number column',
   str COMMENT 'string column';

> DESCRIBE TABLE my_table;
  col_name    data_type      comment
  --------    ---------   -------------
       num          int   number column
       str       string   string column
      bool      boolean            null

-- Can mix different types of column alter
> ALTER TABLE table ALTER COLUMN
   bool COMMENT 'boolean column',
   num AFTER bool,
   str AFTER num,
   bool SET DEFAULT true;

> DESCRIBE TABLE my_table;
  col_name    data_type      comment
  --------    ---------   --------------
      bool      boolean   boolean column
       num          int    number column
       str       string    string column

関連記事

• ADD CONSTRAINT

• ALTER STREAMING TABLE

• ALTER VIEW
• CLUSTER BY
• COMMENT ON
• CREATE TABLE
• DROP CONSTRAINT
• DROP TABLE
• 管理する COLUMN
• 管理する PARTITION
• REPAIR TABLE
• PARTITION