What is a dynamic value reference?

Dynamic value references describe a collection of variables available when configuring jobs and tasks. Use dynamic value references to configure conditional statements for tasks or to pass information as parameters or arguments.

Dynamic value references include information such as:

• Configured values for the job, including the job name, task names, and trigger type.
• Generated metadata about the job, including the job ID, the run ID, and the job run start time.
• Information about how many repair attempts a job has made or retries a task has run.
• The result state for a specified task.
• Values configured using job parameters, task parameters, or set using task values.

Use dynamic value references

Use dynamic value references when configuring jobs or tasks. You cannot directly reference dynamic value references from assets configured using tasks like notebooks, queries, or JARs. Dynamic value references must be defined using parameters or fields that pass context into tasks.

Dynamic value references use double curly braces ({{ }}). When a job or task runs, a string literal replaces the dynamic value reference. For example, if you configure the following key-value pair as a task parameter:

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

If your run ID is 550315892394120, the value for job_run_id evaluates to job_550315892394120.

Use dynamic value references in the jobs UI

Fields that accept dynamic value references provide a shortcut to insert available dynamic value references. Click { } to see this list and insert it into the provided field.

Use dynamic value references in a job JSON

Use {{ }} syntax to use dynamic values in job JSON definitions used by the Databricks CLI and REST API.

Job and task parameters have different syntax, and task parameter syntax varies by task type.

The following example shows the partial JSON syntax to configure job parameters using dynamic value references:

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

The following example shows the partial JSON syntax to configure notebook task parameters using a dynamic value reference:

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

Review parameters for a job run

After a task completes, you can see resolved parameter values under Parameters on the run details page. See View job run details.

Supported value references

The following dynamic value references are supported:

You can set these references with any task. See Configure task parameters.

You can also pass parameters between tasks in a job with task values. See Use task values to pass information between tasks.

Options for date and time values

Use the following arguments to specify the return value from time-based parameter variables. All return values are based on a timestamp in the UTC timezone.

Deprecated dynamic value references

The following dynamic value references are deprecated. The recommended replacement reference is included in the description of each variable.