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 コマンドに追加します。