Databricks Notebooks: 共同編集・実行モデル・ベストプラクティス

Databricksノートブックは、Python・SQL・Scala・Rの4言語に対応したインタラクティブな開発環境です。 1つのノートブック内でマジックコマンドを使い複数言語を切り替えられ、リアルタイム共同編集にも対応します。

本記事では、マジックコマンドの全種類、共同編集と権限モデル、実行コンテキスト（インタラクティブ/ジョブ）、 ウィジェットによるパラメータ化、ノートブック間連携、Git統合（Repos）を体系的に整理します。

多言語対応とデフォルト言語

ノートブック作成時にデフォルト言語（Python / SQL / Scala / R）を1つ選択します。 各セルはデフォルト言語で実行されますが、セル先頭にマジックコマンド（%python, %sql等）を記述することで セル単位で言語を切り替えられます。

%python
# Pythonセル：DataFrameを作成してTempViewに登録
df = spark.range(100).toDF("id")
df.createOrReplaceTempView("numbers")

%sql
-- SQLセル：Pythonで作ったTempViewをSQLで参照
SELECT id, id * 10 AS multiplied FROM numbers WHERE id < 10;

%scala
// Scalaセル：同じSparkSessionを共有
val df = spark.sql("SELECT * FROM numbers LIMIT 5")
df.show()

言語を切り替えてもSparkSessionは共有されるため、Pythonで作成したTempViewをSQLやScalaから参照できます。 ただしPython変数とScala変数は直接共有できないため、TempViewやDeltaテーブルを介してデータを受け渡します。

マジックコマンド一覧

%shはドライバノードのOSで実行されるため、ワーカーノードでは実行されません。 また%shの実行結果はSpark処理に直接渡せないため、ファイルの確認やデバッグ目的で使います。

共同編集とアクセス権限

Databricksノートブックはリアルタイム共同編集に対応しています。複数ユーザーが同時にセルを編集でき、 変更は即座に他のユーザーに反映されます。コメント機能や@メンションでレビューコミュニケーションも可能です。

ノートブックとフォルダには以下の4段階のアクセス権限があります。

• ジョブ用ノートブックにはCAN RUNのみ付与し、誤編集を防止
• 秘匿情報はdbutils.secrets.get()で取得。ノートブック内にパスワードやトークンを直接記述しない
• 大規模な変更はReposでブランチを作成し、PRでレビュー後にマージ

実行コンテキスト：インタラクティブ vs ジョブ

ノートブックの実行には2つのモードがあり、用途に応じて使い分けます。

# インタラクティブ実行のイメージ
# ノートブック → All-Purpose Cluster にアタッチ → セル単位で対話的に実行
#
# ジョブ実行のイメージ
# Workflows → Job Cluster を起動 → ノートブック全体を上から順に実行 → クラスタ破棄
#
# ┌─────────────┐    attach    ┌──────────────────┐
# │  Notebook    │───────────→│ All-Purpose Cluster│  (インタラクティブ)
# │ (開発・探索) │            │ (共有・状態保持)    │
# └─────────────┘            └──────────────────┘
#
# ┌─────────────┐    task     ┌──────────────────┐
# │  Workflow   │───────────→│  Job Cluster      │  (ジョブ)
# │ (定期実行)  │  create    │ (専用・毎回新規)   │
# └─────────────┘            └──────────────────┘

インタラクティブ実行では前のセルの実行結果（変数値、一時ビューなど）が後続セルに引き継がれます。 ジョブ実行では毎回クリーンな環境のため、外部状態に依存しない設計（冪等な書き込み、パラメータ受け渡し）が重要です。

ウィジェット（dbutils.widgets）によるパラメータ化

同一ノートブックを日付・環境・フィルタ条件ごとに使い回すには、ウィジェットでパラメータ化します。 Workflowsのタスクパラメータ（Base parameters）とも連携し、ジョブ実行時に値を注入できます。

%python
# ウィジェットの作成（4種類）
dbutils.widgets.text("proc_date", "2026-01-01", "処理日")
dbutils.widgets.dropdown("env", "dev", ["dev", "staging", "prod"], "環境")
dbutils.widgets.combobox("region", "APAC", ["APAC", "EMEA", "NA"], "リージョン")
dbutils.widgets.multiselect("status", "active", ["active", "inactive", "pending"], "ステータス")

# ウィジェット値の取得
proc_date = dbutils.widgets.get("proc_date")
env = dbutils.widgets.get("env")

# 取得した値をクエリに使用
df = spark.sql(f"""
    SELECT * FROM {env}_catalog.orders.daily
    WHERE order_date = '{proc_date}'
""")
df.display()

# ノートブック終了時に結果を返す（親ジョブが受け取れる）
dbutils.notebook.exit(f"OK: {proc_date}, rows={df.count()}")

ウィジェットの種類はtext（自由入力）、dropdown（単一選択）、combobox（選択+自由入力）、multiselect（複数選択）の4つです。 Workflowsからジョブ実行する場合、Base parametersのキー名がウィジェット名と一致すれば自動的に値が注入されます。

%runとdbutils.notebook.run：ノートブック間連携

ノートブックから別のノートブックを呼び出す方法は2つあり、状態共有の有無が決定的に異なります。

%python
# 方法1: %run - 同一セッションに読み込み（状態共有）
# %run ./includes/common_setup
# → common_setup内の変数・関数がすべて使える
# → 状態が混ざるため本番では注意

# 方法2: dbutils.notebook.run - 分離実行（本番推奨）
result = dbutils.notebook.run(
    "./jobs/etl_daily",
    timeout_seconds=3600,
    arguments={"proc_date": "2026-03-27", "env": "prod"}
)
print(f"子ノートブックの結果: {result}")
# → 例: "OK: 2026-03-27, rows=15234"

# 複数ノートブックの並列実行（ThreadPoolExecutorと組み合わせ）
from concurrent.futures import ThreadPoolExecutor

notebooks = ["./jobs/etl_orders", "./jobs/etl_customers", "./jobs/etl_products"]
with ThreadPoolExecutor(max_workers=3) as executor:
    futures = [
        executor.submit(dbutils.notebook.run, nb, 3600, {"proc_date": "2026-03-27"})
        for nb in notebooks
    ]
    results = [f.result() for f in futures]

Git統合（Repos）：ノートブックをコードとして管理

Databricks ReposはGitプロバイダ（GitHub、GitLab、Bitbucket、Azure DevOps）と連携し、 ノートブックやPythonモジュールをブランチ単位で管理できます。

• ブランチ運用：feature → PR → main。PRでコードレビューと承認を実施
• ノートブックはSource形式（.py）で保存すると、差分レビューが容易
• Repos配下の.pyファイルをimport可能。共通ロジックをパッケージ化してノートブックは薄く保つ
• WorkflowsのGit Source機能で特定のブランチ/タグ/コミットを参照して本番の再現性を担保

%python
# Repos配下のPythonモジュールをインポート
# /Repos/[email protected]/my-project/mypkg/transform.py
from mypkg.transform import run_etl, validate_output

# ノートブックはオーケストレーションに集中
result_df = run_etl(spark, source="s3://landing/orders/", date="2026-03-27")
validation = validate_output(result_df, expected_min_rows=1000)

if not validation["passed"]:
    dbutils.notebook.exit(f"VALIDATION_FAILED: {validation['reason']}")

result_df.write.format("delta").mode("overwrite").saveAsTable("gold.daily_orders")

再現性の確保：環境・依存関係・状態管理

• Databricks Runtimeバージョンを固定（LTS推奨）。ジョブ定義で明示
• 依存パッケージは%pip install パッケージ==バージョンでピン留め
• セッション状態（一時ビュー、キャッシュ）に依存しない設計。入力→変換→出力の純粋な流れ
• Delta Lakeの冪等書き込み（MERGE / overwrite with replaceWhere）で同じ入力から同じ結果を保証
• 乱数を使う場合はシード値を固定（random.seed / np.random.seed）

試験で問われるポイント

• %runは同一セッション（状態共有）、dbutils.notebook.runは分離実行（戻り値は文字列）
• マジックコマンドの%sqlはアタッチされたクラスタで実行（SQLウェアハウスではない）
• 権限レベル4段階（CAN VIEW / CAN RUN / CAN EDIT / CAN MANAGE）の違い
• ウィジェットとWorkflowsのBase parametersの連携
• %shはドライバノードのみで実行される（ワーカーノードでは動かない）

問題で確認

よくある質問