`bundle` コマンドグループ

注

この情報は、Databricks CLI バージョン 0.218.0 以降に適用されます。 Databricks CLI のバージョンを確認するには、 databricks -vを実行します。

Databricks CLI 内の bundle コマンドグループを使用すると、Databricks ジョブ、Delta Live Tables パイプライン、MLOps スタックなどの Databricks ワークフローをプログラムで検証、デプロイ、実行できます。「 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 アセットバンドル構成スキーマを表示するには、次のように 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!

注

bundle validateコマンドは、対応するオブジェクトのスキーマに見つからないリソースプロパティがバンドル構成ファイルに定義されている場合に警告を出力します。

バンドルのツリーをワークスペースに同期する

bundle sync コマンドを使用して、ローカルファイルシステムディレクトリ内のバンドルのファイル変更をリモート Databricks ワークスペース内のディレクトリに一方向同期します。

注

bundle sync コマンドは、リモートの Databricks ワークスペース内のディレクトリからローカルファイルシステム内のディレクトリにファイルの変更を同期することはできません。

databricks bundle sync コマンドは databricks sync コマンドと同じように機能し、生産性の便宜のために提供されています。コマンドの使用状況については、「 sync コマンドグループ」を参照してください。

バンドル構成ファイルの生成

bundle generateコマンドを使用すると、Databricks ワークスペースにすでに存在するジョブまたはパイプラインのリソース構成を生成できます。このコマンドは、バンドルプロジェクトのresourcesフォルダーにジョブまたはパイプラインの*.ymlファイルを生成し、ジョブまたはパイプライン構成で参照されているノートブックもダウンロードします。現在、このコマンドではノートブックタスクを含むジョブのみがサポートされています。

重要

bundle generateコマンドは、リソース構成を自動生成するための便宜のために提供されています。ただし、この構成がバンドルに含まれてデプロイされると、新しいリソースが作成され、そのリソースで最初にbundle deployment bindが使用されない限り、既存のリソースは更新されません。

次のようにbundle generateコマンドを実行します。

databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]

たとえば、次のコマンドは、以下の YAML を含む新しいhello_job.ymlファイルをresourcesバンドルプロジェクトフォルダに生成し、 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コマンドを使用すると、バンドル定義のジョブとパイプラインを Databricks ワークスペース内の既存のジョブとパイプラインにリンクし、Databricks アセットバンドルによって管理されるようにすることができます。リソースをバインドすると、ワークスペース内の既存の 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プロパティはバンドルの一意の ID を決定するもので、デフォルトでは~/.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オプションを使用し、その後にカンマ区切りのキーと値のペアを使用します。ここで、キーは問題名です。たとえば、次のコマンドは、ジョブhello_jobの名前messageの保留をHelloWorldに設定します。

databricks bundle run --params message=HelloWorld hello_job

注

ジョブタスクオプションを使用してジョブタスクに問題を渡すことができますが、ジョブタスクを渡すには--paramsオプションが推奨される方法です。ジョブ確保が定義されていないジョブにジョブ確保を指定した場合、またはジョブ確保が定義されているジョブにタスク確保を指定した場合は、エラーが発生します。

既存のジョブの実行またはパイプラインの更新をキャンセルして再開するには、 --restartオプションを使用します。

databricks bundle run --restart hello_job

バンドルを破棄する

以前にデプロイされたジョブ、パイプライン、アーティファクトを削除するには、 bundle destroyコマンドを実行します。次のコマンドは、バンドル構成ファイルで定義されている、以前にデプロイされたすべてのジョブ、パイプライン、およびアーティファクトを削除します。

databricks bundle destroy

注

バンドルの ID は、バンドル名、バンドルターゲット、およびワークスペースで構成されます。これらのいずれかを変更し、デプロイ前にバンドルを破棄しようとすると、エラーが発生します。

デフォルトにより、以前にデプロイされたジョブ、パイプライン、およびアーティファクトの完全な削除を確認するように求められます。これらのプロンプトをスキップして自動完全削除を実行するには、 bundle destroy コマンドに --auto-approve オプションを追加します。

bundle コマンド グループ