Azure DatabricksでPipeline削除後にテーブルが残る新仕様｜cascade=trueで旧動作を維持

Azure DatabricksのUnity Catalog Pipelineを削除し、「関連テーブルも一緒に消えた」とみなしている自動化は、今のうちに修正が必要です。今後の既定動作では、Pipelineを削除しても、関連するmaterialized view、streaming table、viewは削除されず、非アクティブな状態で保持されるようになります。

従来どおりPipelineと関連オブジェクトをまとめて削除したい場合は、Pipelines REST APIのDELETEリクエストにcascade=trueを明示してください。cascadeパラメーターはすでに利用できるため、仕様変更の適用を待たずに対応できます。(Microsoft Learn)

Pipeline削除の自動化ではcascade=trueを今すぐ明示する

従来の削除動作を維持するために必要な変更は、DELETE APIのURLにcascade=trueを付けることです。

DELETE /api/2.0/pipelines/{pipeline_id}?cascade=true

現在はcascadeを省略しても、Unity Catalog Pipelineと関連オブジェクトがまとめて削除されます。しかし、今後は省略時の既定動作が変わり、関連オブジェクトが保持される予定です。

つまり、次のような呼び出しは将来の動作が変わります。

DELETE /api/2.0/pipelines/{pipeline_id}

削除結果を将来にわたって固定するには、既定値に依存せず、次のどちらかを明示します。

# Pipelineと関連オブジェクトを削除
DELETE /api/2.0/pipelines/{pipeline_id}?cascade=true

# Pipelineだけを削除し、関連オブジェクトを保持
DELETE /api/2.0/pipelines/{pipeline_id}?cascade=false

「Pipelineを削除したい」という同じAPI呼び出しでも、cascadeの値によって最終状態は大きく異なります。

Pipeline削除の現在と新仕様の違い

変更の対象は、Unity Catalogに発行するAzure Databricks Pipelineです。

DELETE APIの指定	現在の動作	今後の動作	適した用途
`cascade`を省略	Pipelineと関連オブジェクトを削除	Pipelineを削除し、関連オブジェクトを保持	使用非推奨
`cascade=true`	Pipelineと関連オブジェクトを削除	Pipelineと関連オブジェクトを削除	完全なクリーンアップ
`cascade=false`	Pipelineを削除し、関連オブジェクトを保持	Pipelineを削除し、関連オブジェクトを保持	移行、調査、データ保全

2026年4月9日に追加されたcascadeフィールドでは、現在の既定値はtrueです。その後、Microsoftは「今後の変更」として、Pipeline削除時に関連テーブルを保持する動作へ既定を変更すると予告しています。(Microsoft Learn)

重要なのは、cascade=true自体が廃止されるわけではないことです。既定動作が変わった後も、明示的にtrueを指定すれば従来と同じ一括削除を維持できます。

削除されずに残るオブジェクト

新しい既定動作では、Pipelineを削除しても、主に次のオブジェクトがUnity Catalogに残ります。

materialized view
streaming table
view

保持されたオブジェクトは非アクティブになります。非アクティブなテーブルは引き続きクエリできますが、削除済みPipelineによって更新されることはありません。

そのため、利用者から見ると「SELECTは成功するが、データが更新されない」という状態が発生します。Pipelineがなくなったことに気付かず参照を続けると、古いデータを最新データとして扱ってしまう可能性があります。

非アクティブなテーブルは新しいPipelineへ移動でき、フローに関連付けることで再アクティブ化できます。このため、cascade=falseはPipelineの作り直しや移行時に有効です。(Microsoft Learn)

既存のクリーンアップ自動化に起きる影響

最も影響を受けるのは、DELETE APIの成功だけを確認して処理を終了しているスクリプトです。

テスト環境の再作成でオブジェクトが残る

たとえば、CI/CDで次の処理を実行しているケースです。

既存Pipelineを削除する
同じカタログとスキーマに新しいPipelineを作る
同じ名前のstreaming tableやmaterialized viewを作る

従来は手順1で関連オブジェクトも削除されていました。しかし、新しい既定動作ではテーブルが残るため、同名オブジェクトとの衝突や、既存オブジェクトの意図しない再利用が起きる可能性があります。

開発環境や一時環境を毎回初期化する処理では、cascade=trueを明示するのが基本です。

DELETE成功が「完全削除」を意味しなくなる

APIが正常終了しても、削除されたのがPipelineだけというケースが発生します。

次のような判定は不十分になります。

DELETE APIが成功
↓
クリーンアップ完了

今後は、目的に応じて終了条件を分ける必要があります。

cascade=true
↓
Pipelineが存在しない
かつ
対象オブジェクトが存在しない

cascade=false
↓
Pipelineが存在しない
かつ
対象オブジェクトが保持されている

APIのHTTPステータスだけでなく、Unity Catalog側の最終状態まで検証する設計に変更してください。

古いデータを下流処理が参照し続ける

保持された非アクティブテーブルにはクエリできます。

そのため、下流のNotebook、Databricks SQL、BIツール、別のジョブなどが対象テーブルを参照している場合、エラーにならず処理が継続する可能性があります。

これは一見すると安全ですが、実際には次の状態です。

SELECTは成功する
過去のデータは取得できる
Pipelineによる更新は停止している
利用者が停止に気付きにくい

削除後もテーブルを残す場合は、更新停止を検知する監視や、利用者への告知が必要です。

ストレージとデータ保持の管理がずれる

「Pipelineを削除したので関連データも消えた」と判断していると、実際のUnity Catalogオブジェクトや保存データとの間に差が生じます。

特に次の処理は見直しが必要です。

一時環境の定期削除
検証データの消去
個人情報を含む中間テーブルの削除
プロジェクト終了時のデータ廃棄
カタログやスキーマの棚卸し
ストレージ使用量の監視

Pipelineの削除と、データオブジェクトの削除を同じものとして扱わないことが重要です。

cascade=trueを指定するREST APIの実装例

curlで削除する

DATABRICKS_HOSTには、https://を含むAzure DatabricksワークスペースURLを設定します。

curl --request DELETE \
  --header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  "${DATABRICKS_HOST}/api/2.0/pipelines/${PIPELINE_ID}?cascade=true"

この呼び出しでは、Pipelineと関連するmaterialized view、streaming table、viewをまとめて削除します。

一方、テーブルを残したい場合はfalseを指定します。

curl --request DELETE \
  --header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  "${DATABRICKS_HOST}/api/2.0/pipelines/${PIPELINE_ID}?cascade=false"

PowerShellで削除する

Azure DevOpsやWindowsベースの運用スクリプトでは、次のように実装できます。

$PipelineId = "対象のPipeline ID"

$Headers = @{
    Authorization = "Bearer $env:DATABRICKS_TOKEN"
}

$Uri = "$($env:DATABRICKS_HOST)/api/2.0/pipelines/$PipelineId?cascade=true"

Invoke-RestMethod `
    -Method Delete `
    -Uri $Uri `
    -Headers $Headers

テーブルを保持する運用では、URLの末尾を次のように変更します。

$Uri = "$($env:DATABRICKS_HOST)/api/2.0/pipelines/$PipelineId?cascade=false"

実運用では、trueまたはfalseを呼び出し元から無条件に渡せるようにするよりも、「完全削除用」「保持削除用」の処理を明確に分けた方が安全です。単純なパラメーター入力ミスで、本番データまで削除する事故を防ぎやすくなります。

CI/CDとクリーンアップ処理の修正手順

DELETE APIを呼び出している箇所を洗い出す

まず、次の文字列や処理をリポジトリ全体で検索します。

/api/2.0/pipelines/

pipelines/delete

DELETE

確認対象は、直接REST APIを呼び出しているスクリプトだけではありません。

Azure DevOps Pipeline
GitHub Actions
PowerShell
Bash
Pythonスクリプト
Azure Functions
Logic Apps
社内運用ツール
SDKをラップした共通ライブラリ
Terraformの外部実行処理
テスト終了時の後片付け処理

共通ライブラリがDELETE APIを隠蔽している場合、アプリケーション側ではなく共通ライブラリ側の修正が必要です。

削除ポリシーを決める

すべてのPipelineに一律でcascade=trueを付けるのは危険です。用途ごとに削除方針を決めます。

利用場面	推奨値	理由
一時的な開発環境の破棄	`true`	次回作成時にオブジェクトを残さない
自動テスト後のクリーンアップ	`true`	テストデータを完全に削除する
本番Pipelineの廃止	要判断	データ保持要件を確認する必要がある
Pipelineの再構築	`false`	既存テーブルを新しいPipelineで再利用できる
障害調査のための一時退避	`false`	既存データを調査用に残せる
法令・社内規程に基づく完全削除	`true`	Pipelineだけでなく関連オブジェクトも削除する

本番環境では、「Pipelineを止める」「Pipelineを削除する」「データも削除する」を別々の承認項目として扱うと安全です。

既定値に依存する呼び出しをなくす

次の呼び出しを残さないようにします。

DELETE /api/2.0/pipelines/{pipeline_id}

必ず意図を明示します。

DELETE /api/2.0/pipelines/{pipeline_id}?cascade=true

または、

DELETE /api/2.0/pipelines/{pipeline_id}?cascade=false

仕様変更前に修正しておけば、ロールアウト時期やワークスペースごとの差を意識せず、削除結果を一定にできます。

非本番環境で両方の動作を確認する

検証用Pipelineを作成し、次の2パターンをテストします。

完全削除テスト

DELETE /api/2.0/pipelines/{pipeline_id}?cascade=true

確認項目は次のとおりです。

Pipelineが削除されている
materialized viewが削除されている
streaming tableが削除されている
viewが削除されている
同じ名前で再デプロイできる

保持削除テスト

DELETE /api/2.0/pipelines/{pipeline_id}?cascade=false

確認項目は次のとおりです。

Pipelineが削除されている
関連オブジェクトが残っている
保持されたデータをクエリできる
Pipelineからの更新が停止している
新しいPipelineへ移行できる

本番環境で初めて挙動を確認するのではなく、権限構成や発行モードが同等の非本番環境で試してください。

削除後にUnity Catalogのオブジェクトを確認する方法

削除後の確認には、Catalog Explorerだけでなく、Information Schemaを利用できます。

SELECT
    table_catalog,
    table_schema,
    table_name,
    table_type
FROM system.information_schema.tables
WHERE table_catalog = 'main'
  AND table_schema = 'target_schema'
  AND table_type IN (
      'MATERIALIZED_VIEW',
      'STREAMING_TABLE',
      'VIEW'
  )
ORDER BY table_name;

TABLE_TYPEでは、materialized viewがMATERIALIZED_VIEW、streaming tableがSTREAMING_TABLE、通常のviewがVIEWとして識別されます。(Microsoft Learn)

ただし、スキーマ内に別のPipelineや手動作成オブジェクトが混在している場合、単純に「件数がゼロか」だけを確認してはいけません。

削除前に対象オブジェクトの一覧を保存し、削除後に同じ名前が残っているかを比較する方法が確実です。

SELECT
    table_catalog,
    table_schema,
    table_name,
    table_type
FROM system.information_schema.tables
WHERE table_catalog = 'main'
  AND table_schema = 'target_schema'
ORDER BY table_name;

CI/CDでは、この結果とデプロイ定義側のオブジェクト一覧を照合し、cascade=trueの場合だけ対象オブジェクトが消えていることを確認します。

監査ログでcascadeの指定を確認する

Azure Databricksの診断ログでは、Lakeflow Pipelinesの削除イベントに次のリクエストパラメーターが記録されます。

pipeline_id
cascade

そのため、削除事故やオブジェクト残存が発生した場合に、「どのPipelineを削除したか」だけでなく、「cascadeに何を指定したか」も確認できます。(Microsoft Learn)

自動化を修正した後は、監査ログでcascade=trueまたはcascade=falseが期待どおり記録されているか確認してください。

CI/CDの実行ログだけでは、共通ライブラリやSDK内部でパラメーターが欠落していても気付けない場合があります。Databricks側の監査ログまで確認することで、実際に送信されたリクエストを検証できます。

cascadeを利用するときの対象範囲と制限

対象はUnity Catalog Pipeline

今回の既定動作変更は、Unity Catalog Pipelineを対象としたものです。

Hive metastoreを利用するPipelineでは、cascade=trueによるテーブルの連鎖削除はサポートされません。Hive metastore Pipelineにcascade=trueを指定すると、対応していないことを示すエラーになる可能性があります。(Microsoft Learn)

自動化では、PipelineがUnity Catalogを使用していることを確認してからcascade=trueを指定してください。

cascade=falseを使えないPipelineがある

cascade=falseは、すべてのPipeline形式で利用できるとは限りません。

公式のエラー条件には、次のケースが示されています。

対象のPipelineタイプがテーブル保持に対応していない
legacy publishing modeのPipelineである
Unity Catalog以外のPipelineである

legacy publishing modeでは、cascade=falseを指定してテーブル削除を回避できず、保持したい場合はdefault publishing modeへの移行が必要です。(Microsoft Learn)

特に、古くから運用しているPipelineでは、非本番環境でcascade=falseの動作を確認してから本番へ適用してください。

Pipeline全体の削除とテーブル定義の削除を混同しない

cascadeが制御するのは、Pipeline全体をDELETE APIで削除するときの動作です。

Pipelineのソースコードから、特定のmaterialized viewやstreaming tableの定義だけを削除する操作とは別です。

テーブル定義をPipelineから外した場合、そのテーブルは次回更新時に非アクティブになることがあります。この動作に関係する設定は、次のPipeline構成です。

{
  "pipelines.dropInactiveTables": "true"
}

整理すると、役割は次のように異なります。

設定	対象操作	制御する内容
`cascade=true`	Pipeline全体の削除	関連オブジェクトも削除する
`cascade=false`	Pipeline全体の削除	関連オブジェクトを保持する
`pipelines.dropInactiveTables`	Pipeline定義からテーブルを外した後の更新	非アクティブテーブルの扱いを制御する

似た削除機能ですが、適用されるタイミングが異なります。Pipeline全体の廃止手順を修正するときはcascadeを確認し、ソースコードからテーブル定義を削除するときは非アクティブテーブルの設定を確認します。(Microsoft Learn)

よくある誤りと防止策

既定値が変わってから対応する

変更日を待ってから修正すると、ワークスペースや環境ごとに異なる結果になる期間が発生する可能性があります。

cascadeはすでに使用できるため、現在の段階で明示するのが安全です。

すべての削除をcascade=trueにする

開発環境では便利ですが、本番Pipelineの移行や障害調査では、既存データを残した方がよい場合があります。

削除処理にtrueを固定する前に、環境と目的を確認してください。

cascade=falseなら安全だと考える

データが消えないという意味では安全ですが、非アクティブなテーブルを最新データとして参照してしまうリスクがあります。

保持する場合は、更新停止の監視、利用者への通知、最終的な削除期限まで決めておく必要があります。

DROP SCHEMA CASCADEで代用する

Pipeline削除後にスキーマ全体をDROP SCHEMA ... CASCADEで消せば、残存オブジェクトは削除できます。しかし、同じスキーマに別のPipelineや手動作成テーブルがある場合、それらまで削除する危険があります。

Pipeline単位のクリーンアップには、Pipelines DELETE APIのcascade=trueを利用する方が対象を限定できます。

API成功だけをテストする

DELETE APIの成功は、目的とするデータ状態が実現したことを保証するものではありません。

テストでは、APIの結果に加えて、Unity Catalog上のオブジェクト一覧まで確認してください。

今すぐ確認すべきチェックリスト

Unity Catalog Pipelineを削除するスクリプトを洗い出す
cascadeを省略しているDELETE APIを特定する
完全削除かテーブル保持かをPipelineごとに決める
完全削除ではcascade=trueを明示する
テーブル保持ではcascade=falseを明示する
Hive metastore Pipelineにcascade=trueを適用しない
legacy publishing modeかどうかを確認する
非本番環境で削除後の状態を検証する
Information Schemaで関連オブジェクトを確認する
監査ログにcascadeが記録されていることを確認する
保持した非アクティブテーブルの削除期限を決める
下流処理が古いデータを参照し続けないよう監視する

既定値ではなく削除の意図をコードに残す

今回の変更で重要なのは、Pipeline削除後にテーブルが残ることだけではありません。これまで曖昧だった「Pipelineの削除」と「データの削除」を明確に分離する必要があります。

完全なクリーンアップが目的なら、次の指定を現在から追加します。

DELETE /api/2.0/pipelines/{pipeline_id}?cascade=true

移行や調査のためにデータを残すなら、次を明示します。

DELETE /api/2.0/pipelines/{pipeline_id}?cascade=false

cascadeを省略した実装は、現在は動作していても、今後は同じ削除結果を保証できません。まずDELETE APIを呼び出している箇所を検索し、用途ごとにtrueまたはfalseを明示してください。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

Azure DatabricksでPipeline削除後にテーブルが残る新仕様｜cascade=trueで旧動作を維持

Pipeline削除の自動化ではcascade=trueを今すぐ明示する

Pipeline削除の現在と新仕様の違い

削除されずに残るオブジェクト

既存のクリーンアップ自動化に起きる影響

テスト環境の再作成でオブジェクトが残る

DELETE成功が「完全削除」を意味しなくなる

古いデータを下流処理が参照し続ける

ストレージとデータ保持の管理がずれる

cascade=trueを指定するREST APIの実装例

curlで削除する

PowerShellで削除する

CI/CDとクリーンアップ処理の修正手順

DELETE APIを呼び出している箇所を洗い出す

削除ポリシーを決める

既定値に依存する呼び出しをなくす

非本番環境で両方の動作を確認する

完全削除テスト

保持削除テスト

削除後にUnity Catalogのオブジェクトを確認する方法

監査ログでcascadeの指定を確認する

cascadeを利用するときの対象範囲と制限

対象はUnity Catalog Pipeline

cascade=falseを使えないPipelineがある

Pipeline全体の削除とテーブル定義の削除を混同しない

よくある誤りと防止策

既定値が変わってから対応する

すべての削除をcascade=trueにする

cascade=falseなら安全だと考える

DROP SCHEMA CASCADEで代用する

API成功だけをテストする

今すぐ確認すべきチェックリスト

既定値ではなく削除の意図をコードに残す

この記事を書いた人

コメント

コメントするコメントをキャンセル

Azure DatabricksでPipeline削除後にテーブルが残る新仕様｜cascade=trueで旧動作を維持

Pipeline削除の自動化ではcascade=trueを今すぐ明示する

Pipeline削除の現在と新仕様の違い

削除されずに残るオブジェクト

既存のクリーンアップ自動化に起きる影響

テスト環境の再作成でオブジェクトが残る

DELETE成功が「完全削除」を意味しなくなる

古いデータを下流処理が参照し続ける

ストレージとデータ保持の管理がずれる

cascade=trueを指定するREST APIの実装例

curlで削除する

PowerShellで削除する

CI/CDとクリーンアップ処理の修正手順

DELETE APIを呼び出している箇所を洗い出す

削除ポリシーを決める

既定値に依存する呼び出しをなくす

非本番環境で両方の動作を確認する

完全削除テスト

保持削除テスト

削除後にUnity Catalogのオブジェクトを確認する方法

監査ログでcascadeの指定を確認する

cascadeを利用するときの対象範囲と制限

対象はUnity Catalog Pipeline

cascade=falseを使えないPipelineがある

Pipeline全体の削除とテーブル定義の削除を混同しない

よくある誤りと防止策

既定値が変わってから対応する

すべての削除をcascade=trueにする

cascade=falseなら安全だと考える

DROP SCHEMA CASCADEで代用する

API成功だけをテストする

今すぐ確認すべきチェックリスト

既定値ではなく削除の意図をコードに残す

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

コメントするコメントをキャンセル