Databricks Asset Bundle プロジェクトテンプレート

Databricks アセットバンドルは、ジョブ、パイプライン、ノートブックなどの Databricks リソースをソースファイルとして記述し、これらのソースファイルと共にメタデータを含めてインフラストラクチャやその他のリソースをプロビジョニングし、プロジェクトのエンドツーエンドの定義を提供し、すべて 1 つのデプロイ可能なプロジェクトとしてパッケージ化します。「Databricks アセットバンドルとは」を参照してください。

バンドルテンプレートを使用すると、ユーザーは、フォルダー構造、ビルドステップとタスク、テスト、およびデプロイパイプライン全体で共通のその他の DevOps Infrastructure-as-Code (IaC) 属性を確立することで、一貫性のある反復可能な方法でバンドルを作成できます。

たとえば、カスタムパッケージを必要とする Databricks ジョブを日常的に実行し、インストール時にコンパイル手順が時間がかかる場合は、カスタムコンテナー環境を指定するバンドルテンプレートを作成することで、開発ループを高速化できます。

Databricks にはデフォルトのバンドルテンプレートのセットが用意されていますが、カスタムバンドルテンプレートを作成することもできます。その後、ユーザーは bundle init コマンドを使用してバンドルを初期化し、デフォルト・テンプレートまたはカスタム・テンプレートを指定できます。

テンプレートを使用したバンドルの作成

Databricks バンドルテンプレートを使用してバンドルを作成するには、 Databricks CLI bundle init コマンドを使用して、使用するテンプレートの名前を指定します。たとえば、次のコマンドは、デフォルトの Python バンドルテンプレートを使用してバンドルを作成します。

databricks bundle init default-python

カスタムバンドルテンプレートを使用するには、テンプレートのローカルパスまたはリモート URL を Databricks CLI bundle init コマンドに渡します。

たとえば、次のコマンドでは、カスタムバンドルテンプレートチュートリアルで作成したdab-container-templateテンプレートを使用します。

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

テンプレートを指定しない場合、 bundle init コマンドを実行すると、選択可能なデフォルト・テンプレートのセットが表示されます。

デフォルトのバンドルテンプレート

Databricks には、次のデフォルトバンドルテンプレートが用意されています。

テンプレート	説明
`default-python`	Databricks で Python を使用するためのテンプレート。このテンプレートは、ジョブと DLT パイプラインを含むバンドルを作成します。デフォルト-Pythonを参照してください。
`default-sql`	Databricks で SQL を使用するためのテンプレート。このテンプレートには、SQLウェアハウスに対してクエリを実行するジョブを定義する構成ファイルSQL含まれています。デフォルト-sql を参照してください。
`dbt-sql`	ローカル開発に dbt-core を活用し、デプロイにバンドルを活用するテンプレート。このテンプレートには、dbtタスクを持つジョブを定義する設定と、デプロイされたdbtジョブのdbtプロファイルを定義する設定ファイルが含まれています。dbt-sql を参照してください。
`mlops-stacks`	新しい MLOps スタックプロジェクトを開始するための高度なフルスタックテンプレート。 MLOps スタックについては、 mlops-stacks と Databricks アセットバンドルを参照してください。

カスタムバンドルテンプレート

バンドルテンプレートは Go パッケージテンプレート構文を使用するため、作成できるカスタムバンドルテンプレートに柔軟性があります。Go パッケージテンプレートのドキュメントを参照してください。

テンプレートプロジェクトの構造

バンドルテンプレートプロジェクトには、少なくとも次のものが必要です。

バンドルプロジェクト名の 1 つのユーザープロンプトプロパティを定義するプロジェクトルートの databricks_template_schema.json ファイル。テンプレートスキーマを参照してください。
template フォルダにある databricks.yml.tmpl ファイルで、テンプレートを使用して作成されたバンドルの設定を定義します。databricks.yml.tmpl ファイルが追加の *.yml.tmpl 構成テンプレートを参照している場合は、include マッピングでこれらの場所を指定します。「YML 設定テンプレート」を参照してください。

また、バンドルテンプレートプロジェクト template フォルダのフォルダ構造とインクルードファイルは、テンプレートで作成されたバンドルによってミラーリングされます。たとえば、 src フォルダーに単純なノートブック、 resources フォルダーにノートブックを実行するジョブ定義を含むバンドルをテンプレートで生成する場合は、テンプレートプロジェクトを次のように整理します。

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      ├── databricks.yml.tmpl
      ├── resources
      │   └── {{.project_name}}_job.yml.tmpl
      └── src
          └── simple_notebook.ipynb

ヒント

このバンドル・テンプレート内のジョブ定義ファイルの名前は、テンプレート変数を使用します。テンプレートヘルパーと変数に関する情報については、テンプレートヘルパーと変数を参照してください。

テンプレートスキーマ

カスタムバンドルテンプレートプロジェクトには、プロジェクトルートに databricks_template_schema.json [JSON ファイル](https://json-schema.org/specification.html が含まれている必要があります。このファイルは、プロンプトテキストなど、 bundle init コマンドの実行時に Databricks CLI によって使用されるフィールドを定義します。

次の基本的な databricks_template_schema.json ファイルは、プロンプトメッセージとデフォルト値を含む、バンドルプロジェクトの入力変数 project_name を定義します。次に、メッセージ内の入力変数値を使用するブンデ・プロジェクトの初期化の成功メッセージを定義します。

JSON
{
  "properties": {
    "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
    }
  },
  "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

テンプレートスキーマフィールド

databricks_template_schema.json ファイルでは、バンドルの初期化中に properties フィールド内のユーザーから情報を収集するための入力変数の定義と、初期化をカスタマイズするための追加フィールドの定義がサポートされています。

入力変数は、テンプレートスキーマの properties フィールドで定義されます。各入力変数は、バンドルの開始時にユーザーにプロンプトを表示するために必要なメタデータを定義します。変数の値には、 {{.project_name}}などのテンプレート変数構文を使用してアクセスできます。

また、一部のフィールドの値を設定して、バンドルの初期化プロセスをカスタマイズすることもできます。

サポートされているスキーマフィールドを次の表に示します。

スキーマフィールド	説明
`properties`	バンドル・テンプレートの入力変数定義。Databricks では、バンドルプロジェクトの名前である入力変数を少なくとも 1 つ定義することをお勧めします。
`properties.<variable_name>`	入力変数の名前。
`properties.<variable_name>.default`	ユーザーが `bundle init` コマンドの一部として `--config-file` を使用して値を指定しない場合、またはコマンド行で値の入力を求められたときに値が指定されていない場合に使用するデフォルト値。
`properties.<variable_name>.description`	入力変数に関連付けられたユーザー・プロンプト・メッセージ。
`properties.<variable_name>.enum`	プロパティに指定できる値のリスト ( `"enum": ["azure", "aws", "gcp"]`など)。このフィールドが定義されている場合、Databricks CLI はコマンドラインに値を一覧に表示し、ユーザーに値を選択するように求めます。
`properties.<variable_name>.order`	入力プロパティの相対的な順序を定義する整数。これにより、これらの入力変数のプロンプトがコマンドラインに表示される順序が制御されます。
`properties.<variable_name>.pattern`	ユーザー入力の検証に使用する正規表現パターン (例: `"pattern": "^[^ .\\\\/]{3,}$"`.サポートされている正規表現の構文については、 https://github.com/google/re2/wiki/Syntax を参照してください。
`properties.<variable_name>.pattern_match_failure_message`	ユーザーが入力した値が指定されたパターンと一致しない場合にユーザーに表示されるメッセージ (例: `Project name must be at least 3 characters long and cannot contain the following characters: \"\\\", \"/\", \" \" and \".\"."`)。
`properties.<variable_name>.skip_prompt_if`	入力変数の入力を求めるプロンプトをスキップします。このスキーマが既に存在する構成によって満たされている場合は、その変数の入力をスキップします。その場合は、代わりにプロパティのデフォルト値が使用されます。例については、 mlops-stacks テンプレートを参照してください。`const`の比較のみがサポートされています。
`properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const`	`<previous_variable_name>` の値が `skip_prompt_if`で設定された定数と一致する場合、`<variable_name>`のプロンプトはスキップされます。
`welcome_message`	ユーザーに入力を求める前に出力する最初のメッセージ。
`success_message`	テンプレートが正常に初期化された後に印刷するメッセージ。
`min_databricks_cli_version`	テンプレートに必要なこの Databricks CLI の最小 semver バージョン。CLI のバージョンがこのバージョンより小さい場合、`databricks bundle init` は失敗します。
`version`	将来の使用のために予約されています。スキーマのバージョン。これは、スキーマが現在の CLI バージョンと互換性があるかどうかを判断するために使用されます。

YML 設定テンプレート

カスタム・バンドル・テンプレートには、バンドル・プロジェクト・databricks.ymlの作成に使用されるバンドル・テンプレート・プロジェクト内のtemplateフォルダにdatabricks.yml.tmplファイルが含まれている必要があります。このテンプレートファイルに基本構成テンプレート YAML を入力します。

次の databricks.yml および関連する *ジョブ.ymlの設定テンプレートの例です。バンドル名と 2 つのターゲット環境を設定し、このテンプレートを使用して作成されたバンドルに対して、バンドル内のノートブックを実行するジョブを定義します。これらの設定テンプレートは、バンドル置換とバンドルテンプレートヘルパーを利用します。バンドルの置換とバンドルテンプレートヘルパーを参照してください。

YAML
# databricks.yml
# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    
    {{end -}}

YAML
# {{.project_name}}_job.yml
# The main job for {{.project_name}}

resources:
    jobs:
        
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

テンプレートヘルパーと変数

テンプレートヘルパーは、 Databricks によって提供される関数であり、テンプレートファイル内で使用して、ランタイム時にユーザー固有の情報を取得したり、テンプレートエンジンと対話したりできます。独自のテンプレート変数を定義することもできます。

次のテンプレートヘルパーは、Databricks バンドルテンプレートプロジェクトで使用できます。Go テンプレートと変数の使用に関する情報については、「 Go テンプレート」を参照してください。

ヘルパー	説明
`{{url}}`	https://pkg.go.dev/net/url#Parse のエイリアス。これにより、 `url.URL`のすべての方法を使用できます。
`{{regexp}}`	https://pkg.go.dev/regexp#Compile のエイリアス。これにより、 `regexp.Regexp`のすべての方法を使用できます。
`{{random_int}}`	半開間隔 (0,n) の非負の擬似乱数を int として返します。
`{{uuid}}`	RFC 4122 で定義されている 128 ビット (16 バイト) の Universal Unique IDentifier である UUID を文字列として返します。この ID は、テンプレートの実行期間中は安定しており、テンプレート作成者が 1 databricks.yml の `bundle.uuid` フィールドに入力するために使用できます。
`{{bundle_uuid}}`	バンドルの一意の ID。この関数を複数回呼び出すと、同じ UUID が返されます。
`{{pair}}`	キーと値のペア。これは、テンプレート内で使用するマップを生成するために `map` ヘルパーと共に使用されます。
`{{map}}`	ペアのリストをマップオブジェクトに変換します。これは、ライブラリディレクトリで定義されたテンプレートに複数のオブジェクトを渡す場合に便利です。テンプレートを呼び出すための Go テキストテンプレート構文では 1 つの引数しか指定できないため、この関数を使用してその制限を回避できます。たとえば、次の行では、 `{{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}}`、 `$arg1` 、 `$arg2` を内部 `my_template` から `.foo` と `.bar`と呼ぶことができます。
`{{smallest_node_type}}`	最小のノードタイプを返します。
`{{path_separator}}`	オペレーティング・システムのパス・セパレータ文字。これは、Unix ベースのシステムには `/` 、Windows には `\` です。
`{{workspace_host}}`	ユーザーが現在認証されているワークスペースのホストURL。
`{{user_name}}`	テンプレートを初期化するユーザーのフルネーム。
`{{short_name}}`	テンプレートを初期化するユーザーの短い名前。
`{{default_catalog}}`	デフォルトのワークスペースカタログを返します。デフォルトがない場合、または Unity Catalog が有効になっていない場合は、空の文字列が返されます。
`{{is_service_principal}}`	現在のユーザーがサービスプリンシパルであるかどうか。
`{{ skip <glob-pattern-relative-to-current-directory> }}`	テンプレートエンジンは、入力 glob パターンに一致するすべてのファイルとディレクトリの生成をスキップします。例については、 mlops-stacks テンプレートを参照してください。

独自の変数を定義するには、テンプレートプロジェクトの library フォルダにテンプレートファイルを作成し、Go テンプレート構文を使用して変数を定義します。たとえば、次の library/variables.tmpl ファイルの内容では、変数 cli_version と model_nameを定義しています。このテンプレートを使用してバンドルを初期化すると、 model_name 変数の値は、テンプレート・スキーマ・ファイルで定義された input_project_name フィールドを使用して作成されます。このフィールド値の値は、プロンプトの後のユーザー入力です。

Go

{{ define `cli_version` -}}
    v0.240.0

{{- end }}

{{ define `model_name` -}}
    
    {{ .input_project_name }}-model

{{- end }}

完全な例については、 mlops-stacks テンプレート変数ファイルを参照してください。

バンドルテンプレートのテスト

最後に、テンプレートを必ずテストしてください。新しいバンドルプロジェクトフォルダーを作成し、Databricks CLI を使用して、テンプレートを使用して新しいバンドルを初期化します。

databricks bundle init basic-bundle-template

プロンプト What is your bundle project name?に「 my_test_bundle」と入力します。

テストバンドルが作成されると、スキーマファイルからの成功メッセージが出力されます。 my_test_bundleフォルダの内容を調べると、次のように表示されます。

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

そして、databricks.ymlファイルとジョブがカスタマイズされました。

YAML
# databricks.yml
# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

YAML
# my_test_bundle_job.yml
# The main job for my_test_bundle

resources:
    jobs:
        my_test_bundle_job:
        name: my_test_bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

テンプレートを共有してください

このバンドルテンプレートを他のユーザーと共有する場合は、Git がサポートし、ユーザーがアクセスできる任意のプロバイダーを使用してバージョン管理に保存できます。 Git URL を使用して bundle init コマンドを実行するには、 databricks_template_schema.json ファイルがその Git URL を基準としたルートの場所にあることを確認します。

ヒント

databricks_template_schema.json ファイルは、バンドルのルートを基準にして別のフォルダーに配置できます。その後、 bundle init コマンドの --template-dir オプションを使用して、 databricks_template_schema.json ファイルを含むフォルダーを参照できます。

次のステップ

Databricks によって作成および保守される追加のテンプレートを参照します。 GitHub のバンドルサンプルリポジトリを参照してください。
MLOps スタックを Databricks アセットバンドルテンプレートで使用するには、「 MLOps スタックの Databricks アセットバンドル」を参照してください。
Goパッケージのテンプレート化についてもっと学びましょう。 Go パッケージテンプレートのドキュメントを参照してください。

テンプレートを使用したバンドルの作成​

デフォルトのバンドルテンプレート​

カスタムバンドルテンプレート​

テンプレート プロジェクトの構造​

テンプレート スキーマ​

テンプレート スキーマ フィールド​

YML 設定テンプレート​

テンプレート ヘルパーと変数​

バンドルテンプレートのテスト​

テンプレートを共有してください​

次のステップ​