bundle
コマンド グループ
Note
この情報は、Databricks CLI バージョン 0.218.0 以降に適用されます。 お使いの Databricks CLI のバージョンを確認するには、databricks -v
を実行してください。
Databricks CLI の bundle
コマンド グループを使用すると、Azure Databricks ワークフロー (Azure Databricks ジョブ、Delta Live Tables パイプライン、MLOps スタックなど) の検証、デプロイ、実行をプログラムで行うことができます。 「Databricks アセット バンドルとは」をご覧ください。
重要
Databricks CLI をインストールするには、「Databricks CLI のインストールまたは更新」を参照してください。 Databricks CLI の認証を構成するには、「Databricks CLI の認証」を参照してください。
bundle
コマンドは、databricks bundle
に追加して実行します。 bundle
コマンドのヘルプを表示するには、databricks bundle -h
を実行してください。
プロジェクト テンプレートからバンドルを作成する
Python 用の既定の Databricks アセット バンドル テンプレートを使用して Databricks アセット バンドルを作成するには、以下のように bundle init
コマンドを実行し、画面上のプロンプトに回答します。
databricks bundle init
既定以外の Databricks アセット バンドル テンプレートを使用して Databricks アセット バンドルを作成するには、次のように bundle init
コマンドを実行します。
databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"
関連項目:
- Databricks アセット バンドル テンプレート
- Databricks アセット バンドルを使用して Azure Databricks でジョブを開発する
- Databricks アセット バンドルを使用して Delta Live Tables パイプラインを開発する
- MLOps スタック用の Databricks アセット バンドル
バンドル構成スキーマを表示する
Databricks アセット バンドル構成スキーマを表示するには、以下のように bundle schema
コマンドを実行します。
databricks bundle schema
Databricks アセット バンドル構成スキーマを JSON ファイルとして出力するには、bundle schema
コマンドを実行し、出力を JSON ファイルにリダイレクトします。 たとえば、現在のディレクトリ内に bundle_config_schema.json
というファイルを生成するには、以下のようにします。
databricks bundle schema > bundle_config_schema.json
バンドルを検証する
バンドル構成ファイルの構文が正しいことを検証するには、次のようにバンドル プロジェクト ルートから bundle validate
コマンドを実行します。
databricks bundle validate
既定では、このコマンドは以下のようなバンドル ID のサマリーを返します。
Name: MyBundle
Target: dev
Workspace:
Host: https://my-host.cloud.databricks.com
User: someone@example.com
Path: /Users/someone@example.com/.bundle/MyBundle/dev
Validation OK!
Note
bundle validate
コマンドは、対応するオブジェクトのスキーマ内に見つからないバンドル構成ファイルでリソース プロパティが定義されている場合に警告を出力します。
バンドルのツリーをワークスペースに同期する
ローカル ファイルシステム ディレクトリ内でバンドルのファイルに加えた変更内容を、一方向の同期でリモート Azure Databricks ワークスペース内のディレクトリに反映するには、bundle sync
コマンドを実行します。
Note
bundle sync
コマンドは、リモート Azure Databricks ワークスペース内のディレクトリからローカル ファイル システム内のディレクトリにファイルの変更を同期することはできません。
databricks bundle sync
コマンドは、生産性向上のために用意されているものであり、databricks sync
コマンドと同じように機能します。 コマンドの使用法については、「sync コマンド グループを参照してください。
バンドル構成ファイルを生成する
bundle generate
コマンドを使用して、Databricks ワークスペースに既に存在するジョブまたはパイプラインのリソース構成を生成できます。 このコマンドでは、ジョブまたはパイプラインの *.yml
ファイルがバンドル プロジェクトの resources
フォルダーに生成され、ジョブまたはパイプライン構成で参照されているノートブックもダウンロードされます。 現在、このコマンドでは、ノートブック タスクを含むジョブのみがサポートされています。
重要
bundle generate
コマンドは、リソース構成を自動生成するために便宜上提供されます。 ただし、この構成がバンドルに含まれてデプロイされている場合は、リソースで最初に bundle deployment bind
が使用されていない限り、新しいリソースが作成され、既存のリソースは更新されません。
次のように bundle generate
コマンドを実行します。
databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]
たとえば、次のコマンドでは、以下の YAML を含む resources
バンドル プロジェクト フォルダーに新しい hello_job.yml
ファイルが生成され、simple_notebook.py
が src
プロジェクト フォルダーにダウンロードされます。
databricks bundle generate job --existing-job-id 6565621249
# This is the contents of the resulting hello_job.yml file.
resources:
jobs:
6565621249:
name: Hello Job
format: MULTI_TASK
tasks:
- task_key: run_notebook
existing_cluster_id: 0704-xxxxxx-yyyyyyy
notebook_task:
notebook_path: ./src/simple_notebook.py
source: WORKSPACE
run_if: ALL_SUCCESS
max_concurrent_runs: 1
バンドル リソースをバインドする
bundle deployment bind
コマンドを使うと、バンドルで定義されたジョブとパイプラインを Azure Databricks ワークスペース内の既存のジョブおよびパイプラインにリンクし、Databricks アセット バンドルの管理対象にすることができます。 リソースをバインドする場合、ワークスペース内の既存の Azure Databricks リソースは、次の bundle deploy
の後に、バインドされているバンドルで定義された構成に基づいて更新されます。
ヒント
バインドを実行する前に、バンドルのワークスペースを確認することをお勧めします。
databricks bundle deployment bind [resource-key] [resource-id]
たとえば、次のコマンドを実行すると、リソース hello_job
をワークスペース内のリモートの対応するリソースにバインドできます。 このコマンドは差分を出力し、ユーザーはリソースのバインドを拒否できますが、承認した場合は、次にバンドルがデプロイされる際に、バンドル内のジョブ定義に対するすべての更新が対応するリモート ジョブに適用されます。
databricks bundle deployment bind hello_job 6565621249
バンドル内のジョブまたはパイプラインと、ワークスペース内のリモートの対応するジョブまたはパイプラインとの間のリンクを削除したい場合は、bundle deployment unbind
を使います。
databricks bundle deployment unbind [resource-key]
バンドルをデプロイする
バンドルをリモート ワークスペースにデプロイするには、バンドル プロジェクト ルートから bundle deploy
コマンドを実行します。 コマンド オプションが指定されていない場合は、バンドル構成ファイル内で宣言されている既定のターゲットが使用されます。
databricks bundle deploy
特定のターゲットにバンドルをデプロイするには、バンドル構成ファイル内で宣言されているターゲットの名前と共に -t
(または --target
) オプションを設定します。 たとえば、dev
という名前で宣言されたターゲットの場合、
databricks bundle deploy -t dev
バンドルは、開発、ステージング、運用ワークスペースなど、複数のワークスペースにデプロイできます。 基本的に、root_path
はバンドルの一意識別子を決定するプロパティで、既定では ~/.bundle/${bundle.name}/${bundle.target}
です。 そのため、既定では、バンドルの ID は、デプロイ担当者の ID、バンドルの名前、バンドルのターゲット名で構成されます。 これらが異なるバンドル間で同一である場合、これらのバンドルのデプロイは相互に干渉します。
さらに、バンドルのデプロイでは、ターゲット ワークスペースに作成されたリソースが、ID ごとにワークスペース ファイル システムに保存されている状態として追跡されます。 リソース名は、バンドルのデプロイとリソース インスタンスの間の関連付けに使用されないため、次のようになります。
- バンドル構成のリソースがターゲット ワークスペースに存在しない場合は、自動的に作成されます。
- バンドル構成のリソースがターゲット ワークスペースに存在する場合は、ワークスペース内で更新されます。
- リソースがバンドル構成から削除された場合、以前にデプロイされていた場合は、ターゲット ワークスペースからも削除されます。
- リソースとバンドルの関連付けを解除できるのは、バンドル名、バンドルのターゲット、またはワークスペースを変更した場合のみです。
bundle validate
を実行すると、これらの値を含む概要を出力できます。
バンドルを実行する
特定のジョブまたはパイプラインを実行するには、bundle run
コマンドを使用します。 バンドル構成ファイル内で宣言されているジョブまたはパイプラインのリソース キーを指定する必要があります。 既定では、バンドル構成ファイル内で宣言された環境が使用されます。 たとえば、既定の環境でジョブ hello_job
を実行するには、次のコマンドを実行します:
databricks bundle run hello_job
dev
という名前で宣言されたターゲットのコンテキスト内で、キー hello_job
を指定してジョブを実行するには、次のようにします。
databricks bundle run -t dev hello_job
パイプライン検証の実行を行う場合は、次の例に示すように、この --validate-only
オプションを使用します:
databricks bundle run --validate-only my_pipeline
ジョブ パラメーターを渡すには、--params
オプションを使用し、その後にコンマ区切りのキーと値のペアを指定します。キーはパラメーター名です。 たとえば、次のコマンドでは、message
という名前のパラメーターをジョブ hello_job
の HelloWorld
に設定します。
databricks bundle run --params message=HelloWorld hello_job
Note
ジョブ タスク オプションを使用してジョブ タスクにパラメーターを渡すことができますが、--params
オプションはジョブ パラメーターを渡すための推奨メソッドです。 ジョブ パラメーターが定義されていないジョブにジョブ パラメーターが指定されている場合、あるいはジョブ パラメーターが定義されているジョブにタスク パラメーターが指定されている場合、エラーが発生します。
既存のジョブの実行またはパイプラインの更新をキャンセルして再開するには、--restart
オプションを使用します。
databricks bundle run --restart hello_job
バンドルを破棄する
以前にデプロイされたジョブ、パイプライン、成果物を削除するには、bundle destroy
コマンドを実行します。 以下のコマンドは、バンドル構成ファイルで定義されているジョブ、パイプライン、成果物で以前にデプロイされたものをすべて削除します。
databricks bundle destroy
Note
バンドルの ID は、バンドル名、バンドルのターゲット、ワークスペースで構成されます。 これらのいずれかを変更した後、デプロイする前にバンドルを破棄しようとすると、エラーが発生します。
既定では、以前にデプロイされたジョブ、パイプライン、成果物の完全な削除を確認するメッセージが表示されます。 これらのプロンプトをスキップし、自動的に完全削除を実行するには、--auto-approve
オプションを bundle destroy
コマンドに追加します。