(airflow) branch main updated: Clarify template context for asset-triggered DAGs in airflow-core docs (#61258)

[sh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

shahar pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/main by this push:
     new f7aa502b724 Clarify template context for asset-triggered DAGs in airflow-core docs (#61258)
f7aa502b724 is described below

commit f7aa502b724ee27cf1609c84d9d6dc8f6d9c2f68
Author: Rachana Dutta <ru...@gmail.com>
AuthorDate: Sat Jan 31 13:04:29 2026 +0530

    Clarify template context for asset-triggered DAGs in airflow-core docs (#61258)
    
    Co-authored-by: kevinhongzl <zh...@gmail.com>
---
 airflow-core/docs/templates-ref.rst | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/airflow-core/docs/templates-ref.rst b/airflow-core/docs/templates-ref.rst
index d5e3e651380..2d9aaec2f29 100644
--- a/airflow-core/docs/templates-ref.rst
+++ b/airflow-core/docs/templates-ref.rst
@@ -21,6 +21,21 @@ Templates reference
 ===================
 
 Variables, macros and filters can be used in templates (see the :ref:`concepts:jinja-templating` section)
+Asset-triggered DAGs
+--------------------
+
+Asset-triggered Dags in Apache Airflow 3 differ from time-based Dags in the
+template context they provide.
+
+Asset-triggered Dags do not have a logical date, and therefore do not provide
+time-based context variables such as ``logical_date``, ``ds``, ``ds_nodash``,
+or values derived from them.
+
+For asset-triggered Dags, information related to the triggering run can be
+accessed via ``dag_run``. For example, ``dag_run.run_id`` can be used to
+uniquely identify a Dag run triggered by an asset event.
+
+.. versionadded:: 3.0.0
 
 The variables listed on this page are provided via Airflow's execution-time context.
 
@@ -74,8 +89,13 @@ Variable                                    Type                  Description
 ``{{ var.value }}``                                               Airflow variables. See `Airflow Variables in Templates`_ below.
 ``{{ var.json }}``                                                Airflow variables. See `Airflow Variables in Templates`_ below.
 ``{{ conn }}``                                                    Airflow connections. See `Airflow Connections in Templates`_ below.
-``{{ task_instance_key_str }}``             str                   | A unique, human-readable key to the task instance. The format is
+``{{ task_instance_key_str }}``             str                   | A human-readable key to the task instance.
+                                                                  |
+                                                                  | For time-based DAGs, the format is
                                                                   | ``{dag_id}__{task_id}__{ds_nodash}``.
+                                                                  |
+                                                                  | For asset-triggered DAGs, the format uses the DAG run identifier instead:
+                                                                  | ``{dag_id}__{task_id}__{dag_run.run_id}``.
 ``{{ run_id }}``                            str                   The currently running :class:`~airflow.models.dagrun.DagRun` run ID.
 ``{{ dag_run }}``                           DagRun                The currently running :class:`~airflow.models.dagrun.DagRun`.
 ``{{ test_mode }}``                         bool                  Whether the task instance was run by the ``airflow test`` CLI.