Databricks アセットバンドルの代替と変数

[アーティクル]
10/04/2024

Databricks アセットバンドルは、代替とカスタム変数をサポートしているため、バンドル構成ファイルのモジュール性と再利用性が高まります。代替とカスタム変数の両方は値を動的に取得できるようにするため、バンドルの配置時と実行時に設定を決定できます。

ヒント

また、ジョブ実行に関するコンテキストをジョブタスクに渡すために、ジョブパラメーター値に動的値参照を使用することもできます。「動的値参照とは」および「ジョブのパラメーター化」を参照してください。

置換

代替を使用して、バンドルの配置と実行のコンテキストに基づいて変更される設定の値を取得できます。

たとえば、bundle validate --output json コマンドを実行すると、次のようなグラフが表示されることがあります。

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

代替を使用してバンドル name、バンドル target、ワークスペース userName フィールドの値を参照し、バンドル構成ファイルにワークスペース root_path を構築できます。

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

名前付きリソースの置換を作成することもできます。たとえば、my_pipeline という名前で構成されたパイプラインの場合、${resources.pipelines.my_pipeline.target} は my_pipeline のターゲットの値の置換です。

有効な置換を判別するには、「REST API リファレンス」で記載されているスキーマ階層を使用するか、bundle schema コマンドの出力を使用することができます。

一般的に使用される置換を次に示します。

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}

カスタム変数

バンドルで単純なカスタム変数と複雑なカスタム変数の両方を定義し、多くのシナリオで必要な値の動的な取得を有効にできます。カスタム変数は、variables マッピングの中のバンドル構成ファイルで宣言されます。「変数」を参照してください。

次の構成例では、my_cluster_id と my_notebook_path の変数を定義します。

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

この宣言の一部として変数に default 値を指定しない場合は、「変数の値を設定する」の説明に従って、バンドルコマンドの実行時、環境変数、またはバンドル構成ファイル内の他の場所で変数を設定する必要があります。

バンドル構成内でカスタム変数を参照するには、変数の代替 ${var.<variable_name>} を使用します。たとえば、my_cluster_id と my_notebook_path の変数を参照するには、次の内容を行います。

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

変数の値を設定する

変数に default 値を指定していない場合、または変数の default 値を一時的にオーバーライドする場合は、次の方法のいずれかを使用して変数の新しい一時的な値を指定します。

validate、deploy、run などの bundle コマンドの一部として変数の値を指定します。これを行うには、オプション --var="<key>=<value>" を使用します。ここで、<key> は変数の名前、<value> は変数の値です。たとえば、bundle validate コマンドの一部として、my_cluster_id という名前の変数に 1234-567890-abcde123 の値を指定し、my_notebook_path という名前の変数に ./hello.py の値を指定するには、以下を実行します。
```
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
```
環境変数を設定して、変数の値を指定します。環境変数の名前は BUNDLE_VAR_ で始まる必要があります。環境変数を設定するには、オペレーティングシステムのドキュメントを参照してください。たとえば、my_cluster_id という名前の変数に 1234-567890-abcde123 の値を指定し、my_notebook_path という名前の変数に ./hello.py の値を指定するには、validate、deploy、run などの bundle コマンドを呼び出す前に、次のコマンドを実行します。

Linux および macOS の場合:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Windows の場合:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
または、たとえば、Linux や macOS の場合、validate、deploy、run などの bundle コマンドの一部として、変数の値を指定します。
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
または Windows の場合:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
バンドル構成ファイル内で変数の値を指定します。これを行うには、この形式に従って、targets マッピング内で variables マッピングを使用します。
```
variables:
  <variable-name>: <value>
```
たとえば、2 つの個別のターゲットについて、my_cluster_id と my_notebook_path という名前の変数に値を指定するには、次のようにします。
```
targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py
```

Note

変数値を指定するためにどの方法を選んでも、デプロイと実行の両方のステージで同じ方法を使用してください。そうしないと、デプロイの時点から、その既存のデプロイに基づくジョブまたはパイプラインの実行までの間に予期しない結果が得られる可能性があります。

前の例では、Databricks CLI によって、次の順序で変数 my_cluster_id と my_notebook_path の値が検索されます。一致する各変数の値が見つかると停止され、その変数の他の場所はスキップされます。

bundle コマンドの一部として指定された --var オプション内。
BUNDLE_VAR_ で始まる環境変数セット内。
バンドル構成ファイル内の targets マッピングの中の任意の variables マッピング内。
バンドル構成ファイル内の最上位レベルの variables マッピングの中で、その変数を定義する任意の default 値。

複合変数を定義する

複合変数として定義しない限り、カスタム変数はタイプ文字列であると想定されます。バンドルの複合型を持つカスタム変数を定義するには、バンドル構成で type を complex に設定します。

Note

type 設定の有効な値は complex のみです。さらに、type が complex に設定され、その変数に定義されている default が 1 つの値である場合、バンドルの検証は失敗します。

次の例で、クラスター設定は my_cluster という名前のカスタム複合変数内で定義されています。

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

オブジェクトの ID 値を取得する

alert、cluster_policy、cluster、dashboard、instance_pool、job、metastore、pipeline、query、service_principal、warehouse オブジェクト型の場合は、次の形式を使用して、名前付きオブジェクトの ID を取得するカスタム変数の lookup を定義することができます。

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

変数に対して lookup が定義されている場合、指定した名前を持つオブジェクトの ID が変数の値として使用されます。これにより、オブジェクトの正しい解決済み ID が、常に変数で使用されることが保証されます。

Note

指定した名前を持つオブジェクトが存在しない場合、または指定した名前を持つオブジェクトが複数存在する場合は、エラーが発生します。

たとえば次の構成において、${var.my_cluster_id} は 12.2 shared クラスターの ID に置き換えられます。

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

次の方法で共有

Databricks アセットバンドルの代替と変数

置換

カスタム変数

変数の値を設定する

複合変数を定義する

オブジェクトの ID 値を取得する

フィードバック

その他のリソース

次の方法で共有

Databricks アセット バンドルの代替と変数

置換

カスタム変数

変数の値を設定する

複合変数を定義する

オブジェクトの ID 値を取得する

フィードバック

その他のリソース

Databricks アセットバンドルの代替と変数