ALTER TABLE

適用対象: Databricks SQL Databricks Runtime

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

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

テーブルのコメントを変更するには、COMMENT ON を使用します。

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

必要なアクセス許可

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 |
     ADD PARTITION clause |
     DROP PARTITION clause |
     RENAME PARTITION clause |
     RECOVER PARTITIONS clause |
     SET TBLPROPERTIES clause |
     UNSET TBLPROPERTIES clause |
     SET SERDE clause |
     SET LOCATION clause |
     SET OWNER TO clause }

パラメーター

• table_name

  変更するテーブルを識別します。 この名前には、テンポラル仕様を含めることはできません。 テーブルが見つからない場合、Azure Databricks で TABLE_OR_VIEW_NOT_FOUND エラーが発生します。

• RENAME TO to_table_name

  同じスキーマ内のテーブルの名前を変更します。

  • to_table_name

    新しいテーブル名を識別します。 この名前には、テンポラル仕様を含めることはできません。

• ADD COLUMN

  この句は、JDBC データ ソースではサポートされていません。

  1 つ以上の列をテーブルに追加するか、Delta Lake テーブル内の既存の列にフィールドを追加します。

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

  • column_identifier

    追加する列の名前です。 名前はテーブル内で一意にする必要があります。

    FIRST または AFTER name が指定されていない限り、列またはフィールドは末尾に追加されます。

  • field_name

    既存の列に追加するフィールドの完全修飾名。 入れ子になったフィールドに対するパスのコンポーネントがすべて存在し、フィールド名自体が一意である必要があります。

  • DEFAULT default_expression

    適用対象:Databricks SQL SQL ウェアハウス バージョン 2022.35 以降 Databricks Runtime 11.2 以降

    列が指定されていない場合に INSERT と MERGE ... INSERT で使われる列の DEFAULT 値を定義します。

    既定値が指定されていない場合、Null 許容列には DEFAULT NULL が暗黙的に使用されます。

    default_expression は、リテラル、および組み込みの SQL 関数か演算子で構成することができます。ただし、次のものは除きます。

    • 集計関数
      • 分析ウィンドウ関数
      • 順位付け関数。
      • テーブル値ジェネレーター関数

    default_expression には、サブクエリを含めることはできません。

    DEFAULT は CSV、JSON、PARQUET、と ORC ソースでサポートされています。

  • data_type

    列かフィールドのデータ型を指定します。 Azure Databricks でサポートされているすべてのデータ型が、すべてのデータ ソースでサポートされているわけではありません。

  • COMMENT コメント

    追加された列またはフィールドを記述する省略可能な STRING リテラル。

  • FIRST

    指定した場合、列はテーブルの最初の列として追加されます。または、フィールドが、含まれている構造体の最初のフィールドとして追加されます。

  • AFTER 識別子

    指定した場合、フィールドまたは列 identifier の直後に列またはフィールドが追加されます。

• ALTER COLUMN

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

  { { ALTER | CHANGE } [COLUMN] { column_identifier | field_name }
    { COMMENT comment |
      { FIRST | AFTER column_identifier } |
      { SET | DROP } NOT NULL |
      SET DEFAULT clause |
      DROP DEFAULT |
      SYNC IDENTITY } }
  

  • column_identifier

    変更する列の名前。

  • field_name

    変更するフィールドの完全修飾名。 入れ子になったフィールドへのパスのすべてのコンポーネントが存在する必要があります。

  • COMMENT コメント

    column_name 列の説明を変更します。 comment は文字列リテラルである必要があります。

  • FIRST または AFTER identifier

    列を現在の位置から前 (FIRST) または identifier のすぐ AFTER に移動します。 この句は、table_name が Delta テーブルの場合にのみサポートされます。

  • SET NOT NULL または DROP NOT NULL

    有効な列値のドメインを変更して null を除外 (SET NOT NULL) するか、null を含め (DROP NOT NULL) ます。 このオプションは、Delta Lake テーブルでのみサポートされます。 Delta Lake では、制約が既存のすべてのデータと新しいデータに対して有効になります。

  • SYNC IDENTITY

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

    ID 列のメタデータを実際のデータと同期します。 ID 列に独自の値を書き込む場合、メタデータに準拠していない可能性があります。 このオプションでは、状態が評価され、実際のデータと一致するようにメタデータが更新されます。 このコマンドの後、次に自動的に割り当てられる ID 値は start + (n + 1) * step から開始されます。ここで、n は start + n * step >= max() を満たす最小の値です (正の手順の場合)。

    このオプションは、Delta Lake テーブルの ID 列でのみサポートされます。

  • DROP DEFAULT

    適用対象:Databricks SQL SQL ウェアハウス バージョン 2022.35 以降 Databricks Runtime 11.2 以降

    列から既定の式を削除します。 Null 許容列の場合、これは SET DEFAULT NULL と同じになります。 NOT NULL で定義された列の場合、今後すべての INSERT 操作で値を指定する必要があります

• DEFAULT default_expression

  適用対象:Databricks SQL SQL ウェアハウス バージョン 2022.35 以降 Databricks Runtime 11.2 以降

  列が指定されていない場合に INSERT と MERGE ... INSERT で使われる列の DEFAULT 値を定義します。

  既定値が指定されていない場合、Null 許容列には DEFAULT NULL が暗黙的に使用されます。

  default_expression は、リテラル、組み込みの SQL 関数か演算子で構成することができます。ただし、次のものは除きます。

  • 集計関数
  • 分析ウィンドウ関数
  • 順位付け関数。
  • テーブル値ジェネレーター関数

  default_expression には、サブクエリを含めることはできません。

  DEFAULT は CSV、JSON、ORC、と PARQUET ソースでサポートされています。

  新しく追加された列の既定値を定義すると、その既定値はすべての既存の行に適用されます。 既定値に rand や current_timestamp のような非決定論的関数が含まれている場合、その値は ALTER TABLE が実行されたときに一度だけ計算され、既存の行に定数として適用されます。 新しく挿入された行では、既定の式は行ごとに 1 回実行されます。

  ALTER COLUMN を使って既定値を設定した場合、既存の行はその変更の影響を受けません。

• data_type

  列かフィールドのデータ型を指定します。 Azure Databricks でサポートされているすべてのデータ型が、すべてのデータ ソースでサポートされているわけではありません。

• DROP COLUMN

  重要

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

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

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

  列またはフィールドを削除する場合は、依存 Check 制約と生成された列を削除する必要があります。

  要件については、「Delta Lake の列マッピングを使用して列の名前変更と削除を行う」をご覧ください。

  DROP [COLUMN | COLUMNS] [ IF EXISTS ] ( { {column_identifier | field_name} [, ...] )
  

  • IF EXISTS

    IF EXISTS を指定すると、Azure Databricks は、存在しない列を削除しようとしても無視します。 それ以外の場合、存在しない列の削除によってエラーが発生します。

  • column_identifier

    既存の列の名前。

  • field_name

    既存のフィールドの完全修飾名。

• RENAME COLUMN

  重要

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

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

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

  列またはフィールドの名前を変更する場合は、依存 Check 制約と生成された列も変更する必要があります。 当該の列を使用する主キーと外部キーはすべて削除されます。 外部キーの場合は、外部キーが定義されているテーブルを所有している必要があります。

  要件については、「Delta Lake の列マッピングを使用して列の名前変更と削除を行う」をご覧ください。

  RENAME COLUMN { column_identifier TO to_column_identifier|
                  field_name TO to_field_identifier }
  

  • column_identifier

    列の既存の名前。

  • to_column_identifier

    新しい列識別子。 識別子はテーブル内で一意である必要があります。

  • field_name

    フィールドの既存の完全修飾名。

  • to_field_identifier

    新しいフィールド識別子。 識別子は、ローカル構造体内で一意である必要があります。

• ADD CONSTRAINT

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

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

• DROP CONSTRAINT

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

• ADD PARTITION

  指定した場合、テーブルに 1 つ以上のパーティションが追加されます。 Delta Lake テーブルでは、パーティションの追加はサポートされていません。

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

  • IF NOT EXISTS

    パーティションが既に存在する場合に、ステートメントを無視するように Azure Databricks に指示する省略可能な句。

  • PARTITION 句

    追加するパーティション。 パーティション キーは、テーブルのパーティション分割と一致し、値に関連付けられている必要があります。 パーティションが既に存在する場合は、IF NOT EXISTS が指定されていない限り、エラーが発生します。

  • LOCATION パス

    path は、パーティションを指すオプションの場所を表す文字列リテラルである必要があります。

    場所が指定されていない場合、場所はテーブルの場所とパーティション キーから派生します。

    その場所にファイルが存在する場合は、パーティションを設定し、テーブルとそのオプションの data_source と互換性がある必要があります。

• DROP PARTITION

  この句を指定すると、テーブルから 1 つ以上のパーティションが削除されます。必要に応じて、パーティションの場所にあるファイルも削除されます。

  Delta 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
  

  • from_partition_clause

    名前を変更するパーティションの定義。

  • to_partition_clause

    このパーティションの新しい定義。 同じキーを持つパーティションは、既に存在していてはなりません。

• RECOVER PARTITIONS

  この句は、Delta Lake テーブルには適用されません。

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

• SET TBLPROPERTIES

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

• UNSET TBLPROPERTIES

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

• SET LOCATION

  パーティションまたはテーブルの位置を移動します。

  Delta Lake は、Delta Lake テーブルの個々のパーティションの移動をサポートしていません。

  [ PARTITION clause ] SET LOCATION path
  

  • PARTITION 句

    必要に応じて、場所を変更するパーティションを識別します。 パーティションの名前を省略した場合 Azure Databricks はテーブルの場所を移動します。

  • LOCATION パス

    path は文字列リテラルである必要があります。 パーティションまたはテーブルの新しい場所を指定します。

    元の場所にあるファイルは、新しい場所に移動されません。

• [ SET ] OWNER TO プリンシパル

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

  適用対象:Databricks SQL SQL ウェアハウス バージョン 2022.35 以降 Databricks Runtime 11.2 以降

  SET は省略可能なキーワードとして使用できます。

例

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

関連記事

• ALTER VIEW
• ADD CONSTRAINT
• COMMENT ON
• CREATE TABLE
• DROP CONSTRAINT
• DROP TABLE
• REPAIR TABLE
• PARTITION