mcpField
D
databricks-migration

databricks-migration

github.com/microsoftデータ・データベース1.3k192 回インストール3 週間前に更新
リポジトリ

databricks-migration について

Databricks のワークロードを Microsoft Fabric に移行するためのスキルです。各コンポーネントの移行先を示し、コード変更、互換性の差、移行時の確認事項をまとめています。

主な機能

  1. 01Databricks コンポーネントと Fabric の移行先を対応付け
  2. 02dbutils 呼び出しを notebookutils の用法に置換
  3. 03クラスター設定を Fabric Spark 構成に変換
  4. 04ジョブ、カタログ、SQL ワークロードの移行を案内
  5. 05阻害要因と互換性の差を提示

活用シーン

  1. 01Databricks ワークスペースの移行を計画
  2. 02Fabric 向けにノートブックコードを調整
  3. 03クラスターとライブラリの差を評価
  4. 04変換前に移行リスクを確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/microsoft/skills-for-fabric --skill databricks-migration

インストール後、Claude Code で/databricks-migrationを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

apm.yml
resources/
catalog-migration.md
code-patterns.md
dbutils-to-notebookutils.md
migration-gotchas.md
migration-orchestrator.md
validation-testing.md

詳細

テレメトリ — 必須。 すべての api.fabric.microsoft.com 呼び出しには x-ms-fabric-skill: databricks-migration（az rest の場合は --headers "x-ms-fabric-skill=databricks-migration"）を含める必要があります。 fabric_lro や再試行を含む、すべての LRO ポーリングにも付与してください。スニペットでは省略されていますが、必ず追加してください。

重要な注意事項

  1. ワークスペース名からワークスペースの詳細（ID を含む）を取得するには、すべてのワークスペースを一覧表示してから、JMESPath でフィルタリングします
  2. ワークスペース ID、項目の種類、項目名から項目の詳細（ID を含む）を取得するには、そのワークスペース内の該当する種類の項目をすべて一覧表示してから、JMESPath でフィルタリングします
  3. Fabric に dbutils.widgets の直接的な同等機能はありません。ノートブックパラメーター（セルタグ parameters）を使用してください。notebookutils.runtime.context は実行メタデータであり、パラメーターの保存先ではありません。コンテキストフィールドを示す場合は、currentWorkspaceId、currentWorkspaceName、currentNotebookId、currentNotebookName、isForPipeline、isForInteractive などのドキュメントに記載された名前を使用してください。activityId は Livy ジョブ ID です
  4. dbutils.library（ランタイムでのライブラリのインストール）に同等機能はありません。再現性のあるライブラリ管理には Fabric Environments を使用してください
  5. Unity Catalog の各カタログは、デフォルトでスキーマ対応の Lakehouse にマッピングしてください。これにより、移行元の schema.table 階層が維持され、Lakehouse がカタログを表します。競合が生じるのは、複数のカタログを意図的に 1 つの Lakehouse に統合する場合のみです
  6. ワークスペース全体の移行について要件が不十分な場合は、Fabric のトポロジーを推奨する前に、インベントリ、ワークロードのトポロジー、セキュリティ、データの保存場所、ランタイムの制約について焦点を絞った質問をしてください
  7. 完了した Fabric 移行では、デュアルランタイム分岐や try/except ガード内に、実行可能な dbutils.* 呼び出しを残してはいけません。これらの呼び出しと Databricks のパスを完全に置き換えてください

Databricks から Microsoft Fabric への移行

前提知識

移行タスクを実行する前に、次の関連ドキュメントをお読みください。

  • COMMON-CORE.md — Fabric REST API のパターン、認証、トークンの対象、項目の検出
  • COMMON-CLI.md — az rest、az login、トークンの取得、CLI 経由での Fabric REST
  • SPARK-AUTHORING-CORE.md — ノートブックのデプロイ、Lakehouse の作成、Spark ジョブの実行

ノートブックと Lakehouse の作成については、spark-cli を参照してください。 Fabric Warehouse の DDL/DML 作成については、sqldw-cli を参照してください。

目次

トピック参照先
移行オーケストレーターmigration-orchestrator.md
移行ワークロードマップ§ 移行ワークロードマップ
dbutils → notebookutils の完全なマッピングdbutils-to-notebookutils.md
Unity Catalog → Fabric Lakehouse スキーマcatalog-migration.md
変更前／変更後のコードパターンcode-patterns.md
クラスター構成 → Fabric Spark プール§ クラスター構成 → Fabric Spark プール
Databricks Jobs → Spark Job Definitions§ Databricks Jobs → Spark Job Definitions
Delta Sharing → Fabric External Data Sharing と OneLake Shortcuts§ Delta Sharing → Fabric External Data Sharing and OneLake Shortcuts
MLflow → Fabric ML Experiments§ MLflow → Fabric ML Experiments
移行後の検証とテストvalidation-testing.md
移行時の注意点とトラブルシューティングmigration-gotchas.md
複数ノートブック移行プロトコル§ 複数ノートブック移行プロトコル
失敗の報告§ 失敗の報告
必須／推奨／回避§ 必須／推奨／回避
認証とトークンの取得COMMON-CORE.md § 認証
Lakehouse の管理SPARK-AUTHORING-CORE.md § Lakehouse の管理
ノートブックの管理SPARK-AUTHORING-CORE.md § ノートブックの管理
コンテキスト読み込みガイド

重要 — 必要なものだけを読み込んでください。 すべてのリソースファイルを最初に読み込まないでください。実行するフェーズに応じて、対象のファイルを読み込んでください。

タイミング読み込むファイル
ユーザーがワークスペースの移行を依頼した場合（完全なオーケストレーション）migration-orchestrator.md
コード変換を適用する場合（dbutils、名前空間、パス）dbutils-to-notebookutils.md + code-patterns.md
Unity Catalog の名前空間の競合を解決する場合catalog-migration.md
移行後の検証validation-testing.md
失敗や既知の問題のトラブルシューティングmigration-gotchas.md

移行ワークロードマップ

Databricks コンポーネントFabric の移行先重要度備考
汎用クラスター（ノートブック、REPL）Fabric Notebook（Starter Pool または Custom Pool）情報クラスターは永続化されません。セッションの開始時に Fabric がコンピューティングをプロビジョニングします
ジョブクラスター（自動化されたジョブ）Spark Job Definition（SJD）情報SJD はジョブクラスター上の Databricks Jobs に一対一で対応します
Unity CatalogFabric Lakehouse（スキーマ対応、カタログごとに 1 つ）情報スキーマ対応の Lakehouse では schema.table が維持されます。カタログごとに Lakehouse を 1 つ使用する既定の構成では競合は発生しません。詳しくは catalog-migration.md を参照してください
Databricks Repos（Git 連携ノートブック）Fabric Git Integration情報ワークスペースを Azure DevOps または GitHub に接続すると、ノートブックが同期されます
Delta Live Tables（DLT）Fabric Notebooks + Data PipelinesブロッカーDLT に相当する機能はありません。DLT データセットを、パラメーター化されたノートブックのセルとパイプラインオーケストレーションを使用して書き換えてください
Databricks SQL WarehousesFabric Warehouse または Lakehouse SQL Endpoint情報SQL ウェアハウスのセッションは、書き込みには Warehouse、読み取り専用には SQL Endpoint に置き換えます
MLflow TrackingFabric ML Experiments情報Fabric では MLflow SDK がサポートされています。詳しくは § MLflow を参照してください
Delta SharingOneLake Shortcuts + Fabric external data sharing警告§ Delta Sharing → Fabric External Data Sharing and OneLake Shortcuts を参照してください
Databricks Feature StoreLakehouse／Delta テーブルでの特徴量エンジニアリング + MLflow警告Fabric にはそのまま置き換えられるマネージド Feature Store がありません。Lakehouse 内の Delta テーブルとして特徴量テーブルを再作成し、ノートブック／MLflow で特徴量を管理してください。方針を決定する前に、Fabric の Feature Store の最新ロードマップを確認してください
dbutils（すべてのサブモジュール）notebookutils（大半のサブモジュール）情報完全な対応表については dbutils-to-notebookutils.md を参照してください
Scala ノートブックFabric Notebook（Spark／Scala）警告Scala はサポートされています。セルマジックを %scala から %%spark に置き換え、Databricks 固有の API／ライブラリを書き換えてください
R ノートブックFabric Notebook（SparkR）警告SparkR はサポートされています。セルマジックを %r から %%sparkr に置き換え、パッケージが利用可能か確認し、Databricks 固有の API を書き換えてください
重要度の定義
レベル意味対応
ブロッカー再設計またはユーザーの判断なしでは Fabric で実行できません作業を停止し、ユーザーに提示して解決を求めます
警告移行可能ですが、検証またはアーキテクチャ上の判断が必要ですレビュー要のフラグを付けて移行します
情報直接置き換えられるレベルの変更です自動で移行します

dbutils → notebookutils クイックリファレンス

API の完全な対照表は、dbutils-to-notebookutils.md にあります。主な対応関係は次のとおりです。

dbutils の呼び出しnotebookutils での同等機能互換性に関する注意
dbutils.fs.ls(path)notebookutils.fs.ls(path)そのまま置き換え可能
dbutils.fs.cp(src, dest)notebookutils.fs.cp(src, dest)そのまま置き換え可能
dbutils.fs.mv(src, dest)notebookutils.fs.mv(src, dest, create_path, overwrite=False)⚠️ シグネチャが異なります。dbutils-to-notebookutils.md を参照してください
dbutils.fs.rm(path, recurse)notebookutils.fs.rm(path, recurse)そのまま置き換え可能
dbutils.fs.mkdirs(path)notebookutils.fs.mkdirs(path)そのまま置き換え可能
dbutils.fs.put(path, contents)notebookutils.fs.put(path, contents)そのまま置き換え可能
dbutils.fs.head(path, maxBytes)notebookutils.fs.head(path, max_bytes)⚠️ デフォルト値が異なります。Python／Scala は 100 KB、R は 64 KB です。dbutils-to-notebookutils.md を参照してください
dbutils.fs.mount(...)notebookutils.fs.mount(source, mountPoint, extraConfigs=None)✅ サポートされています。Microsoft Entra（デフォルト）、accountKey、または sasToken による認証を利用できます。ワークスペース間での共有や永続的な共有には、OneLake Shortcuts を推奨します
dbutils.secrets.get(scope, key)notebookutils.credentials.getSecret(keyVaultUrl, secretName)scope → Key Vault の URL、key → シークレット名
dbutils.notebook.run(path, timeout, args)notebookutils.notebook.run(name, timeout, args)path → ノートブックの name（ワークスペースからの相対パス）
dbutils.notebook.exit(value)notebookutils.notebook.exit(value)そのまま置き換え可能
dbutils.widgets.get(name)§ Widgets Migration を参照してください直接置き換えられる機能はありません
dbutils.library.install(...)実行時には利用できません。Fabric Environments を使用してくださいdbutils.library.restartPython() → notebookutils.session.restartPython()
dbutils.data.summarize(df)display(df.summary())display() または pandas の describe() を使用してください
ウィジェットの移行

dbutils.widgets に相当する機能は Fabric にありません。代わりに、次のパターンを使用してください。

用途Fabric でのパターン
親ノートブックからパラメーターを渡す子ノートブックのセルをパラメーターセルとして指定します（ノートブック UI：セルの「...」メニュー →「Mark cell as parameters」）。親ノートブックから notebookutils.notebook.run("child", arguments={"param": "value"}) を呼び出すと、実行時にエンジンがパラメーターセルの下に新しいセルを挿入し、デフォルト値を上書きします
パイプラインによるパラメーター指定同じパラメーターセルの仕組みを使用します。Fabric パイプラインのノートブックアクティビティでは、Base parameters の設定から上書き値を指定します
ノートブック間で一元管理する設定notebookutils.variableLibrary.getLibrary("<name>") を使用して、Variable Library アイテムから値を読み取ります（デプロイメントパイプラインでは、ステージごとに適切な値のセットが有効になります）
ノートブックでの対話的な選択入力セルを使った display()、IPython ウィジェット（Python のみ）、または Fabric Data Activator を使用します

注：notebookutils.runtime.context ではパラメーター値を取得できません。これは実行メタデータ（ワークスペース／ノートブック／アクティビティ／ユーザーの ID、パイプラインか対話型かを示すフラグなど）を取得するためのものです。dbutils-to-notebookutils.md § Runtime Context を参照してください。

クラスター構成 → Fabric Spark プール

Databricks クラスターの概念Fabric Spark での同等機能備考
汎用クラスター（対話型）Starter Pool自動でプロビジョニングされ、構成は不要です。ノートブックに最適です
ジョブクラスター（ジョブごとに使い捨て）Custom Pool（または Starter Pool）を SJD にアタッチFabric の容量設定でノードサイズとオートスケールを構成します
ノードタイプ（例：Standard_DS3_v2）Fabric ノードサイズ（Small／Medium／Large／X-Large／XX-Large）vCore／メモリ比に基づいて対応付けます
オートスケールの最小／最大ワーカー数Custom Pool の最小／最大ノード数の設定ワークスペースの Spark 設定で利用できます
クラスター設定の spark.confFabric Environment の Spark プロパティEnvironment アイテムに移動し、ワークスペースまたはノートブックにアタッチします
init_scripts（クラスター初期化）Fabric Environment のインストールスクリプト完全な同等機能ではありません。ライブラリのインストールのみサポートされます
Databricks Runtime のバージョンFabric Runtime（1.1 = Spark 3.3、1.2 = Spark 3.4、1.3 = Spark 3.5）対応する Spark バージョンを選択し、非推奨 API をテストします
Photon アクセラレーターFabric Native Execution Engine（NEE）ワークスペースの Spark 設定で有効にします。Photon と同様のベクトル化実行を行います

Databricks Jobs → Spark Job Definitions

Databricks Jobs の概念Fabric SJD での同等機能備考
ノートブックタスクが 1 つのジョブノートブックを参照する SJD既定の Lakehouse をアタッチし、SJD の引数でパラメーターを渡します
複数タスクのジョブ（タスクの DAG）複数の SJD／ノートブックをオーケストレーションする Fabric Data Pipelineパイプラインのアクティビティはジョブタスクに対応します。依存関係はアクティビティの依存関係に対応します
ジョブのスケジュール（cron）パイプラインのスケジュールトリガーcron 式をパイプラインの繰り返しトリガーに変換します
ジョブのパラメーターSJD の既定の引数またはノートブックのセルパラメーターノートブックのパラメーターセルに実行時に値が挿入されます
タスクごとのジョブクラスターSJD にアタッチするプール各 SJD で個別に Spark プールを指定できます
Databricks WorkflowsFabric Data Pipelines条件、ループ、失敗時の分岐を含む完全な DAG オーケストレーションです

SJD の作成とノートブックのデプロイは spark-cli に委任してください。

Delta Sharing → Fabric 外部データ共有と OneLake ショートカット

Databricks Delta Sharing のパターンFabric での同等機能
プロバイダーが Delta 共有を公開するテナントをまたぐ Fabric データ共有には Fabric の外部データ共有を使用するか、Delta データが格納されている ADLS Gen2 への OneLake ショートカットを作成します
受信者が共有データを読み取る外部データ共有を Lakehouse に受け入れる（Fabric により読み取り専用の OneLake ショートカットが作成されます）か、アクセス可能な ADLS Gen2 データへの直接の OneLake ショートカットを作成します
組織内のワークスペース間でのテーブル共有別のワークスペースの Lakehouse テーブルを参照する OneLake ショートカット。データのコピーは不要です
テナント間共有Fabric の外部データ共有。受信者のテナント内のショートカットを介した、ライブで読み取り専用のインプレースアクセスです

移行ワークロードマップを作成するときは、アクセス可能な ADLS または同じテナント内の OneLake データに対する直接の OneLake ショートカットと、ネイティブなテナント間の受信者共有に対する Fabric の外部データ共有の両方の方法を含めてください。

MLflow → Fabric ML Experiments

Fabric ML Experiments は MLflow SDK を基盤としているため、ほとんどのコードはそのまま移植できます。

Databricks MLflow パターンFabric での同等機能移行時の対応
mlflow.set_tracking_uri("databricks")削除 — Fabric のトラッキングは自動ですFabric ノートブックではこの行を削除します
mlflow.set_experiment("/path/exp")mlflow.set_experiment("experiment_name")名前のみを使用します（パスではありません）。Fabric が Experiment アイテムを作成します
mlflow.log_metric(...)mlflow.log_metric(...) — 同一変更不要
mlflow.log_artifact(...)mlflow.log_artifact(...) — 同一変更不要
mlflow.autolog()mlflow.autolog() — 同一変更不要
mlflow.register_model(...)mlflow.register_model(...) — 同一Model Registry は Fabric ML で利用できます
Databricks Model ServingAzure ML Online Endpoints または Fabric Data ActivatorFabric に直接のモデルサービング機能はまだありません — Azure ML を使用します

必須／推奨／回避

必須
  • ワークスペースのトポロジーを提案する前に棚卸しを行います — ワークロードの棚卸し、依存関係、セキュリティ要件、データの場所、ランタイムの制約が記載されていないワークスペース全体に関する依頼では、Fabric の設計を選ぶ前に、要点を絞った確認質問を行い、条件に応じた選択肢を提示します
  • dbutils-to-notebookutils.md の対応表を使って、すべての dbutils.* 呼び出しを置き換えます — Fabric ノートブックでは dbutils を利用できません
  • dbutils.fs.mount() を notebookutils.fs.mount() に移行します（✅ サポート対象 — Microsoft Entra の既定認証、または Key Vault の accountKey／sasToken）。ワークスペース間または永続的な共有には、代わりに OneLake Shortcuts を優先します。mount() は必ず try/finally で unmount() と組み合わせます — Fabric のマウントはセッション終了時に自動で解除されません
  • dbutils.secrets.get(scope, key) を notebookutils.credentials.getSecret(keyVaultUrl, secretName) に置き換えます — シークレットスコープは Azure Key Vault URL に対応します
  • ウィジェットベースのパラメーター受け渡しを再設計します。ノートブックの パラメーターセル（セルの「...」メニュー → 「Mark cell as parameters」）を使用します。ノートブック間で設定を一元化するには notebookutils.variableLibrary を使用します。notebookutils.runtime.context からパラメーター値を取得することはできません
  • dbutils.library.install*() を Fabric の Environments に置き換えます — ランタイムでのライブラリのインストールは本番環境ではサポートされません。dbutils.library.restartPython() は notebookutils.session.restartPython() に対応します（Python／PySpark のみ）
  • Unity Catalog の名前空間を慎重にマッピングします — schema.table の形式を維持できるよう、既定ではカタログごとにスキーマ対応の Lakehouse を 1 つ使用します。複数のカタログを 1 つの Lakehouse に統合する場合に限り、ユーザーが承認した命名ポリシーを必須とします。catalog-migration.md を参照してください
  • Databricks のクラスター初期化スクリプトを Fabric Environments にマッピングします — クラスター レベルでのライブラリのインストールは Environment アイテムに移行する必要があります
推奨
  • Photon に相当する機能として Fabric Native Execution Engine（NEE） を使用します — Delta Lake でベクトル化実行を行うには、ワークスペースの Spark 設定で有効にします
  • ADLS Gen2 にすでに存在する Delta テーブルでは、データをコピーするよりも OneLake Shortcuts を優先します — 再取り込みせずに直接参照します
  • Databricks Repos の代替として Fabric Git Integration を使用します — ワークスペースを ADO または GitHub に接続し、ノートブックのバージョン管理を行います
  • MLflow との直接的な継続性を保つには Fabric ML Experiments を使用します — トラッキングコードへの変更は最小限です（set_tracking_uri を削除します）
  • 移行した Databricks カタログを再構成する際は、メダリオンアーキテクチャ を採用します — bronze、silver、gold の Unity Catalog スキーマを、それぞれ別の Fabric Lakehouse に対応させます
  • 対話型ノートブックのワークフローを移行する際は Starter Pool を使用します — Databricks のジョブクラスターでよく問題となっていたクラスターの起動時間をなくせます
回避事項
  • ソースのインベントリと移行の制約が不足している場合は、画一的なワークスペース構成を推奨しないでください
  • Fabric ノートブックで dbutils をインポートしたり、dbutils = ... の代入を試みたりしないでください。インポートを試みると ModuleNotFoundError が発生し、解決されない dbutils への参照は NameError を発生させます。必ず notebookutils を使用してください
  • ランタイム検出ガード（try/except、if IS_DATABRICKS）の背後に dbutils.* 呼び出しを残さないでください。呼び出しと Databricks のパスはそのまま notebookutils と Fabric のパスに置き換えてください
  • Unity Catalog のガバナンスポリシーが自動的に引き継がれると想定しないでください。Fabric では、ワークスペースロールと Lakehouse のアクセス許可を使って、RBAC、行レベルセキュリティ、列マスキングを再設定する必要があります
  • 本番環境の Fabric ノートブックで、実行時に %pip install を使用しないでください。安定したバージョン管理されたライブラリ管理には Fabric Environments を使用してください
  • Delta Live Tables（DLT）のパイプラインをそのまま移植しようとしないでください。DLT に Fabric の同等機能はありません。Fabric Pipelines がオーケストレーションするパラメーター化されたノートブックとして書き直してください
  • Databricks 固有の Spark 設定（例：spark.databricks.*）に依存しないでください。これらは独自仕様であり、Fabric では無視されるか、エラーが発生します
  • DBFS パス（dbfs:/...）を使用しないでください。Fabric に DBFS はありません。すべてのパスに OneLake の abfss:// または Lakehouse 相対パスを使用してください

複数ノートブックの移行プロトコル

ノートブックが 3 個を超えるワークスペース、または個々のノートブックのサイズが 5KB を超える場合は、コンテキストのオーバーフローを避けるため、一度に 1 つのノートブックを処理してください（一覧化 → エクスポート → 変換 → 要約 → デプロイ → リリース）。各ノートブックのステータスをライフサイクル（inventory → analyzed → converted → deployed → validated、または failed）に沿って追跡してください。

完全なプロトコル、ステータスの定義、ノートブックごとの要約スキーマについては、migration-orchestrator.md § Phase 2を参照してください。

失敗の報告

移行を完了できない場合（アクセス許可の失敗、DLT や OS レベルの初期化スクリプトなど、解決できない Blocker、ユーザーがポリシーを選択していない名前空間の競合、または API の失敗が繰り返される場合）は、構造化された失敗レポートを出力してください。黙って中断しないでください。レポートには phase_reached、blockers[]（item / pattern / reason / recommendation）、partial_success の件数、next_steps を記録します。

完全なレポートスキーマと停止条件については、migration-orchestrator.md § Failure Reportingを参照してください。

例

完全なマッピングについては、dbutils-to-notebookutils.mdとcode-patterns.mdを参照してください。主なクイックリファレンス：

dbutils.fs → notebookutils.fs

# Databricks
dbutils.fs.ls("/mnt/bronze/orders/")
dbutils.fs.cp("/mnt/raw/file.csv", "/mnt/archive/file.csv")

# Fabric (replace DBFS/mount paths with OneLake relative paths)
notebookutils.fs.ls("Files/bronze/orders/")
notebookutils.fs.cp("Files/raw/file.csv", "Files/archive/file.csv")

dbutils.secrets → notebookutils.credentials

# Databricks
pwd = dbutils.secrets.get(scope="prod", key="db-password")

# Fabric (scope → Key Vault URL, key → secret name)
pwd = notebookutils.credentials.getSecret("https://myvault.vault.azure.net/", "db-password")

Unity Catalog の名前空間 → Lakehouse スキーマ

# Databricks
df = spark.read.table("prod.silver.customers")

# Fabric (ProdLakehouse represents the source catalog and is attached as context)
df = spark.read.table("silver.customers")

コメント

Markdown 対応