Databricks Workspace Export / Import 実践

Databricksワークスペース内のノートブック・フォルダ・ファイルを別のワークスペースに移行したり、 バックアップを取得したり、CI/CDパイプラインにコードを渡す際に使うのがWorkspace Export / Importです。

この記事では、エクスポート形式（DBC/SOURCE/HTML）の違い、Databricks CLIとREST APIを使った 操作コマンド、Terraformとの連携方式、そしてエクスポート時の権限・シークレットの扱いについて解説します。

エクスポート形式の比較

Databricksのワークスペースからノートブックをエクスポートする際、3つの形式を選択できます。

DBC形式はDatabricks固有のアーカイブ（実体はZIPファイル）で、フォルダ全体をまとめてエクスポートできます。 SOURCE形式は純粋なソースコードファイルで、Gitリポジトリへの格納やPRレビューに最適です。

Databricks CLIによるExport / Import

Databricks CLIを使うと、コマンドラインからバッチ的にExport / Importを実行できます。

単一ノートブックのエクスポート

# SOURCE形式でエクスポート
databricks workspace export \
  /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.py \
  --format SOURCE

# DBC形式でエクスポート
databricks workspace export \
  /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.dbc \
  --format DBC

# HTML形式でエクスポート（レポート共有用）
databricks workspace export \
  /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.html \
  --format HTML

フォルダ全体の一括エクスポート

# フォルダ全体をSOURCE形式で一括エクスポート
databricks workspace export_dir \
  /Workspace/Shared/etl-project \
  ./backup/etl-project \
  --overwrite

インポート

# SOURCE形式のインポート
databricks workspace import \
  --path /Workspace/Users/[email protected]/etl_pipeline \
  --file ./etl_pipeline.py \
  --format SOURCE \
  --language PYTHON

# DBC形式の一括インポート
databricks workspace import_dir \
  ./backup/etl-project \
  /Workspace/Shared/etl-project-restored \
  --overwrite

REST APIによるExport / Import

CI/CDパイプラインからプログラマティックにExport / Importを行う場合はREST APIを使います。

# エクスポート（SOURCE形式）
curl -X GET \
  "https://<workspace-url>/api/2.0/workspace/export" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "path": "/Workspace/Users/[email protected]/etl_pipeline",
    "format": "SOURCE"
  }'

# レスポンス（Base64エンコードされたコンテンツ）
{
  "content": "IyBEYXRhYnJpY2tzIG5vdGVib29rIHNvdXJjZQ...",
  "file_type": "py"
}

# インポート（SOURCE形式）
curl -X POST \
  "https://<workspace-url>/api/2.0/workspace/import" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/Workspace/Users/[email protected]/etl_pipeline_v2",
    "format": "SOURCE",
    "language": "PYTHON",
    "content": "IyBEYXRhYnJpY2tzIG5vdGVib29rIHNvdXJjZQ...",
    "overwrite": true
  }'

REST APIでのコンテンツはBase64エンコードされる点に注意してください。 大量のノートブックを移行する場合は、CLIのexport_dir/import_dirの方が効率的です。

エクスポートに含まれるもの / 含まれないもの

ワークスペース権限（ACL）、Secret Scope、クラスタ設定、ジョブ定義はいずれの形式でもエクスポートされません。 これらのリソースを移行するには、Databricks Terraform ProviderまたはDatabricks CLIの 各リソース用APIを個別に使う必要があります。

Terraformとの連携

ワークスペースのノートブック配置をIaCで管理する場合、Terraform Providerのdatabricks_notebookリソースを使います。

resource "databricks_notebook" "etl_pipeline" {
  path     = "/Workspace/Shared/etl-project/etl_pipeline"
  language = "PYTHON"
  source   = "${path.module}/notebooks/etl_pipeline.py"
}

resource "databricks_notebook" "data_quality" {
  path     = "/Workspace/Shared/etl-project/data_quality"
  language = "SQL"
  source   = "${path.module}/notebooks/data_quality.sql"
}

Terraformで管理するメリットは、ノートブックの配置だけでなく、 クラスタ・ジョブ・権限・Secret Scopeなどのリソースも含めて一元管理できる点です。 ただし、ノートブックの頻繁な更新にはTerraformのapplyサイクルが重く、 開発フェーズではRepos、デプロイフェーズではDABsまたはTerraformという使い分けが現実的です。

ワークスペース移行パターン

ワークスペース間でのノートブック移行には複数のアプローチがあります。

ベストプラクティス

• 定期バックアップにはCLIのexport_dir + DBC形式: cronジョブまたはCI/CDスケジュールで 定期的にワークスペースのノートブックをDBC形式でバックアップする
• 移行前にシークレットのハードコードを排除する: エクスポートされたコードにシークレットが 含まれないよう、事前にSecret Scope方式に移行する
• 権限は別途移行する: ノートブックのExport/Importでは権限が引き継がれないため、 Permissions APIまたはTerraformで権限を再設定する
• 長期的にはRepos + DABsに移行する: Export/Importは一時的な移行やバックアップには有用だが、 継続的なデプロイにはRepos + DABsの方が適している

試験で問われるポイント

• 「ノートブックをワークスペース間で移行するには」→ Export/Import（DBC形式）またはRepos経由のGit Clone
• 「エクスポートに権限は含まれるか」→ 含まれない（Permissions APIで別途設定が必要）
• 「SOURCE形式とDBC形式の違いは」→ SOURCEはソースコードのみ、DBCはメタデータを含むアーカイブ
• 「HTML形式のエクスポートはインポートできるか」→ できない（読み取り専用のレポート形式）

問題で確認

よくある質問