ストリーミングテーブルのスキーマを更新する (使用するもの: `ALTER TABLE`

備考

ベータ版

ALTER TABLE を使用したストリーミングテーブルスキーマの更新はベータ版です。アクセスをリクエストするには、ベータ版にサインアップしてください。

ALTER TABLE 列レベルのスキーマ変更（列の追加、削除、名前変更、および列の型の拡張）をサポートしています。これらはメタデータのみのオペレーションです。これらは完全な更新を必要とせず、ストリーミングのResetをせず、データを再取り込みしません。

注記

Auto Loader は独自のソーススキーマを追跡するため、DROP COLUMN および RENAME COLUMN が Auto Loader によってバックアップされたテーブルに完全には適用されない場合があります。Auto Loader のソーススキーマが更新されないを参照してください。

サポートされている操作

すべての操作には、Unity Catalog に発行するパイプラインが必要です。CREATE TABLE ... FLOW で作成されたマネージドテーブルを除き、これらには外部メタデータも必要です。一部の操作には追加の要件があります：

オペレーション	追加要件
列を追加	追加の要件はありません。
DROP COLUMN	列マッピングモード `name`
列の名前を変更	列マッピングモード `name`
ALTER COLUMN ... TYPE	型の拡張

オペレーション	追加要件
列を追加	追加の要件はありません。
DROP COLUMN	列マッピングモード `name`
列の名前を変更	列マッピングモード `name`
ALTER COLUMN ... TYPE	型の拡張

外部メタデータを有効にする

列操作には、ストリーミングテーブルを所有するパイプライン上の外部メタデータが必要です。有効になっていない場合、コマンドはエラーで失敗します。ストリーミングテーブルおよびマテリアライズドビューへの外部データアクセスの有効化を参照してください。

注記

CREATE TABLE ... FLOW 構文で作成されたパイプライン内のマネージドテーブルには、外部メタデータは必要ありません。

パイプライン構成で pipelines.externalMetadata.enabled を true に設定します：

JSON
{
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

Lakeflow Pipelines Editorでこれを設定するには、パイプライン設定を選択し、値 true を持つ pipelines.externalMetadata.enabled を追加します。

有効にした後、パイプラインの更新を1回実行します。それ以降は、ALTER TABLE列のオペレーションが利用可能です。

列マッピングを有効にする

DROP COLUMN および RENAME COLUMN には、列マッピングモード name が必要です。パイプラインの定義で設定します。これは次回の更新時に適用されます：

SQL
CREATE OR REFRESH STREAMING TABLE orders
  TBLPROPERTIES ('delta.columnMapping.mode' = 'name')
  AS SELECT * FROM STREAM read_files('/Volumes/main/sales/raw');

警告

列マッピングを有効にすると元に戻すことはできず、テーブルのリーダーおよびライタープロトコルのバージョンが上がります。古いDatabricks Runtimeバージョンや外部リーダーでは、テーブルを読み取れなくなる可能性があります。Databricksにおけるスキーマ進化を参照してください。

型の拡張を有効にする

ALTER COLUMN ... TYPE には型の拡張が必要です。これを有効にしないと、列の拡張は行われず、ステートメントは失敗します。pipelines.enableTypeWidening 構成を使用して、パイプライン内のすべてのテーブルでこれを有効にします。

JSON
{
  "configuration": {
    "pipelines.enableTypeWidening": "true"
  }
}

または、delta.enableTypeWidening テーブルプロパティを使用して単一のテーブルに対して有効にします：

SQL
CREATE OR REFRESH STREAMING TABLE orders
  TBLPROPERTIES ('delta.enableTypeWidening' = 'true')
  AS SELECT * FROM STREAM read_files('/Volumes/main/sales/raw');

型の拡張が有効になっているテーブルを読み取るには、Databricks Runtime 15.4 LTS以降が必要です。Lakeflow pipelinesにおける型の拡張を参照してください。

以下を実行した後にパイプラインのソースコードを更新します： `ALTER`

ALTER TABLE テーブルを変更します。パイプラインのソースコードは変更されません。ストリーミングテーブルで明示的なスキーマを宣言している場合は、パイプラインのソースコードでも同じ変更を行う必要があります。そうしないと、次回のパイプライン更新でテーブルが宣言されたスキーマに戻るように調整されます。これは、「制限事項：パイプラインの更新と ALTER を使用して行われた変更」で説明されている一般的な動作です。

CREATE OR REFRESH STREAMING TABLE st AS SELECT * FROM ... のような暗黙的なスキーマを持つストリーミングテーブルの場合、ソースコードの変更は不要です。

パイプラインがスケジュールに基づいて実行される場合、ALTER TABLE とソースコードの変更の間にトリガーされた更新が実行され、テーブルが宣言されたスキーマに戻される可能性があります。これを回避するには、一致する変更を行う間、パイプラインを停止するします。

パイプラインのスケジュールを停止する。
ALTER TABLE ステートメントを実行します。
新しいスキーマに合わせてパイプラインのソースコードを更新してください。
パイプラインのスケジュールの一時停止を解除します。

互換性のないソース型の変更を処理する

ソースが列の型を互換性のない方法で変更した場合（例：user_id を STRING から INT に変更）、Delta は既存の列を変換できないため、パイプラインの更新は失敗します。完全更新を実行する代わりに、列をインプレースで移行します。

SQL
-- 1. Add a column with the new type.
ALTER TABLE main.bronze.users ADD COLUMN user_id_new INT;

-- 2. Backfill it from the old column.
UPDATE main.bronze.users SET user_id_new = CAST(user_id AS INT);

-- 3. Drop the old column.
ALTER TABLE main.bronze.users DROP COLUMN user_id;

-- 4. Rename the new column into place.
ALTER TABLE main.bronze.users RENAME COLUMN user_id_new TO user_id;

次に、パイプラインのソースコードを更新して user_id を INT として宣言し、更新を実行します。更新は、チェックポイントのResetや完全更新なしで成功します。

ステップ 2 はストリーミングテーブルに対する DML ステートメントであり、独自の要件があります。「ターゲットストリーミングテーブルのデータの追加、変更、または削除」を参照してください。ダウンストリームのクエリーがこのテーブルからストリーミングする場合、バックフィルがそのストリームで失敗しないように、読み取り時に skipChangeCommits を設定する必要がある場合があります。

非加法的なソーススキーマの変更を処理する

ストリーミングテーブルによって読み取られるソースで列が削除または名前変更された場合、ストリームは停止し、意図を推測するのではなく変更を報告します。続行するには変更を承諾してください:

JSON
{
  "configuration": {
    "spark.databricks.delta.streaming.allowSourceColumnDrop": "always",
    "spark.databricks.delta.streaming.allowSourceColumnRename": "always"
  }
}

各構成を always または特定の Delta テーブルバージョンに設定します：

always パイプラインに対するその種の現在および将来のすべての変更を承諾します。
バージョン番号は、ソーステーブルのそのバージョンまで（そのバージョンを含む）のすべてのスキーマ変更を認識します。DESCRIBE HISTORY を使用してソーステーブルの履歴からバージョンを確認するか、ストリームが停止したときに報告されるエラーから確認してください。

注記

ソースの変更を承認しても、その変更はストリーミングテーブルには伝搬されません。ALTER TABLE を使用して、ターゲット上で一致する変更を行います。

制限事項

ALTER TABLE でストリーミングテーブルのスキーマを更新する場合、以下の制限が適用されます。

フル更新はパイプラインのソースコードからストリーミングテーブルを再生成するため、ALTER TABLE で行われた列の変更は保持されません。フル更新後も変更を保持する必要がある場合は、パイプラインのソースコードで同等の変更を行ってください。
Auto Loader は、ストリーミングテーブルとは独立してソーススキーマを追跡します。Auto Loader に裏打ちされたテーブルで DROP COLUMN または RENAME COLUMN を有効にするには、Auto Loader のソーススキーマが更新されないを参照してください。
ストリーミングビューはサポートされていません。ストリーミングビューがストリーミングテーブルへのパス上にある場合、スキーマ進化は機能しません。これには、ストリーミングビューから読み取るフローと、ストリーミングビューから定義されたフローの両方が含まれます。ALTER TABLE 列操作は、フローがソースから直接読み取るストリーミングテーブルでのみ使用してください。
DROP COLUMN および RENAME COLUMN は、列識別子をキーとして変更データ状態を追跡する AUTO CDC フローを持つストリーミングテーブルではブロックされます。コマンドはエラーで失敗します。ADD COLUMN および ALTER COLUMN ... TYPE はサポートされています。
最上位の列のみがサポートされています。構造体、配列、またはマップ内にネストされたフィールドへの変更はサポートされていません。

Auto Loader ソーススキーマは更新されません

フローが Auto Loader で読み取る場合、Auto Loader はソースファイルのスキーマをストリーミングテーブルのスキーマとは別に追跡するため、ALTER TABLE では変更されません。列を生成し続けるソースの場合：

DROP COLUMN：Auto Loader はソースファイルから列の推論を継続し、次の更新でテーブルに書き戻されます。
RENAME COLUMN: Auto Loader は古い列名を生成し続けます。暗黙的スキーマテーブルの場合、古い列が新しい列と並んで追加されます。

Auto Loader を使用したストリーミングテーブルで削除または名前の変更を反映させるには、Auto Loader が読み取る内容も制限してください。列を除外する明示的なリーダーのスキーマを宣言し、rescuedDataColumn オプションを設定して、除外されたフィールドが削除されずにレスキューされたデータ列に入るようにします。スキーマを指定した場合、Auto Loader はレスキューされたデータ列を自動的に追加しないため、そのオプションがないとフィールドは破棄されます。レスキューされたデータ列とはを参照してください。

サポートされている操作​

外部メタデータを有効にする​

列マッピングを有効にする​

型の拡張を有効にする​

以下を実行した後にパイプラインのソースコードを更新します： ALTER​

互換性のないソース型の変更を処理する​

非加法的なソーススキーマの変更を処理する​

制限事項​

Auto Loader ソーススキーマは更新されません​

その他のリソース​