Variables, macros and filters can be used in templates (see the Jinja Templating section)
The following come for free out of the box with Airflow.Additional custom macros can be added globally through Plugins, or at a DAG level through theDAG.user_defined_macros
argument.
Variables¶
The Airflow engine passes a few variables by default that are accessiblein all templates
Variable | Type | Description |
---|---|---|
| Start of the data interval. Added in version 2.2. | |
| End of the data interval. Added in version 2.2. | |
| str | The DAG run’s logical date as Same as |
| str | Same as |
| str | Same as Example: |
| str | Same as Example: |
| str | Same as Example: |
| pendulum.DateTime| | Start of the data interval of the prior successful DagRun. Added in version 2.2. |
| pendulum.DateTime| | End of the data interval of the prior successful DagRun. Added in version 2.2. |
| pendulum.DateTime| | Start date from prior successful DagRun (if available). |
| DAG | The currently running DAG. You can read more about DAGs in DAGs. |
| BaseOperator | The currently running BaseOperator. You can read more about Tasks in Operators |
| A reference to the macros package. See Macros below. | |
| TaskInstance | The currently running TaskInstance. |
| TaskInstance | Same as |
| dict[str, Any] | The user-defined params. This can be overridden by the mapping passed to is enabled in |
| Airflow variables. See Airflow Variables in Templates below. | |
| Airflow variables. See Airflow Variables in Templates below. | |
| Airflow connections. See Airflow Connections in Templates below. | |
| str | A unique, human-readable key to the task instance. The format is
|
| AirflowConfigParser | The full configuration object representing the content of your
|
| str | The currently running DagRun run ID. |
| DagRun | The currently running DagRun. |
| bool | Whether the task instance was run by the |
| int | | Number of task instances that a mapped task was expanded into. If the current task is not mapped, this should be Added in version 2.5. |
| dict[str,list[DatasetEvent]] | If in a Dataset Scheduled DAG, a map of Dataset URI to a list of triggering (there may be more than one, if there are multiple Datasets with different frequencies). Read more here Datasets. Added in version 2.4. |
Note
The DAG run’s logical date, and values derived from it, such as ds
andts
, should not be considered unique in a DAG. Use run_id
instead.
Accessing Airflow context variables from TaskFlow tasks¶
While @task
decorated tasks don’t support rendering jinja templates passed as arguments,all of the variables listed above can be accessed directly from tasks. The following code blockis an example of accessing a task_instance
object from its task:
from airflow.models.taskinstance import TaskInstancefrom airflow.models.dagrun import DagRun@taskdef print_ti_info(task_instance: TaskInstance | None = None, dag_run: DagRun | None = None): print(f"Run ID: {task_instance.run_id}") # Run ID: scheduled__2023-08-09T00:00:00+00:00 print(f"Duration: {task_instance.duration}") # Duration: 0.972019 print(f"DAG Run queued at: {dag_run.queued_at}") # 2023-08-10 00:00:01+02:20
Deprecated variables¶
The following variables are deprecated. They are kept for backward compatibility, but you should convertexisting code to use other variables instead.
Deprecated Variable | Description |
---|---|
| the execution date (logical date), same as |
| the logical date of the next scheduled run (if applicable);you may be able to use |
| the next execution date as |
| the next execution date as |
| the logical date of the previous scheduled run (if applicable) |
| the previous execution date as |
| the previous execution date as |
| the day before the execution date as |
| the day before the execution date as |
| the day after the execution date as |
| the day after the execution date as |
| execution date from prior successful DAG run;you may be able to use |
Note that you can access the object’s attributes and methods with simpledot notation. Here are some examples of what is possible:{{ task.owner }}
, {{ task.task_id }}
, {{ ti.hostname }}
, …Refer to the models documentation for more information on the objects’attributes and methods.
Airflow Variables in Templates¶
The var
template variable allows you to access Airflow Variables.You can access them as either plain-text or JSON. If you use JSON, you arealso able to walk nested structures, such as dictionaries like:{{ var.json.my_dict_var.key1 }}
.
It is also possible to fetch a variable by string if needed (for example your variable key contains dots) with{{ var.value.get('my.var', 'fallback') }}
or{{ var.json.get('my.dict.var', {'key1': 'val1'}) }}
. Defaults can besupplied in case the variable does not exist.
Airflow Connections in Templates¶
Similarly, Airflow Connections data can be accessed via the conn
template variable. For example, you could use expressions in your templates like {{ conn.my_conn_id.login }}
,{{ conn.my_conn_id.password }}
, etc.
Just like with var
it’s possible to fetch a connection by string (e.g. {{ conn.get('my_conn_id_'+index).host }}
) or provide defaults (e.g {{ conn.get('my_conn_id', {"host": "host1", "login": "user1"}).host }}
).
Additionally, the extras
field of a connection can be fetched as a Python Dictionary with the extra_dejson
field, e.g.conn.my_aws_conn_id.extra_dejson.region_name
would fetch region_name
out of extras
.This way, defaults in extras
can be provided as well (e.g. {{ conn.my_aws_conn_id.extra_dejson.get('region_name', 'Europe (Frankfurt)') }}
).
Filters¶
Airflow defines some Jinja filters that can be used to format values.
For example, using {{ logical_date | ds }}
will output the logical_date in the YYYY-MM-DD
format.
Filter | Operates on | Description |
---|---|---|
| datetime | Format the datetime as |
| datetime | Format the datetime as |
| datetime | Same as |
| datetime | Same as |
| datetime | As |
Macros¶
Macros are a way to expose objects to your templates and live under themacros
namespace in your templates.
A few commonly used libraries and methods are made available.
Variable | Description |
---|---|
| The standard lib’s |
| The standard lib’s |
| A reference to the |
| The standard lib’s |
| The standard lib’s |
| The standard lib’s |
Some airflow specific macros are also defined:
- airflow.macros.datetime_diff_for_humans(dt, since=None)[source]¶
Return a human-readable/approximate difference between datetimes.
When only one datetime is provided, the comparison will be based on now.
- Parameters
dt (Any) – The datetime to display the diff for
since (DateTime | None) – When to display the date from. If
None
then the diff isbetweendt
and now.
- airflow.macros.ds_add(ds, days)[source]¶
Add or subtract days from a YYYY-MM-DD.
- Parameters
>>> ds_add("2015-01-01", 5)'2015-01-06'>>> ds_add("2015-01-06", -5)'2015-01-01'
- airflow.macros.ds_format(ds, input_format, output_format)[source]¶
Output datetime string in a given format.
- Parameters
>>> ds_format("2015-01-01", "%Y-%m-%d", "%m-%d-%y")'01-01-15'>>> ds_format("1/5/2015", "%m/%d/%Y", "%Y-%m-%d")'2015-01-05'
- airflow.macros.random() → x in the interval [0, 1).¶