databricks-execution-compute

Databricks の実行とコンピュート

Databricks でコードを実行します。実行モードは 3 種類あります。ワークロードに合わせて選択してください。以下の例はすべて Databricks CLI を使用します。インストールと認証については、databricks-core スキルを参照してください。

実行モードの判断マトリクス

観点	Databricks Connect ⭐	サーバーレスジョブ	インタラクティブクラスター
用途	Spark コード（ETL、データ生成）	大規模な処理（ML）	ツール呼び出し間で状態を保持する場合、Scala/R
起動時間	即時	コールドスタートで約 25～50 秒	停止中の場合、約 5 分
状態	Python プロセス内	なし	context_id 経由
言語	Python（PySpark）	Python、SQL	Python、Scala、SQL、R
依存関係	withDependencies()	環境仕様を指定した CLI	クラスターにインストール

判断フロー

主な判断ポイント：Declarative Automation Bundles（DAB）を使用している場合は、まず databricks-dabs スキルの手順に従ってください。簡単に言うと、databricks bundle run を使用して、ジョブ、パイプライン、その他のリソースに関連付けられたコードを実行できます。プロジェクトのルートにある databricks.yml ファイルで、これらのリソースの有無を確認できます。これらのリソースが存在しない場合、または DAB を使用していない場合は、以下に進んでください。

すべての Spark ベースのワークロードでは Databricks Connect を優先し、次にサーバーレスを使用してください。

Spark-based code? → Databricks Connect (fastest)
  └─ Python 3.12 missing? → Install it + databricks-connect
  └─ Install fails? → Ask user (don't auto-switch modes)

Heavy/long-running (ML)? → Serverless Job (independent)
Need state across calls? → Interactive Cluster (list and ask which one to use)
Scala/R? → Interactive Cluster (list and ask which one to use)

コードの実行方法

先に、選択したモードのリファレンスファイルを読んでください。

Databricks Connect（ローカルで実行。純粋な Spark コードの場合に推奨）→ リファレンス

from databricks.connect import DatabricksSession
...
spark = DatabricksSession.builder.profile("my-local-profile").serverless(True).getOrCreate()


python my_spark_script.py

サーバーレスジョブ → リファレンス

純粋な CLI の手順：ローカルファイルをワークスペースのノートブックとしてアップロードし、databricks jobs submit で 1 回限りの実行を開始します（作成と実行を 1 回の呼び出しで行います。エフェメラルであり、Jobs UI にエントリーは作成されず、再試行もありません）。その後、ポーリングして結果を取得します。ローカルファイルは Databricks ソースノートブックである必要があります。先頭行は # Databricks notebook source（Python）または -- Databricks notebook source（SQL）です。

1. ローカルファイルをワークスペースのノートブックとしてアップロードします。 TARGET_PATH は位置引数です。--file はローカルパスです。

databricks workspace import /Workspace/Users/<user>/.ai_dev_kit/train --file /local/path/to/train.py --format SOURCE --language PYTHON --overwrite

2. 実行を送信します。 --no-wait を指定すると、すぐに {"run_id": N} が返されます。指定しない場合は、実行が終了するまで待機します。依存関係をインストールするには "client": "4" が必要です（"1" では依存関係が黙って無視されます）。

databricks jobs submit --no-wait --json @submit.json

{
  "run_name": "train-run",
  "tasks": [{
    "task_key": "main",
    "notebook_task": {"notebook_path": "/Workspace/Users/<user>/.ai_dev_kit/train"},
    "environment_key": "ml_env"
  }],
  "environments": [{
    "environment_key": "ml_env",
    "spec": {"client": "4", "dependencies": ["scikit-learn==1.5.2", "mlflow==2.22.0"]}
  }]
}

3. 状態を確認し、完了を待ちます。 ライフサイクル：PENDING → RUNNING → TERMINATED（または SKIPPED / INTERNAL_ERROR）。ライフサイクルが TERMINATED になってから、.state.result_state（SUCCESS / FAILED / CANCELED）を読み取ってください。

databricks jobs get-run <RUN_ID> | jq '{state: .state.life_cycle_state, result: .state.result_state, duration_ms: .execution_duration, url: .run_page_url, task_run_id: .tasks[0].run_id}'

4. 出力またはエラーを取得します。 注意点： get-run-output が受け取るのはタスクの run_id（.tasks[0].run_id）であり、submit から返される親の run_id ではありません。notebook_output.result は dbutils.notebook.exit() に渡された文字列です。

databricks jobs get-run-output <TASK_RUN_ID> | jq '{result: .notebook_output.result, error, error_trace}'

ノートブックでは必ず dbutils.notebook.exit(<string>) を使用してください。print() の出力は get-run-output では取得されません。JSON の結果を返す場合は、dbutils.notebook.exit(json.dumps({...})) を使用し、クライアント側で .notebook_output.result を解析してください。

インタラクティブクラスター → リファレンス

デフォルトでは使用しないでください。Serverless Job を優先してください。 インタラクティブクラスターを使用するのは、次の場合に限ります。

• すでに稼働中の既存のクラシッククラスターを利用できる場合、または
• 複数回の呼び出しにわたる、ライブで状態を保持する実行が必要な場合（実行コンテキストを使ったデバッグなど）、または
• ユーザーから明示的に要求された場合

インタラクティブクラスターは起動が遅く（3-8 min）、稼働中は費用が発生します。暗黙的に起動しないでください。

CLI コマンド一覧

コンピュートのライフサイクル管理とコード実行の操作は、すべて Databricks CLI を通じて行います。主なコマンドは次のとおりです。

操作	コマンド
ローカルファイルをワークスペースノートブックとしてアップロード	databricks workspace import <WORKSPACE_PATH> --file <LOCAL> --format SOURCE --language PYTHON --overwrite
サーバーレスコードを実行（アップロード＋送信＋待機）	databricks jobs submit --json @submit.json（上記の Serverless Job セクションを参照。非同期実行には --no-wait を指定）
実行状態の取得／待機	databricks jobs get-run <RUN_ID>（.state.life_cycle_state をポーリング）
実行出力の取得	databricks jobs get-run-output <TASK_RUN_ID>
クラスターの一覧表示	databricks clusters list --output json
クラスターの詳細取得	databricks clusters get <CLUSTER_ID>
クラスターの起動／再起動／終了	databricks clusters start/restart/delete <CLUSTER_ID>
クラスターの完全削除	databricks clusters permanent-delete <CLUSTER_ID>
クラスターの作成	databricks clusters create --json '{...}'（3-interactive-cluster.md を参照）
ノードタイプ／Spark バージョンの一覧表示	databricks clusters list-node-types / databricks clusters spark-versions
稼働中のクラスターでコードを実行	databricks api post /api/1.2/contexts/create + databricks api post /api/1.2/commands/execute（3-interactive-cluster.md を参照）
SQL ウェアハウス	databricks warehouses create/list/get/start/stop/edit/delete（下記の SQL ウェアハウスを参照）

SQL ウェアハウス

ID を受け取るコマンドはすべて位置引数を使用します（--id フラグはありません）。ID を確認するには databricks warehouses list を使用してください。

# Create a serverless SQL warehouse. min_num_clusters + max_num_clusters are REQUIRED
# (the server rejects the default 0). Keep the aidevkit_project tag for resource tracking.
databricks warehouses create --json '{
  "name": "my-warehouse",
  "cluster_size": "Small",
  "enable_serverless_compute": true,
  "auto_stop_mins": 10,
  "min_num_clusters": 1,
  "max_num_clusters": 1,
  "tags": {"custom_tags": [{"key": "aidevkit_project", "value": "ai-dev-kit"}]}
}'

# List / find — trim to id, name, state with jq
databricks warehouses list -o json | jq '.[] | {id, name, state, size: .cluster_size}'

# Find by name
databricks warehouses list -o json | jq '.[] | select(.name == "my-warehouse")'

# Get one warehouse's full config
databricks warehouses get <WAREHOUSE_ID>

# Start / stop (both are LROs; add --no-wait to return immediately)
databricks warehouses start <WAREHOUSE_ID>
databricks warehouses stop  <WAREHOUSE_ID>

# Resize / reconfigure — pass the FULL desired config (omitted fields revert to defaults,
# so always re-state min_num_clusters/max_num_clusters). Use --no-wait if the warehouse
# is STOPPED, otherwise edit blocks trying to reach RUNNING and errors out (the mutation
# itself still applies). When the warehouse is already RUNNING, --no-wait is optional.
databricks warehouses edit <WAREHOUSE_ID> --no-wait --json '{
  "name": "my-warehouse",
  "cluster_size": "Medium",
  "enable_serverless_compute": true,
  "auto_stop_mins": 15,
  "min_num_clusters": 1,
  "max_num_clusters": 1
}'

# Delete (irreversible)
databricks warehouses delete <WAREHOUSE_ID>

サイズ： 2X-Small、X-Small、Small、Medium、Large、X-Large、2X-Large、3X-Large、4X-Large。タイプ： JSON 本文で "warehouse_type": "PRO"（デフォルト）または "CLASSIC" を設定します。

関連スキル

• databricks-synthetic-data-gen — Spark + Faker を使用したデータ生成
• databricks-jobs — 本番ジョブのオーケストレーション
• databricks-dbsql — SQL ウェアハウスと AI 関数