メインコンテンツまでスキップ

動的値参照とは

動的値参照 は、ジョブとタスクを構成するときに使用可能な変数のコレクションを記述します。 動的値参照を使用して、タスクの条件ステートメントを構成したり、情報をパラメーターまたは引数として渡したりします。

動的値参照には、次のような情報が含まれます。

  • ジョブの設定値 (ジョブ名、タスク名、トリガー・タイプなど)。
  • ジョブ ID、実行 ID、ジョブ実行開始時刻など、ジョブに関する生成されたメタデータ。
  • ジョブが行った修復の試行回数、またはタスクが実行した再試行回数に関する情報。
  • 指定したタスクの結果の状態。
  • ジョブ・パラメーター、タスク・パラメーターを使用して構成された値、またはタスク値を使用して設定された値。

動的な値参照を使う​

ジョブまたはタスクを構成するときに動的値参照を使用します。 ノートブック、クエリ、JAR などのタスクを使用して設定されたアセットから動的な値参照を直接参照することはできません。 動的な値参照は、タスクにコンテキストを渡すパラメーターまたはフィールドを使用して定義する必要があります。

動的値参照では、二重中括弧 ( ){{ }}を使用します。 ジョブまたはタスクが実行されると、文字列リテラルが動的値参照を置き換えます。 たとえば、次のキーと値のペアをタスク パラメーターとして構成するとします。

{"job_run_id": "job_{{job.run_id}}"}

実行 ID が 550315892394120の場合、 job_run_id の値は job_550315892394120と評価されます。

注記

二重中括弧の内容は、式として評価されません。 二重中括弧で操作や関数を実行することはできません。

ユーザー指定の値識別子は、英数字とアンダースコア文字をサポートします。 特殊文字を含むエスケープ キーは、識別子をバッククォート ( ) で囲みます。

存在しない動的参照値や中括弧の欠落など、構文エラーは警告なしに無視され、リテラル文字列として扱われます。 既知のネームスペースに属する無効な参照 ( {{job.notebook_url}}など) を指定すると、エラー メッセージが表示されます。

ジョブ UI での動的値参照の使用​

動的な値参照を受け入れるフィールドは、使用可能な動的な値参照を挿入するためのショートカットを提供します。 { } をクリックしてこのリストを表示し、表示されたフィールドに挿入します。

注記

UI は、タスク値を参照するためのキーをオートコンプリートしません。

動的値参照を受け入れる多くのフィールドでは、正しく使用するために追加の書式設定が必要です。 Configure タスク パラメーターを参照してください。

ジョブ JSON で動的な値参照を使用する​

Databricks CLI と REST API で使用されるジョブ JSON 定義で動的な値を使用するには、 {{ }} 構文を使用します。

ジョブ パラメーターとタスク パラメーターの構文は異なり、タスク パラメーターの構文はタスクの種類によって異なります。

次の例は、動的値参照を使用してジョブ・パラメーターを構成するための部分的な JSON 構文を示しています。

JSON
{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

次の例は、動的値参照を使用してノートブック タスク パラメーターを構成するための部分的な JSON 構文を示しています。

JSON
{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

ジョブ実行のパラメーターを確認する​

タスクが完了すると、実行詳細ページの [パラメーター ] の下に解決されたパラメーターの値が表示されます。 「ジョブ実行の詳細の表示」を参照してください。

サポートされている値参照​

次の動的値参照がサポートされています。

参考資料

説明

{{job.id}}

ジョブに割り当てられた一意の識別子。

{{job.name}}

ジョブ実行時のジョブの名前。

{{job.run_id}}

ジョブ実行に割り当てられた一意の識別子。

{{job.repair_count}}

現在のジョブ実行でのリペアの試行回数。

{{job.start_time.<argument>}}

ジョブ実行が開始された時刻 (UTC タイムゾーン) に基づく値。 戻り値は argument オプションに基づいています。 日付と時刻の値については、オプションを参照してください。

{{job.parameters.<name>}}

ジョブ・レベル・パラメーターの値で、キーは <name>です。

{{job.trigger.type}}

ジョブ実行のトリガーの種類。 指定できる値は、 periodic、 one_time、 run_job_task、 file_arrival、 continuous、および tableです。

{{job.trigger.file_arrival.location}}

このジョブにファイル到着トリガーが設定されている場合は、ストレージの場所の値。

{{job.trigger.time.<argument>}}

ジョブの実行がトリガーされた時刻 (UTC タイムゾーン) に基づく値で、cron スケジュールを持つジョブの最も近い分に切り捨てられます。 戻り値は argument オプションに基づいています。 日付と時刻の値については、オプションを参照してください。

{{task.name}}

現在のタスクの名前。

{{task.run_id}}

現在のタスク実行の一意の識別子。

{{task.execution_count}}

現在のタスクが実行された回数 (再試行と修復を含む)。

{{task.notebook_path}}

現在のノートブック タスクのノートブック パス。

{{tasks.<task_name>.run_id}}

<task_name>のタスク実行に割り当てられた一意の識別子。

{{tasks.<task_name>.result_state}}

タスクの結果の状態は <task_name>です。 指定できる値は、 success、 failed、 excluded、 canceled、 evicted、 timedout、 upstream_canceled、 upstream_evicted、および upstream_failedです。

{{tasks.<task_name>.error_code}}

タスク <task_name> のエラーコードは、タスクの実行中にエラーが発生した場合です。 可能な値の例としては、 RunExecutionError、 ResourceNotFound、 UnauthorizedErrorがあります。 タスクが成功した場合、これは空の文字列に評価されます。

{{tasks.<task_name>.execution_count}}

タスク <task_name> が実行された回数 (再試行と修復を含む)。

{{tasks.<task_name>.notebook_path}}

ノートブック タスクのノートブックへのパス <task_name>.

{{tasks.<task_name>.values.<value_name>}}

タスク<task_name>によって設定されたキー<value_name>を持つタスク値。

{{tasks.<task_name>.output.rows}}

アップストリーム SQL タスクの出力ロー <task_name>です。For eachタスク の入力 として渡された場合、各行はネストされたタスクに繰り返し送信されます。SQL 出力は 1,000 行に制限され、サイズは 48 KB に制限されています。SQL 出力オプションを参照してください。

{{tasks.<task_name>.output.first_row}}

アップストリーム SQL タスクの出力の最初の行は <task_name>です。SQL 出力は 1,000 行、サイズは 48 KB に制限されています。

{{tasks.<task_name>.output.first_row.<column_alias>}}

列の値は、アップストリーム SQL タスクの出力の最初の行 <column_alias> <task_name>です。SQL 出力は 1,000 行、サイズは 48 KB に制限されています。

{{tasks.<task_name>.output.alert_state}}

アップストリーム SQL アラート タスクの状態。値は、 UNKNOWN、 OK、 TRIGGEREDのいずれかです。

{{workspace.id}}

ワークスペースに割り当てられた一意の識別子。

{{workspace.url}}

ワークスペースの URL。

これらの参照は、任意のタスクで設定できます。 Configure タスク パラメーターを参照してください。

また、 タスク値 を使用して、ジョブ内のタスク間でパラメーターを渡すこともできます。 「タスク値を使用してタスク間で情報を渡す」を参照してください。

日付と時刻の値のオプション​

次の引数を使用して、時間ベースのパラメーター変数からの戻り値を指定します。 すべての戻り値は、UTC タイムゾーンのタイムスタンプに基づいています。

引数

説明

iso_weekday

タイムスタンプの曜日を表す 1 から 7 までの数字を返します。

is_weekday

タイムスタンプが平日の場合は true を返します。

iso_date

日付を ISO 形式で返します。

iso_datetime

日付と時刻を ISO 形式で返します。

year

タイムスタンプの年部分を返します。

month

タイムスタンプの月部分を返します。

day

タイムスタンプの日部分を返します。

hour

タイムスタンプの時間部分を返します。

minute

タイムスタンプの分部分を返します。

second

タイムスタンプの 2 番目の部分を返します。

timestamp_ms

タイムスタンプをミリ秒単位で返します。

SQL 出力オプション​

アップストリーム SQL タスクの出力には、動的な値を使用してアクセスできます。

たとえば、次の SQL を持つ sales_by_year という SQL タスクがある場合、最終的な SELECT ステートメントに基づいて出力が作成されます。

SQL
-- Generate example data
CREATE OR REPLACE TEMP VIEW example_sales AS
SELECT * FROM VALUES
  (2020, 12),
  (2021, 23),
  (2022, 47),
  (2023, 15),
  (2024, 22)
AS example_sales(sales_year, num_sales);

-- Query example data
SELECT sales_year, num_sales FROM example_sales;

ダウンストリームタスクで出力を参照するには、 {{tasks.<task_name>.output.<argument>}} 動的値を使用してタスク設定を作成します。

For eachタスクでは、行はネストされたタスクに繰り返し送信されます。この例では、For each タスクの入力を {{tasks.sales_by_year.output.rows}}に設定すると、ネストされたタスクで、構文 {{input.<column_alias>}} を使用して、行の値をパラメーターとして繰り返し送信できます。ネストされたタスク構成では、キーと値のペア year:{{input.sales_year}}と sales:{{input.num_sales}}を使用して 2 つのパラメーターを作成できます。 ネストされたタスクが SQL タスクであると仮定すると、次のようなクエリを使用してコード内の値を参照できます。

SQL
-- Example: access data from previous query:
SELECT concat('In ', :year, ' we had ', :sales, ' sales.')

For eachタスクとそのネストされたタスクの詳細については、「For eachタスクを使用してループ内の別のタスクを実行する」を参照してください。

注記

SQL クエリ出力は 7 日間保持されます。ジョブが停止する (失敗時など) に 7 日以上後に再開された場合、 SQL クエリ出力は使用できません。

非推奨の動的値リファレンス​

次の動的値リファレンスは廃止されました。 推奨される代替リファレンスは、各変数の説明に含まれています。

変数

説明

{{job_id}}

ジョブに割り当てられた一意の識別子。 代わりに job.id を使用してください。

{{run_id}}

タスク実行に割り当てられた一意の識別子。 代わりに task.run_id を使用してください。

{{start_date}}

タスクの実行が開始された日付。 形式は UTC タイムゾーンの yyyy-MM-dd です。 代わりに job.start_time.<argument> を使用してください。

{{start_time}}

クラスタリングが作成されて準備が整った後の実行開始のタイムスタンプ。 形式は、UTC タイムゾーンの UNIX エポックからのミリ秒で、 System.currentTimeMillis()で返されます。代わりに job.start_time.<format> を使用してください。

{{task_retry_count}}

最初の試行が失敗した場合にタスクの実行を試行した再試行回数。 値は最初の試行で 0 で、再試行ごとに増加します。 代わりに task.execution_count を使用してください。

{{parent_run_id}}

複数のタスクを持つジョブの実行に割り当てられた一意の識別子。 代わりに job.run_id を使用してください。

{{task_key}}

複数のタスクを持つジョブの一部であるタスクに割り当てられた一意の名前。 代わりに task.name を使用してください。

に最終更新