計算資源を作り込み、コードを書く場所を決める — クラスタ設定とノートブック／ローカル IDE

3.1クラスタの中身とサイジング — Driver / Worker / Instance pool / Instance fleet / ハードウェア選定とクラスタ設定 JSON の export・import

クラスタの作成画面を初めて開くと、ノードタイプ、台数、Auto termination の分数を一度に聞かれます。基準が分からないまま大きめを選び、月末の請求で驚く。台数を考える前に「どの種類のコンピュートを使うか」を決め、それからサイジングに入ります。

まず 4 つの選択肢から選ぶ

判断の軸は 2 つです。誰がいつ使うのかと、起動待ちとアイドル時間の課金をどこまで許すのかです。

サーバーレスコンピュートは、インスタンスタイプもメモリも処理エンジンも Databricks が継続的に最適化する方式で、ノードタイプや台数を指定しません。パフォーマンスモードは 2 つあり、performance optimized は起動を速くする側、standard は起動に 4〜6 分かかることを許す代わりに安い側です。サーバーレスのノートブックには既定で 2.5 時間 (9,000 秒) の実行タイムアウトがあり、超えたクエリはキャンセルされます。同じサーバーレスでも SQL ウェアハウスは SQL クエリ専用の窓口で、ノートブックの PySpark を走らせる場所ではありません。

もう 1 つの分岐点が Photon です。Photon は Databricks が C++ で書き直したクエリエンジンで、Databricks Runtime 9.1 LTS 以上では既定で有効です。API や Automation Bundle から作るときは `runtime_engine` に `PHOTON` を指定します。SQL や DataFrame API の集計・結合・スキャンは速くなりますが、UDF (自分で書いてデータに適用する関数)、RDD API、Dataset API には対応しません。2 秒未満で終わるクエリも、計画作りの時間が支配的なので速くなりません。サーバーレスと SQL ウェアハウスでは自動的に有効になります。

Driver は結果を受け取る係、Worker は計算する係

クラスタは Driver 1 台と Worker 0 台以上でできています。`num_workers` を n にすると Spark ノードは合計 n+1 台になり、Databricks はワーカーノード 1 台につき executor を 1 つ動かします。

Driver はタスクを実行しません。処理の依存関係グラフ (DAG) を組み立てて配り、`collect()` や `toPandas()` で集まった結果を受け取り、アタッチされている全ノートブックの状態を保持します。既定では Driver のノードタイプは Worker と同じで、大量の結果を手元に集めるときだけ Driver を大きくします。「Driver は必ず Worker より大きく」という決まりはありません。

ワーカーを持たない構成が Single node です。Driver が master と worker を兼ね、論理コア 1 つにつき executor スレッドを 1 つ、Driver 用に 1 コアを差し引いて起動します。複数ノードのクラスタをワーカー 0 台まで縮めることはできず、Single node を複数ノードへ変換することもできません。ワーカーが 0 台のクラスタでは Spark のコマンドは失敗し、GPU スケジューリングも無効です。

ハードウェアは「シャッフルするかどうか」で選ぶ

大きな JOIN や集約はシャッフル (ノードをまたいだデータの並べ替え) を伴い、中間データがメモリとローカルディスクに広がります。単機のコア数を上げるより、メモリ最適化型を複数台並べるほうが効きます。

AWS の classic compute では、各ワーカーノードに 30 GB の EBS instance root volume (ホスト OS と Databricks 内部サービス用) と 150 GB の暗号化された EBS container root volume (Spark worker 用) が既定で用意され、HIPAA 対応ワークスペースではさらに 75 GB の暗号化ログ用ボリュームが付きます。30 GB のほうは暗号化の有無が公式ドキュメント間で食い違っており、暗号化を前提にした設計は避けます。ディスクが足りなくなると自動で追加され、1 VM あたり合計 5 TB が上限です。

台数と稼働時間を人に任せない

Premium プランでは optimized autoscaling が使われ、最小から最大まで多くても 2 回のスケーリングで上がります。下げる判断は用途で分かれ、ジョブコンピュートは直近 40 秒、汎用コンピュートは直近 150 秒使用率が低ければワーカーを減らします。判定の間隔は `spark.databricks.aggressiveWindowDownS` で調整でき、指定できる最大は 600 秒です。

止め忘れを機械的に止めるのが `autotermination_minutes` です。指定できるのは 10 分から 10000 分までで、0 は自動終了の明示的な無効化、既定は 60 分です。10 分より短い値は設定できません。

起動待ちと在庫切れを Instance pool と fleet で解く

Instance pool はアイドル状態の VM を確保しておく仕組みです。プールで待機している間、Databricks の DBU (Databricks 側の使用量を数える単位) は課金されませんが、クラウド事業者の VM 料金は発生します。クラスタが TERMINATED になると使っていたインスタンスはプールに戻り、別のクラスタが再利用します。オートスケールと併用した場合、増やすときはまずプールの在庫から取り、不足分だけ新規に起動します。

Driver と Worker で別のプールを指定でき、API では `driver_instance_pool_id` と `instance_pool_id` に分かれます。AWS と Azure では 1 つのプールは全部 spot (クラウドの余剰在庫を安く借りる枠。回収されることがある) か全部 on-demand のどちらかで、混在できません。AWS の spot 上限価格は既定で on-demand 価格の 100% です。Driver に spot のプールを使ってはいけません。Preloaded Databricks Runtime を None にすると、待機ノードに Runtime を都度ダウンロードすることになります。Minimum Idle Instances の台数はアイドル自動終了の設定にかかわらず残り、要求がプールの最大容量を超えると `INSTANCE_POOL_MAX_CAPACITY_FAILURE` で失敗します。

プールを使わない通常のクラスタで spot を有効にした場合、最初の 1 台である Driver は常に on-demand で、2 台目以降が spot になります。spot の在庫切れで型が取れない問題には、AWS の fleet インスタンスタイプ (`m-fleet.xlarge` のような可変の型) が効きます。fleet は GPU インスタンスに対応しません。flexible node types が有効なワークスペースでは、指定した型が取れないとき互換のある別の型へフォールバックします。

作った設定を JSON で持ち出す

既存クラスタの Configuration タブから JSON を開くと、設定全体が表示されます。この JSON ビューは読み取り専用で、その場では編集できません。コピーして Clusters API に渡すのが正しい使い方です。終了したクラスタは 30 日後に完全に削除され、Pin できるのはワークスペースあたり 100 個までです。イベントログの保持は 60 日です。Clone は設定とインストール済みライブラリを引き継ぎますが、権限とアタッチ済みノートブックは引き継ぎません。誤って削除したクラスタを戻す手順も同じで、保管しておいた JSON を Clusters API に渡して作り直します。Delta のタイムトラベルやワークスペースのごみ箱はデータやノートブック向けの機能で、計算資源には効きません。

3.2クラスタ環境を作り込む — クラスタポリシー、init script（UC Volumes 推奨・DBFS 非推奨）、ライブラリのスコープ

クラスタを 1 台作れるようになると、次に来るのは「全員が好き勝手な設定で作り始めた」という問題です。誰かが大量のワーカーを立てて放置し、誰かのノートブックでだけライブラリが入っていて他の人の環境では動かない。設定を人の善意に任せるのをやめる道具が 3 つあります。効くタイミングが違うので、混同すると期待どおりに動きません。

ポリシーは属性ごとに 1 つだけルールを書く

クラスタポリシーは、作成時の属性に対する制約を JSON で宣言したものです。型は 7 つで、この並びをそのまま覚えます。

落とし穴になるのが、1 つの属性に書ける制約は 1 つだけという規則です。「ノードタイプを allowlist で絞ったうえに regex もかける」はできません。`fixed` と `forbidden` 以外の 5 つには `defaultValue` と `isOptional` を添えられ、`isOptional` を書かなければその属性は必須になります。`hidden` を使えるのは `fixed` だけです。さらに、Clusters API からクラスタを作るときは `apply_policy_default_values` を `true` にしない限り `defaultValue` が適用されません。UI では既定値が入るのに API では入らない、という食い違いはここから生まれます。`randomize` のような型は存在しません。

ゼロから書く必要はありません。policy family という Databricks 提供のテンプレートを選ぶとルールが継承され、そこへ追加や上書きをしていけます。使わせる相手の指定は権限側の話で、ポリシーに Can Use を持つユーザーだけがそのポリシーを選んでクラスタを作れます。逆に、ポリシーで縛れないものもはっきりしています。SQL ウェアハウスの設定はウェアハウス側で個別に管理しますし、外部ストレージへ書けるかどうかは Unity Catalog の外部ロケーションとストレージ資格情報が決めます。

init script は Volumes に置く。DBFS はもう動かない

OS レベルのパッケージや社内証明書のように、クラスタが立ち上がりきる前に入れておきたいものは init script (起動時にノード上で走る bash スクリプト) で入れます。試験で問われるのは中身より置き場所です。

DBFS 上の init script は end-of-life に達しており、クラスタを起動する前にほかの置き場所へ移す必要があります。実行順も決まっていて、管理者がワークスペース全体に登録する global init script が、クラスタ個別の cluster-scoped より先に走ります。アクセスモード (そのクラスタを誰が使えて何ができるかを決める設定) による差もあり、ワークスペースファイル上のスクリプトは standard access mode では使えず、Volumes 上のスクリプトは分離なしの共有モードでは使えません。notebook-scoped な init script という分類は存在しません。スクリプト本体は起動のたびに読みに行くため、置いたファイルを消すとそれ以降の起動が失敗します。

ライブラリは 3 つのスコープを使い分ける

compute-scoped はクラスタ設定の Libraries に登録するもので、そのクラスタに接続する全ノートブックとジョブで共有され、再起動のたびに自動で入れ直されます。ソースは PyPI / Maven / CRAN / ワークスペースファイル / Unity Catalog Volumes / クラウドオブジェクトストレージです。DBFS ルートへの配置は Databricks Runtime 14.3 LTS 以下では可能ですが非推奨で、15.1 以上では既定で無効化されています。standard access mode では JAR と Maven 座標を管理者が allowlist に登録する必要があり、CRAN は使えません。

notebook-scoped は `%pip install pandas==2.2.2` のようにセルで入れるもので、そのノートブックのセッションにだけ効きます。セッションをまたいで残らないため、接続し直すたびに入れ直しが必要です。JAR は入れられず、対象は Python と R に限られます。3 つめが job-scoped で、ジョブ定義の側にライブラリを書く形です。「ワークスペース全体へ強制配布する」という独立した機能は存在しないので、全員に同じ環境を配りたいならポリシーと compute-scoped ライブラリを組み合わせます。

`%pip` には引っかかりやすい挙動があります。インストールしても Python プロセスは自動では再起動しないため、新しいパッケージを確実に読み込ませるには `dbutils.library.restartPython()` を実行します。

3.3ノートブックを使いこなす — マジックコマンド（%pip / %sql と存在しない %git）、Revision history、共同編集、Export 形式、セル操作

ノートブックは開けばすぐ動くので軽く見られがちですが、実際には細かい構文規則と上限値の塊です。`%sql` をセルの 2 行目に書いてパースエラーになる、消してしまったセルの戻し方が分からない、結果が途中で切れている理由が分からない。どれも知っていれば 10 秒、知らないと数十分を溶かす種類の困りごとです。

マジックコマンドは 1 行目、1 セルに 1 つ

ノートブックには既定言語が 1 つありますが、セル単位で言語を切り替えられます。使えるマジックは `%python` / `%sql` / `%scala` / `%r` / `%sh` / `%md` / `%pip` / `%run` / `%fs` / `%skip` などです。セルマジックは 1 セルに 1 つだけ、しかも必ずセルの 1 行目に書きます。前に空行やコメントが 1 行あるだけでパースエラーになるので、`%sql` が動かないときはまず行位置を疑います。`%run` はさらに厳しく、ノートブック全体をその場で実行する性質上、単独のセルに置かなければなりません。

言語をまたいだ変数の共有はできません。ある言語の REPL (そのコードを評価する環境) で定義した変数は、別の言語の REPL からは見えません。例外的な橋渡しとして、`%sql` セルの実行結果は `_sqldf` という DataFrame で後続の Python から参照できます。`%sh` は Driver ノードの上だけで動くシェルで、Worker には届きません。ワーカー全台に何かを入れたいなら、前節の init script の出番です。

もう 1 つ、`%git` というマジックは存在しません。Git の pull や commit は、サイドバーの Git UI、`/api/2.0/repos` の REST API、または Databricks CLI から行います。存在しないマジックを打って失敗する形は試験でもよく出るので、実在するマジックの一覧を先に頭へ入れておきます。

アタッチ、セル操作、可視化

ノートブックはコンピュートに接続していないと実行できません。最初にやるのは、画面右上のドロップダウンからクラスタを選んでアタッチすることです。停止していれば起動を促されます。セルは右上のメニューの Copy か、標準の `Ctrl` + `C` / `V` で複製できます。行を選んで `Ctrl` + `/` を押すと、Python なら `#`、SQL なら `--` でのコメントアウトが切り替わります。`%md` セルは実行すると Markdown としてレンダリングされ、セルの実行結果はノートブックを保存しても消えません。

可視化は `display(df)` が出した結果の上にある「+」から Visualization を選び、種類と軸の列を指定します。Line / Bar / Area / Pie / Heatmap / Histogram では集計も設定できます。ロジックを追いたいときは、`print` を撒く前に組み込みのデバッガを使います。Settings の Developer で Python Notebook Interactive Debugger を有効にすると、サーバーレス、standard access mode なら Databricks Runtime 14.3 LTS 以上、dedicated access mode なら 13.3 LTS 以上で使えます。ただしステップインできるのはワークスペース内のファイルに定義された関数までで、Python ライブラリや別ノートブックの中には入れません。デバッグコンソールは 15 秒でタイムアウトし、`display` は使えないので `df.show()` や `df.head()` を使います。

消したセルは Version history から戻す

ノートブックは編集のたびにスナップショットが保存され、履歴パネルから任意の版を選んで「Restore this version」で戻せます。版に説明を付ける、特定の版を削除する、履歴をまとめて消すこともできますが、まとめて消した履歴は元に戻せません。クラスタの再起動は実行コンテキストを消すだけで、セルの中身とは無関係です。

Git フォルダの中では事情が変わります。`git pull` のようにノートブックのソースを書き換える Git 操作は、セル出力・コメント・バージョン履歴・ウィジェットを失わせます。commit や push はソースを書き換えないため、これらは保たれます。Git 管理下のノートブックで履歴に頼るのは危険で、履歴の役目は Git 側に移ったと考えます。

共同編集は排他ロックではありません。複数人が同じノートブックを同時に編集でき、互いのカーソル位置と編集内容が見えます。「先に開いた人が編集権を独占する」「チェックアウトするまで他人は見られない」といった古い方式ではありません。

Export 形式とサイズ上限

File メニューからの Export では、ソース形式 (.py / .sql / .scala / .r)、HTML、.ipynb、DBC アーカイブ、R Markdown (.Rmd) を選べます。フォルダ単位では DBC アーカイブ、ZIP (Source)、ZIP (HTML) です。ソース形式ではセルの境界が `# COMMAND ----------` という行として保存されるため、戻したときもセル分割が保たれます。SQL なら `--`、Scala なら `//` で始まる同じ行になります。DBC はメタデータとセル出力を含み、フォルダ階層ごと 1 ファイルに固められます。

「結果が途中で切れている」と感じたときは、まずテーブル表示の 10,000 行という壁を疑ってください。全件が必要ならテーブルへ書き出して SQL で数えるほうが確実です。

3.4ノートブックをつなぐ・ローカルから動かす — %run と dbutils.notebook.run の実行コンテキストの違い、Databricks Connect と VS Code 拡張

ノートブックが 5 本、10 本と増えると、同じ前処理関数をコピペで配って回る事態になります。共通化しようとして分割すると、今度は「呼んだ先で定義したはずの関数が見えない」「戻り値が文字列にしかならない」で詰まります。さらに開発が進むと、ブラウザの中だけでは pytest もブレークポイントも回らないという壁に当たります。

`%run` は同じ部屋、`dbutils.notebook.run` は別の部屋

違いは実行コンテキストの一語に尽きます。`%run` は指定したノートブックをその場に展開し、呼び出し元とまったく同じ Python プロセス・同じ Spark セッションで実行します。だから向こうで定義された関数・変数・import がそのまま手元で使えます。逆方向にも通っていて、呼び出し元で先に定義した変数を向こうから参照できます。

# Notebook A
x = 10
%run ./notebook_b
print(y)

# Notebook B
y = x + 5

この A を実行すると `15` が表示されます。`notebook_b` 側から A の `x` を参照できているからです。パスは `./utils` のような相対指定でも `/Workspace/Shared/utils` のような絶対パスでも構いません。

一方 `dbutils.notebook.run(path, timeout_seconds, arguments)` は、子ノートブックを新しいジョブとして独立した実行コンテキストで起動します。親の関数も変数も、子からは一切見えません。やりとりできるのは次の 2 経路だけです。

• 行き — `arguments` に渡したマップがウィジェット経由で子に入る。受け付けるのは Latin 文字 (ASCII) だけで、それ以外はエラーになる
• 帰り — 子が `dbutils.notebook.exit(value)` で返した文字列 1 つだけ。長さの上限は 5 MB

`timeout_seconds` に 0 を指定するとタイムアウトなしです。この API で作られたジョブは 30 日以内に完了する必要があり、Databricks 側が 10 分以上停止すると `timeout_seconds` の値にかかわらず失敗します。表にすると使い分けは明快です。

大きなデータを返したくなったら、設計のほうを疑ってください。ジョブのタスク間で値を渡す `dbutils.jobs.taskValues.set()` にしても、JSON 表現で 48 KiB が上限です。データそのものはテーブルや Volumes に書き、受け渡すのはパスや件数といった小さな値にとどめる前提の設計になっています。

Git フォルダ配下の `%run` には固有の罠があります。`%run` は、そのときワークスペースに保存されている本文を読んで実行するだけです。リモートのリポジトリで更新されていても、Pull していなければ古いコミットのコードが動き続けます。「直したはずなのに反映されない」の原因はたいていこれで、自動 Pull の仕組みは `%run` 側にはありません。

ノートブックをやめて `.py` として `import` する

`%run` は手軽ですが、依存関係が暗黙になり、単体テストも書きにくくなります。共通ロジックが育ってきたら、ノートブックではなく通常の Python ファイルに移し、`import` で読む形へ切り替えます。

これを支えているのがワークスペースファイルの仕組みです。Databricks Runtime 11.3 LTS 以上では、ノートブックのカレントディレクトリが自動的に Python のパスへ追加されます。Git フォルダの場合はリポジトリのルートが追加されます。つまり同じフォルダに `sample.py` を置けば、`from sample import power` がそのまま通ります。別の階層から読みたいときだけ、`sys.path.append(os.path.abspath('..'))` のように自分でパスを足します。

Databricks Runtime 13.3 LTS 以上では、`sys.path` に加えたディレクトリや Python パッケージの形をしたディレクトリが、クラスタの全 executor へ自動的に配られます。12.2 LTS 以下では executor へ明示的に入れる必要がありました。編集しながら試すときは `%load_ext autoreload` と `%autoreload 2` が使えますが、autoreload が効くのは Spark のドライバプロセスの中だけで、executor には反映されません。UDF のようにワーカーで動くコードを書いているときは頼らないでください。

ローカル IDE から動かす Databricks Connect

ブラウザのノートブックでは、手元の Git、型チェック、ブレークポイント、pytest といった道具立てがそのまま使えません。Databricks Connect はこの不足を埋めるクライアントで、コードはローカルで書いて実行し、Spark の計算だけをクラスタまたはサーバーレスコンピュートへ送ります。接続中も Unity Catalog の権限は通常どおり効くので、ガバナンスの抜け道ではありません。

pip3 uninstall pyspark
pip3 install --upgrade "databricks-connect==17.3.*"

導入時に外せない点が 3 つあります。1 つめ、`databricks-connect` は `pyspark` パッケージと衝突するので、先に `pyspark` をアンインストールします。2 つめ、接続先クラスタの Databricks Runtime に合わせて `==X.Y.*` の形でバージョンを固定します。3 つめ、対応するのは Databricks Runtime 13.3 LTS 以上です。コード側の入り口は 2 行で、ノートブックで自動的に用意されていた `spark` を自分で組み立てるだけです。

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

この `spark` に対する `spark.read` や DataFrame の操作は、手元では実行されずリモートのコンピュートへ送られます。ローカルの CPU で Spark が動くわけではない、という点は取り違えやすいところです。サーバーレスに繋ぐ場合は環境変数 `DATABRICKS_SERVERLESS_COMPUTE_ID` に `auto` を設定します。この指定があると `cluster_id` は無視されます。逆にクラスタ側で受け口を閉じたいときは、Spark 設定に `spark.databricks.service.server.enabled false` を入れます。

できないことも整理しておきます。`SparkContext` と RDD API は使えず、それらに依存する GraphFrames のようなライブラリも動きません。dbutils も全部は使えず、`credentials` / `library` / `notebook workflow` / `widgets` は対象外です。この `notebook workflow` が使えないという 1 行が、「Databricks Connect からは `%run` も `dbutils.notebook.run` も使えない」の正体です。`display()` も使えません。`CREATE TABLE ... AS SELECT` の構文も通らないので、`spark.sql("SELECT ...").write.saveAsTable("table")` に書き換えます。未解決の論理プランが 128 MB を超える DataFrame や、3600 秒を超える長いクエリも対象外です。`applyInPandas()` と `cogroup()` は Databricks Runtime 16.3 以上かつ standard access mode が要ります。

VS Code 拡張で日常の開発をまとめる

Databricks の VS Code 拡張は、ここまでの作業を 1 つのエディタに寄せます。ローカルのコードをワークスペースへ同期し、ローカルの Python ファイルをクラスタやサーバーレス上で実行し、ノートブック (.py / .ipynb / .r / .scala / .sql) をジョブとして走らせられます。Databricks Connect と組み合わせればノートブックをセル単位でデバッグでき、`databricks.yml` を置けば Declarative Automation Bundles のデプロイまで同じ場所から行えます。ただし R / Scala / SQL はジョブとして実行できるだけで、エディタ内での深い支援は Python が中心です。

最後に、共通コードの置き場所を規模で 3 段階に整理します。ちょっとしたヘルパなら `%run`。テストしたい共通ロジックなら Git フォルダに `.py` を置いて通常の `import` で読む。組織全体へ配るなら wheel (Python パッケージを 1 ファイルに固めた配布形式) にして、クラスタライブラリやポリシー経由で配る。困りごとの規模に合わせてこの順に上げていくのが、いちばん失敗の少ない道筋です。