テーブルスキーマを更新します

テーブルはスキーマ進化をサポートしており、データ要件の変化に応じてテーブル構造を変更できます。以下の種類の変更がサポートされています。

任意の位置に新しい列を追加する
既存の列の並べ替え
既存の列の名前を変更する
既存の列の型拡張については、「自動スキーマ進化による型の拡張」を参照してください。

これらの変更は、DDLを使用して明示的に行うか、DMLを使用して暗黙的に行います。

重要

スキーマの更新は、すべての書き込み操作と競合します。 Databricksは、書き込み競合を避けるために、スキーマ変更の調整を行うことを推奨しています。

テーブルスキーマを更新すると、そのテーブルから読み取りを行っているすべてのストリームが終了します。処理を続行するには、構造化ストリーミングの本番運用の考慮事項で説明されている方法を使用してストリームを再開します。

スキーマを明示的に更新して列を追加します

SQL
ALTER TABLE table_name ADD COLUMNS (col_name data_type [COMMENT col_comment] [FIRST|AFTER colA_name], ...)

デフォルトでは、NULL値の許容はtrueです。

ネストされたフィールドに列を追加するには、次のコマンドを使用します：

SQL
ALTER TABLE table_name ADD COLUMNS (col_name.nested_col_name data_type [COMMENT col_comment] [FIRST|AFTER colA_name], ...)

たとえば、ALTER TABLE boxes ADD COLUMNS (colB.nested STRING AFTER field1)を実行する前のスキーマが次のようになっているとします：

- root
| - colA
| - colB
| +-field1
| +-field2

その後のスキーマは次のとおりです：

- root
| - colA
| - colB
| +-field1
| +-nested
| +-field2

注記

ネストされた列の追加は、構造体に対してのみサポートされています。配列とマップはサポートされていません。

スキーマを明示的に更新して、列のコメントまたは順序を変更する

SQL
ALTER TABLE table_name ALTER [COLUMN] col_name (COMMENT col_comment | FIRST | AFTER colA_name)

ネストされたフィールドの列を変更するには、次のコマンドを使用します。

SQL
ALTER TABLE table_name ALTER [COLUMN] col_name.nested_col_name (COMMENT col_comment | FIRST | AFTER colA_name)

たとえば、ALTER TABLE boxes ALTER COLUMN colB.field2 FIRSTを実行する前のスキーマが次のようになっているとします：

- root
| - colA
| - colB
| +-field1
| +-field2

その後のスキーマは次のとおりです：

- root
| - colA
| - colB
| +-field2
| +-field1

列を置き換えるためにスキーマを明示的に更新します

SQL
ALTER TABLE table_name REPLACE COLUMNS (col_name1 col_type1 [COMMENT col_comment1], ...)

例えば、以下のようなDDLを実行する場合：

SQL
ALTER TABLE boxes REPLACE COLUMNS (colC STRING, colB STRUCT<field2:STRING, nested:STRING, field1:STRING>, colA STRING)

前のスキーマが次の場合：

- root
| - colA
| - colB
| +-field1
| +-field2

その後のスキーマは次のとおりです：

- root
| - colC
| - colB
| +-field2
| +-nested
| +-field1
| - colA

スキーマを明示的に更新して列の名前を変更する

注記

この機能は、Databricks Runtime 10.4 LTS 以降で使用できます。

列の既存のデータを書き換えずに列の名前を変更するには、テーブルの列マッピングを有効にする必要があります。「Delta Lake 列マッピングを使用した列の名前変更と削除」を参照してください。

列の名前を変更するには：

SQL
ALTER TABLE table_name RENAME COLUMN old_col_name TO new_col_name

ネストされたフィールドの名前を変更するには：

SQL
ALTER TABLE table_name RENAME COLUMN col_name.old_nested_field TO new_nested_field

たとえば、次のコマンドを実行するとします：

SQL
ALTER TABLE boxes RENAME COLUMN colB.field1 TO field001

以前のスキーマが次の場合：

- root
| - colA
| - colB
| +-field1
| +-field2

その後のスキーマは次のようになります：

- root
| - colA
| - colB
| +-field001
| +-field2

Delta Lake 列マッピングを使用した列の名前変更と削除を参照してください。

スキーマを明示的に更新して列をドロップする

注記

この機能は、Databricks Runtime 11.3 LTS 以降で使用できます。

データファイルを書き換えることなく、メタデータのみの操作として列をドロップするには、テーブルの列マッピングを有効にする必要があります。 Delta Lake 列マッピングを使用した列の名前変更と削除を参照してください。

重要

メタデータから列を削除しても、ファイル内の列の基になるデータは削除されません。ドロップされた列データをパージするには、 REORG TABLE を使用してファイルを書き換えます。その後、vacuum を使用して、ドロップされた列データを含むファイルを物理的に削除できます。

列を削除するには：

SQL
ALTER TABLE table_name DROP COLUMN col_name

複数の列を削除するには：

SQL
ALTER TABLE table_name DROP COLUMNS (col_name_1, col_name_2)

スキーマを明示的に更新して列のタイプまたは名前を変更する

列のタイプや名前を変更したり、テーブルを書き換えて列を削除したりできます。これを行うには、 overwriteSchema オプションを使用します。

次の例は、列の型を変更する方法を示しています：

Python
(spark.read.table(...)
  .withColumn("birthDate", col("birthDate").cast("date"))
  .write
  .mode("overwrite")
  .option("overwriteSchema", "true")
  .saveAsTable(...)
)

次の例は、列名の変更を示しています：

Python
(spark.read.table(...)
  .withColumnRenamed("dateOfBirth", "birthDate")
  .write
  .mode("overwrite")
  .option("overwriteSchema", "true")
  .saveAsTable(...)
)

スキーマ進化の有効化

次のいずれかの方法を使用してスキーマ進化を有効にします。

INSERT WITH SCHEMA EVOLUTION構文を使用してください。 INSERTステートメントで動作します。SQL構文にWITH SCHEMA EVOLUTIONを含めてください。
MERGE WITH SCHEMA EVOLUTION構文を使用してください。 MERGEステートメントで動作します。SQL構文にWITH SCHEMA EVOLUTIONを含めるか、Databricks APIで.withSchemaEvolution()を使用してください。
mergeSchemaオプションを設定します： バッチ書き込みまたはストリーミング書き込みに対応します。個々の書き込み操作に.option("mergeSchema", "true")設定します。
Spark構成を設定します（レガシー）： SparkSession全体に対してspark.databricks.delta.schema.autoMerge.enabledをtrueに設定します。本番運用での使用はお勧めしません。

Databricksは、Spark構成を設定するのではなく、 WITH SCHEMA EVOLUTION構文またはmergeSchemaオプションを使用して、各書き込み操作のスキーマ進化を有効にすることを推奨しています。

書き込み操作でスキーマ進化を有効にするためにオプションまたは構文を使用する場合、これはSparkの設定よりも優先されます。

新しい列を追加するための書き込みのスキーマ進化を有効にする

ソースクエリには存在するが、ターゲットテーブルには存在しないカラムは、スキーマ進化が有効な場合、書き込みトランザクションの一部として自動的に追加されます。スキーマ進化の有効化を参照してください。

新しい列を追加するときに大文字と小文字が保持されます。新しい列は、テーブルスキーマの最後に追加されます。追加の列が構造体内にある場合、それらはターゲットテーブルの構造体の末尾に追加されます。

INSERT のスキーマ進化構文

INSERTステートメントでWITH SCHEMA EVOLUTION句を使用すると、スキーマ進化を有効にできます。

SQL
INSERT WITH SCHEMA EVOLUTION INTO target_table
SELECT * FROM source_table

source_tableに対するクエリが、対象テーブルに存在しない列を返す場合、それらの列は自動的にtarget_tableスキーマに追加されます。既存の行には、新しい列に対してNULL値が割り当てられます。

DataFrame API を使用したスキーマ進化を伴う INSERT を実行

次の例は、バッチ書き込み操作で mergeSchema オプションを使用する方法を示しています。

Python
Scala

Python
(spark.read
  .table("source_table")
  .write
  .option("mergeSchema", "true")
  .mode("append")
  .saveAsTable("target_table")
)

Scala
spark.read
  .table("source_table")
  .write
  .option("mergeSchema", "true")
  .mode("append")
  .saveAsTable("target_table")

ストリーミングにおけるスキーマ進化を伴うINSERT

次の例は、 Auto Loaderで mergeSchema オプションを使用する方法を示しています。「Auto Loaderとは」を参照してください。

Python
(spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "json")
  .option("cloudFiles.schemaLocation", "<path-to-schema-location>")
  .load("<path-to-source-data>")
  .writeStream
  .option("mergeSchema", "true")
  .option("checkpointLocation", "<path-to-checkpoint>")
  .trigger(availableNow=True)
  .toTable("table_name")
)

マージのための自動スキーマ進化

スキーマ進化を使用すると、マージでターゲットテーブルとソーステーブルの間のスキーマの不一致を解決できます。次の 2 つのケースを処理します。

列はソーステーブルには存在しますが、ターゲットテーブルには存在せず、挿入または更新アクションの割り当てで名前によって指定されます。あるいは、 UPDATE SET *またはINSERT *アクションが存在します。

その列はターゲットスキーマに追加され、その値はソースの対応する列から入力されます。
- これは、マージソースの列名と構造がターゲット割り当てと完全に一致する場合にのみ適用されます。
- 新しい列はソーススキーマに存在する必要があります。アクション句で新しい列を割り当てても、その列は定義されません。
これらの例では、スキーマ進化が可能になります。
SQL
```
-- The column newcol is present in the source but not in the target. It will be added to the target.
UPDATE SET target.newcol = source.newcol

-- The field newfield doesn't exist in struct column somestruct of the target. It will be added to that struct column.
UPDATE SET target.somestruct.newfield = source.somestruct.newfield

-- The column newcol is present in the source but not in the target.
-- It will be added to the target.
UPDATE SET target.newcol = source.newcol + 1

-- Any columns and nested fields in the source that don't exist in target will be added to the target.
UPDATE SET *
INSERT *
```
これらの例は、列newcolがsourceスキーマに存在しない場合、スキーマ進化をトリガーしません。
SQL
```
UPDATE SET target.newcol = source.someothercol
UPDATE SET target.newcol = source.x + source.y
UPDATE SET target.newcol = source.output.newcol
```
カラムはターゲット表に存在しますが、ソース表には存在しません。

ターゲット・スキーマは変更されません。これらの列は、次のとおりです。
- UPDATE SET *は変更されません。
- はINSERT *のNULLに設定されています。
- action 句で割り当てられている場合は、明示的に変更される可能性があります。
例えば：
SQL
```
UPDATE SET *  -- The target columns that are not in the source are left unchanged.
INSERT *  -- The target columns that are not in the source are set to NULL.
UPDATE SET target.onlyintarget = 5  -- The target column is explicitly updated.
UPDATE SET target.onlyintarget = source.someothercol  -- The target column is explicitly updated from some other source column.
```

自動スキーマ進化を手動で有効にする必要があります。スキーマ進化の有効化を参照してください。

注記

Databricks Runtime 12.2 LTS 以降では、ソーステーブルに存在する列と構造体フィールドを、挿入アクションまたは更新アクションで名前で指定できます。 Databricks Runtime 11.3 LTS 以前では、マージによるスキーマ進化に使用できるのは、INSERT * または UPDATE SET * アクションのみです。

Databricks Runtime 13.3 LTS 以降では、map<int, struct<a: int, b: int>> などのマップ内にネストされた構造体でスキーマ進化を使用できます。

マージのスキーマ進化構文

Databricks Runtime 15.4 LTS以降では、 SQLまたはテーブルAPIsを使用してマージステートメントでスキーマ進化を指定できます。

SQL
Python
Scala

SQL
MERGE WITH SCHEMA EVOLUTION INTO target
USING source
ON source.key = target.key
WHEN MATCHED THEN
  UPDATE SET *
WHEN NOT MATCHED THEN
  INSERT *
WHEN NOT MATCHED BY SOURCE THEN
  DELETE

Python
from delta.tables import *

(targetTable
  .merge(sourceDF, "source.key = target.key")
  .withSchemaEvolution()
  .whenMatchedUpdateAll()
  .whenNotMatchedInsertAll()
  .whenNotMatchedBySourceDelete()
  .execute()
)

Scala
import io.delta.tables._

targetTable
  .merge(sourceDF, "source.key = target.key")
  .withSchemaEvolution()
  .whenMatched()
  .updateAll()
  .whenNotMatched()
  .insertAll()
  .whenNotMatchedBySource()
  .delete()
  .execute()

スキーマ進化を伴うマージ操作の例

ここでは、スキーマ進化を伴う場合と伴わない場合のmerge操作の影響の例をいくつか示します。

列	クエリー（SQL の場合）	スキーマ進化なしの動作（既定）	スキーマの進化に伴う動作
ターゲット列： `key, value` ソース列： `key, value, new_value`	SQL `MERGE INTO target_table t USING source_table s ON t.key = s.key WHEN MATCHED THEN UPDATE SET * WHEN NOT MATCHED THEN INSERT *`	テーブルのスキーマは変更されません。列`key`、`value`のみが更新/挿入されます。	テーブルスキーマが`(key, value, new_value)`に変更されます。一致する既存のレコードは、ソース内の`value`と`new_value`で更新されます。新しい行がスキーマ`(key, value, new_value)`とともに挿入されます。
ターゲット列： `key, old_value` ソース列： `key, new_value`	SQL `MERGE INTO target_table t USING source_table s ON t.key = s.key WHEN MATCHED THEN UPDATE SET * WHEN NOT MATCHED THEN INSERT *`	`UPDATE` ターゲット列`old_value`がソースにないため、`INSERT`アクションはエラーをスローします。	テーブルスキーマが`(key, old_value, new_value)`に変更されます。一致する既存のレコードは、ソース内の`new_value`で更新され、`old_value`は変更されません。`old_value`に指定された`key`、`new_value`、および`NULL`を使用して新しいレコードが挿入されます。
ターゲット列： `key, old_value` ソース列： `key, new_value`	SQL `MERGE INTO target_table t USING source_table s ON t.key = s.key WHEN MATCHED THEN UPDATE SET new_value = s.new_value`	`UPDATE` 列`new_value`がターゲットテーブルに存在しないため、エラーがスローされます。	テーブルスキーマが `(key, old_value, new_value)`に変更されます。一致する既存のレコードは、ソースの`new_value`で更新され、`old_value`は変更されません。一致しないレコードは`new_value`に入力`NULL`。注 (1) を参照してください。
ターゲット列： `key, old_value` ソース列： `key, new_value`	SQL `MERGE INTO target_table t USING source_table s ON t.key = s.key WHEN NOT MATCHED THEN INSERT (key, new_value) VALUES (s.key, s.new_value)`	`INSERT` 列`new_value`がターゲットテーブルに存在しないため、エラーがスローされます。	テーブルスキーマが `(key, old_value, new_value)`に変更されます。新しいレコードは、指定された [ `key`]、[ `new_value`]、および `NULL` [ `old_value`] で挿入。既存のレコードはnew_value``NULL入力されていません`old_value`変更されていません。注 (1) を参照してください。

(1) この動作は、Databricks Runtime 12.2 LTS 以降で使用できます。Databricks Runtime 11.3 LTS 以下では、この条件でエラーが発生します。

マージされた列を除外する

Databricks Runtime 12.2 LTS 以降では、マージ条件で EXCEPT 句を使用して列を明示的に除外できます。 EXCEPT キーワードの動作は、スキーマ進化が有効になっているかどうかによって異なります。

スキーマ進化が無効な場合、EXCEPT キーワードがターゲットテーブルの列のリストに適用され、UPDATE または INSERT アクションから列を除外できるようになります。除外された列は null に設定されます。

スキーマ進化が有効な場合、EXCEPT キーワードがソーステーブルの列のリストに適用され、スキーマ進化から列を除外することができます。ターゲットに存在しないソースの新しい列が EXCEPT 句にリストされている場合、その列はターゲットスキーマに追加されません。除外される列がターゲットに既に存在する場合、null に設定されます。

次の例は、構文を示しています。

列	クエリー（SQL の場合）	スキーマ進化なしの動作（既定）	スキーマの進化に伴う動作
ターゲット列： `id, title, last_updated` ソース列： `id, title, review, last_updated`	SQL `MERGE INTO target t USING source s ON t.id = s.id WHEN MATCHED THEN UPDATE SET last_updated = current_date() WHEN NOT MATCHED THEN INSERT * EXCEPT (last_updated)`	一致した行は、`last_updated` フィールドが現在の日付に設定されて更新されます。新しい行は、`id` と `title` の値を使って挿入されます。除外されたフィールド `last_updated` は `null` に設定されます。フィールド `review` はターゲットにないため無視されます。	一致した行は、`last_updated` フィールドが現在の日付に設定されて更新されます。スキーマは、フィールド `review` を追加するように進化します。新しい行は、`null` に設定される `last_updated` を除き、すべてのソースフィールドを使用して挿入されます。
ターゲット列： `id, title, last_updated` ソース列： `id, title, review, internal_count`	SQL `MERGE INTO target t USING source s ON t.id = s.id WHEN MATCHED THEN UPDATE SET last_updated = current_date() WHEN NOT MATCHED THEN INSERT * EXCEPT (last_updated, internal_count)`	`INSERT` 列`internal_count`がターゲットテーブルに存在しないため、エラーがスローされます。	一致した行は、`last_updated` フィールドが現在の日付に設定されて更新されます。`review` フィールドはターゲットテーブルに追加されますが、`internal_count` フィールドは無視されます。新たに挿入された行では、`last_updated` が `null` に設定されます。

列

クエリー（SQL の場合）

スキーマ進化なしの動作（既定）

スキーマの進化に伴う動作

ターゲット列： id, title, last_updated

ソース列： id, title, review, last_updated

SQL
MERGE INTO target t
USING source s
ON t.id = s.id
WHEN MATCHED
  THEN UPDATE SET last_updated = current_date()
WHEN NOT MATCHED
  THEN INSERT * EXCEPT (last_updated)

一致した行は、last_updated フィールドが現在の日付に設定されて更新されます。新しい行は、id と title の値を使って挿入されます。除外されたフィールド last_updated は null に設定されます。フィールド review はターゲットにないため無視されます。

一致した行は、last_updated フィールドが現在の日付に設定されて更新されます。スキーマは、フィールド review を追加するように進化します。新しい行は、null に設定される last_updated を除き、すべてのソースフィールドを使用して挿入されます。

ターゲット列： id, title, last_updated

ソース列： id, title, review, internal_count

SQL
MERGE INTO target t
USING source s
ON t.id = s.id
WHEN MATCHED
  THEN UPDATE SET last_updated = current_date()
WHEN NOT MATCHED
  THEN INSERT * EXCEPT (last_updated, internal_count)

INSERT 列internal_countがターゲットテーブルに存在しないため、エラーがスローされます。

一致した行は、last_updated フィールドが現在の日付に設定されて更新されます。review フィールドはターゲットテーブルに追加されますが、internal_count フィールドは無視されます。新たに挿入された行では、last_updated が null に設定されます。

Spark構成でスキーマ進化を有効にする（従来型）

Sparkの設定spark.databricks.delta.schema.autoMerge.enabledをtrueに変更すると、現在のSparkSession内のすべての書き込み操作でスキーマ進化が有効になります。

Python
Scala
SQL

Python
spark.conf.set("spark.databricks.delta.schema.autoMerge.enabled", True)

Scala
spark.conf.set("spark.databricks.delta.schema.autoMerge.enabled", true)

SQL
SET spark.databricks.delta.schema.autoMerge.enabled=true

重要

このアプローチは本番運用での使用には推奨されません。代わりに、書き込み操作ごとにスキーマ進化を有効にします。

INSERTおよびバッチ/ストリーミング書き込みの場合は、 .option("mergeSchema", "true")またはINSERT WITH SCHEMA EVOLUTIONを使用してください。
MERGEステートメントの場合は、 MERGE WITH SCHEMA EVOLUTIONを使用してください。

セッション全体にわたる設定を行うと、複数の操作にわたって意図しないスキーマ変更が発生する可能性があり、どの操作がスキーマを変化させたのかを推論することが難しくなります。

書き込み操作でスキーマ進化を有効にするためにオプションまたは構文を使用する場合、これはSparkの設定よりも優先されます。

テーブルスキーマを置き換える

デフォルトでは、テーブル内のデータを上書きしてもスキーマは上書きされません。replaceWhereを使用せずにmode("overwrite")を使用してテーブルを上書きする場合でも、書き込まれるデータのスキーマを上書きする必要がある場合があります。overwriteSchemaオプションをtrueに設定して、テーブルのスキーマとパーティションを置き換えます：

Python
df.write.option("overwriteSchema", "true")

重要

動的パーティションの上書きを使用する場合、overwriteSchemaをtrueとして指定することはできません。

スキーマを明示的に更新して列を追加します​

スキーマを明示的に更新して、列のコメントまたは順序を変更する​

列を置き換えるためにスキーマを明示的に更新します​

スキーマを明示的に更新して列の名前を変更する​

スキーマを明示的に更新して列をドロップする​

スキーマを明示的に更新して列のタイプまたは名前を変更する​

スキーマ進化の有効化​

新しい列を追加するための書き込みのスキーマ進化を有効にする​

INSERT のスキーマ進化構文​

DataFrame API を使用したスキーマ進化を伴う INSERT を実行​

ストリーミングにおけるスキーマ進化を伴うINSERT​

マージのための自動スキーマ進化​

マージのスキーマ進化構文​

スキーマ進化を伴うマージ操作の例​

マージされた列を除外する​

Spark構成でスキーマ進化を有効にする（従来型）​

テーブルスキーマを置き換える​

スキーマを明示的に更新して列を追加します

スキーマを明示的に更新して、列のコメントまたは順序を変更する

列を置き換えるためにスキーマを明示的に更新します

スキーマを明示的に更新して列の名前を変更する

スキーマを明示的に更新して列をドロップする

スキーマを明示的に更新して列のタイプまたは名前を変更する

スキーマ進化の有効化

新しい列を追加するための書き込みのスキーマ進化を有効にする

INSERT のスキーマ進化構文

DataFrame API を使用したスキーマ進化を伴う INSERT を実行

ストリーミングにおけるスキーマ進化を伴うINSERT

マージのための自動スキーマ進化

マージのスキーマ進化構文

スキーマ進化を伴うマージ操作の例

マージされた列を除外する

Spark構成でスキーマ進化を有効にする（従来型）

テーブルスキーマを置き換える