`bundle` コマンドグループ

注

この情報は、Databricks CLI バージョン 0.205 以降に適用されます。 Databricks CLI はパブリックプレビュー段階です。

Databricks CLI 使用には、 Databricks ライセンスおよび Databricks プライバシー通知(使用データのプロビジョニングを含む)が適用されます。

Databricks CLI内のbundleコマンドグループを使用すると、Databricksジョブ、Delta Live Tablesパイプライン、 MLOpsスタックなどの Databricks ワークフローをプログラムで検証、デプロイ、実行できます。「Databricks アセットバンドルとは何ですか?」を参照してください。

bundle コマンドを実行するには、コマンドを databricks bundleに追加します。bundle コマンドのヘルプを表示するには、 databricks bundle -hを実行します。

プロジェクトテンプレートからのバンドルの作成

Databricksのデフォルトアセットバンドルテンプレートを使用してアセットDatabricks Pythonバンドルを作成するには、次のように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>"

バンドル構成スキーマの表示

バンドル構成スキーマを表示するには、次のように 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コマンドは、対応するオブジェクトのスキーマに見つからないリソースプロパティがバンドル構成ファイルに定義されている場合に警告を出力します。

バンドルの ID とリソースの概要のみを出力する場合は、 bundle summary を使用します。

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

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 generateを実行し、ダッシュボードの ID またはワークスペースパスを指定します。

databricks bundle generate dashboard --existing-id [dashboard-id]

databricks bundle generate dashboard --existing-path [dashboard-workspace-path]

ダッシュボードのワークスペースパスは、ワークスペース UI からコピーできます。

たとえば、次のコマンドは、以下の YAML を含む resources バンドルプロジェクトフォルダーに新しい baby_gender_by_county.dashboard.yml ファイルを生成し、baby_gender_by_county.lvdash.json ファイルを src プロジェクトフォルダーにダウンロードします。

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: "Baby gender by county"
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

ヒント

ダッシュボードを既にデプロイした後で .lvdash.json ファイルを更新するには、bundle generate dashboard を実行して既存のダッシュボードリソースのファイルを生成するときに --resource オプションを使用します。ダッシュボードの更新を継続的にポーリングして取得するには、 --force オプションと --watch オプションを使用します。

バンドルリソースをバインドする

bundle deployment bindコマンドを使用すると、バンドル定義のジョブとパイプラインを Databricks ワークスペース内の既存のジョブとパイプラインにリンクし、Databricks アセットバンドルによって管理されるようにすることができます。リソースをバインドすると、ワークスペース内の既存の Databricks リソースは、次のbundle deployの後にバインドされているバンドルで定義された構成に基づいて更新されます。

ヒント

bind を実行する前に、ワークスペースでバンドルを確認することをお勧めします。

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 summary コマンドは、バンドルの ID とリソースの概要を出力します。これには、 Databricks ワークスペース内のリソースに簡単に移動できるように、リソースのディープリンクが含まれます。

databricks bundle summary

次の出力例は、ジョブとパイプラインを定義する my_pipeline_bundle という名前のバンドルの概要です。

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

ヒント

bundle open を使用して、Databricks ワークスペース内のリソースに移動することもできます。バンドル・リソースを開くを参照してください。

バンドルのデプロイ

バンドルをリモートワークスペースにデプロイするには、バンドルプロジェクトルートから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 open コマンドを実行し、開くリソースを指定します。リソースキーが指定されていない場合、このコマンドは、選択するバンドルのリソースの一覧を出力します。

databricks bundle open [resource-key]

たとえば、次のコマンドはブラウザーを起動し、バンドル用に構成されている Databricks ワークスペース内のバンドル内の baby_gender_by_county ダッシュボードに移動します。

databricks bundle open baby_gender_by_county

バンドルを破棄する

警告

バンドルを破棄すると、バンドルの以前にデプロイされたジョブ、パイプライン、およびアーティファクトが完全に削除されます。この操作は元に戻せません。

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

databricks bundle destroy

注

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

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

bundle コマンド グループ