bundle コマンド グループ

注記

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

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

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

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

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

Databricksのデフォルト アセット バンドル テンプレートを使用して アセットDatabricks Pythonバンドルを作成するには、次のようにbundle init コマンドを実行し、画面のプロンプトに応答します。

Bash

databricks bundle init

カスタム Databricks アセット バンドル テンプレートを使用して Databricks アセット バンドルを作成するには、次のように bundle init コマンドを実行します。

Bash

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

関連項目は次を参照してください。

• Databricks Asset Bundle プロジェクト テンプレート
• Databricks Asset Bundles を使用して Databricks でジョブを開発
• Databricks Asset Bundles を使用した DLT パイプラインの開発
• MLOpsスタックのDatabricksアセットバンドル

バンドル設定スキーマを表示します

バンドル構成スキーマを表示するには、次のように bundle schema コマンドを実行します。

Bash

databricks bundle schema

Databricks Asset Bundle 構成スキーマを JSON ファイルとして出力するには、 bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトします。 たとえば、次のように、現在のディレクトリに bundle_config_schema.json という名前のファイルを生成できます。

Bash

databricks bundle schema > bundle_config_schema.json

バンドルの検証

バンドル構成ファイルが構文的に正しいことを検証するには、次のように、バンドル・プロジェクトのルートから bundle validate コマンドを実行します。

Bash

databricks bundle validate

デフォルトでは、このコマンドはバンドル ID の要約を返します。

Output

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 ファイルを生成し、構成で参照されているノートブックなどのファイルもダウンロードします。

ジョブまたはパイプライン設定の生成

important

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

ジョブまたはパイプラインの設定を生成するには、次のように bundle generate コマンドを実行します。

Bash

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

注記

現在、このコマンドでサポートされているのは、ノートブック タスクを持つジョブのみです。

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

Bash

databricks bundle generate job --existing-job-id 6565621249

YAML

# 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 またはワークスペースパスを指定します。

Bash

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

Bash

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 プロジェクト フォルダーにダウンロードします。

Bash

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

YAML

# 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 を実行する前に、ワークスペースでバンドルを確認することをお勧めします。

Bash

databricks bundle deployment bind [resource-key] [resource-id]

たとえば、次のコマンドは、リソース hello_job をワークスペース内の対応するリモートにバインドします。 このコマンドは diff を出力し、リソース・バインディングを拒否できますが、確認された場合、バンドル内のジョブ定義に対する更新は、バンドルが次にデプロイされるときに対応するリモート・ジョブに適用されます。

Bash

databricks bundle deployment bind hello_job 6565621249

バンドル内のジョブ、パイプライン、またはスキーマとワークスペース内の対応するリモートとの間のリンクを削除する場合は、 bundle deployment unbind を使用します。

Bash

databricks bundle deployment unbind [resource-key]

バンドルの概要を出力する

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

Bash

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 コマンドを実行します。 コマンド・オプションが指定されていない場合は、バンドル構成ファイル内で宣言されているデフォルト・ターゲットが使用されます。

Bash

databricks bundle deploy

バンドルを特定のターゲットにデプロイするには、-t (または --target) オプションと、バンドル設定ファイル内で宣言されているターゲットの名前を設定します。 たとえば、dev という名前で宣言されたターゲットの場合:

Bash

databricks bundle deploy -t dev

バンドルは、開発、ステージング、本番運用 ワークスペースなど、複数のワークスペースにデプロイできます。 基本的に、 root_path プロパティはバンドルの一意の ID を決定するもので、デフォルトは ~/.bundle/${bundle.name}/${bundle.target}です。 したがって、デフォルトでは、バンドルの ID は、デプロイヤの ID、バンドルの名前、およびバンドルのターゲット名で構成されます。 これらが異なるバンドル間で同一である場合、これらのバンドルのデプロイは互いに干渉します。

さらに、バンドル・デプロイメントは、ターゲット・ワークスペースに作成したリソースを、ワークスペース・ファイル・システムに格納されている状態として ID によって追跡します。 リソース名は、バンドル・デプロイメントとリソース・インスタンスの相関関係には使用されないため、次のようになります。

• バンドル構成内のリソースがターゲット ワークスペースに存在しない場合は、そのリソースが作成されます。
• バンドル構成内のリソースがターゲット ワークスペースに存在する場合、そのリソースはワークスペースで更新されます。
• リソースがバンドル構成から削除されると、そのリソースは以前にデプロイされていた場合はターゲット ワークスペースから削除されます。
• リソースとバンドルの関連付けを忘れることができるのは、バンドル名、バンドル・ターゲット、またはワークスペースを変更した場合のみです。 bundle validate を実行して、これらの値を含む概要を出力できます。

ジョブまたはパイプラインを実行する

特定のジョブまたはパイプラインを実行するには、 bundle run コマンドを使用します。 バンドル設定ファイル内で宣言されているジョブまたはパイプラインのリソースキーを指定する必要があります。 デフォルトでは、バンドル設定ファイル内で宣言された環境が使用されます。 たとえば、デフォルト環境でジョブ hello_job を実行するには、次のコマンドを実行します。

Bash

databricks bundle run hello_job

キー hello_job を持つジョブを、 devという名前で宣言されたターゲットのコンテキスト内で実行するには、次のようにします。

Bash

databricks bundle run -t dev hello_job

パイプライン検証の実行を行う場合は、次の例に示すように、--validate-only オプションを使用します。

Bash

databricks bundle run --validate-only my_pipeline

ジョブ パラメーターを渡すには、--params オプションを使用し、その後にコンマ区切りのキーと値のペア (キーはパラメーター名) を付けます。たとえば、次のコマンドは、ジョブhello_jobの名前が message のパラメーターを HelloWorld に設定します。

Bash

databricks bundle run --params message=HelloWorld hello_job

注記

ジョブ タスク オプションを使用して パラメーター をジョブ タスクに渡すこともできますが、ジョブ パラメーターを渡すには --params オプションを使用することをお勧めします。 ジョブ・パラメーターが定義されていないジョブにジョブ・パラメーターが指定されている場合、またはジョブ・パラメーターが定義されているジョブにタスク・パラメーターが指定されている場合は、エラーが発生します。

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

Bash

databricks bundle run --restart hello_job

バンドルリソースを開く

ワークスペース内のバンドル・リソースに移動するには、バンドル・プロジェクトのルートから bundle open コマンドを実行し、開くリソースを指定します。 リソース キーが指定されていない場合、このコマンドは、選択するバンドルのリソースの一覧を出力します。

Bash

databricks bundle open [resource-key]

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

Bash

databricks bundle open baby_gender_by_county

バンドルを破壊する

警告

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

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

Bash

databricks bundle destroy

注記

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

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