This is an automated email from the ASF dual-hosted git repository.
pierrejeambrun 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 5bc196f5528 docs: Clarify manual DAG run data interval semantics in
Airflow 3 (#64740)
5bc196f5528 is described below
commit 5bc196f5528ae94c6468fd63418d813ce020c653
Author: Gwak Beomgyu <[email protected]>
AuthorDate: Thu May 21 22:51:06 2026 +0900
docs: Clarify manual DAG run data interval semantics in Airflow 3 (#64740)
---
airflow-core/docs/core-concepts/dag-run.rst | 18 ++++++++
.../docs/installation/upgrading_to_airflow3.rst | 48 +++++++++++++++++++++-
2 files changed, 65 insertions(+), 1 deletion(-)
diff --git a/airflow-core/docs/core-concepts/dag-run.rst
b/airflow-core/docs/core-concepts/dag-run.rst
index 2f5cd3c5a66..b536681036b 100644
--- a/airflow-core/docs/core-concepts/dag-run.rst
+++ b/airflow-core/docs/core-concepts/dag-run.rst
@@ -76,6 +76,24 @@ scheduled one interval after ``start_date``.
For more information on ``logical date``, see :ref:`concepts-dag-run` and
:ref:`faq:what-does-execution-date-mean`
+Manual Triggering and Data Intervals
+'''''''''''''''''''''''''''''''''''''
+
+When you manually trigger a Dag (for example from the UI, CLI, REST API, or
+``TriggerDagRunOperator``), do not assume the run's ``data_interval`` is
+derived from, or equal to, the supplied ``logical_date``.
+
+For scheduled runs, the timetable defines the data interval directly. For
+manually triggered runs, the resulting ``data_interval`` depends on the
+timetable and the trigger path, and may differ from the run's
+``logical_date``.
+
+If your Dag logic needs the user-specified date for a manual run, use
+``logical_date`` explicitly instead of assuming it matches
+``data_interval_start`` or ``data_interval_end``.
+
+For upgrade guidance, see :ref:`data-interval-manual-triggering`.
+
Re-run Dag
''''''''''
There can be cases where you will want to execute your Dag again. One such
case is when the scheduled
diff --git a/airflow-core/docs/installation/upgrading_to_airflow3.rst
b/airflow-core/docs/installation/upgrading_to_airflow3.rst
index 4020aee4634..91e86cb3ccb 100644
--- a/airflow-core/docs/installation/upgrading_to_airflow3.rst
+++ b/airflow-core/docs/installation/upgrading_to_airflow3.rst
@@ -126,7 +126,7 @@ You can also configure these flags through configuration
files. See `Configuring
Key Import Updates
^^^^^^^^^^^^^^^^^^
-While ruff can automatically fix many import issues, here are the key import
changes you'll need to make to ensure your DAGs and other
+While ruff can automatically fix many import issues, here are the key import
changes you'll need to make to ensure your Dags and other
code import Airflow components correctly in Airflow 3. The older paths are
deprecated and will be removed in a future Airflow version.
.. list-table::
@@ -388,6 +388,7 @@ These include:
Airflow 3 dagruns already exist (going
``CronTriggerTimetable`` -> ``CronDataIntervalTimetable``), one scheduled run
is skipped to avoid colliding with the previous run's ``logical_date``.
+- **Manual Dag runs and data intervals**: In Airflow 3, do not assume that a
manually triggered Dag run's ``data_interval`` is derived from, or equal to,
the supplied ``logical_date``. If your Dag logic needs the user-specified
trigger date, use ``logical_date`` explicitly. This especially affects
workflows that read ``data_interval_start`` or ``data_interval_end`` during
manual triggering or when using ``TriggerDagRunOperator``. For detailed
migration guidance, see :ref:`data-interval-m [...]
- **Simple Auth** is now default ``auth_manager``. To continue using FAB as
the Auth Manager, please install the FAB provider and set ``auth_manager`` to
``FabAuthManager``:
.. code-block:: ini
@@ -406,3 +407,48 @@ These include:
# Airflow 3 - specify task_ids to pull from other tasks
value = ti.xcom_pull(task_ids="upstream_task", key="shared_state")
+
+.. _data-interval-manual-triggering:
+
+Manual Dag Runs and ``logical_date``
+====================================
+
+For scheduled runs, ``logical_date`` and ``data_interval`` are both derived
from
+the Dag's timetable.
+
+For manually triggered runs in Airflow 3, do not assume that
+``data_interval_start`` or ``data_interval_end`` are derived from, or equal to,
+the supplied ``logical_date``. The resulting ``data_interval`` depends on the
+timetable and the trigger path, and some APIs also allow the data interval to
+be provided explicitly.
+
+This matters most for Dags that:
+
+- use ``data_interval_start`` or ``data_interval_end`` during manual runs
+- trigger downstream Dags with ``TriggerDagRunOperator``
+- migrated from Airflow 2 and treated ``data_interval_start`` as the requested
+ manual run date
+
+Migration guidance
+------------------
+
+If your Dag logic needs the user-specified date for a manual run, use
+``logical_date`` explicitly.
+
+.. code-block:: python
+
+ from airflow.decorators import get_current_context, task
+
+
+ @task
+ def process_data():
+ context = get_current_context()
+ processing_date = context["logical_date"]
+ return f"Processing data for {processing_date}"
+
+Keep using ``data_interval_start`` and ``data_interval_end`` when you need the
+run's resolved interval semantics instead of the user-supplied trigger date.
+
+When upgrading from Airflow 2, review any manual-triggered workflows that read
+``data_interval_start`` or ``data_interval_end`` and confirm whether they
+really wanted the interval semantics or the requested logical date.
