dsuhinin opened a new pull request, #67329:
URL: https://github.com/apache/airflow/pull/67329
### Motivation
Airflow's `logical_date` was designed as a scheduling identifier, not as a
semantic "what date are we processing?" signal. In practice, teams often need
to tell a task *"process data for 2025-03-31"* independently of when the run
was scheduled. The common workaround — storing a date in `dag_run.conf` —
has no first-class template variable, no API surface, and no schema validation.
`target_date` fills this gap.
---
### What this PR adds
#### Dag-level `target_date`
Set a fixed date or a callable on the `DAG` object:
```python
from datetime import date, timedelta
from airflow.sdk import DAG
# Fixed date — every run targets 2025-03-31
with DAG("my_dag", schedule="@daily", target_date=date(2025, 3, 31)) as
dag:
...
# Callable — last day of the previous month
def last_day_of_prev_month(logical_date, data_interval_start,
data_interval_end):
return (logical_date.replace(day=1) - timedelta(days=1)).date()
with DAG("monthly_dag", schedule="@monthly",
target_date=last_day_of_prev_month) as dag:
...
Task-level override
Individual tasks can refine the Dag-level value via their own callable.
The callable receives the full template context, so ctx["target_date"]
is already the Dag-level result:
def shift_one_week(ctx):
return ctx["target_date"] - timedelta(weeks=1)
with DAG("my_dag", schedule="@weekly", target_date=last_day_of_prev_month)
as dag:
PythonOperator(
task_id="weekly_lookback",
python_callable=process,
target_date=shift_one_week,
)
Template variable {{ target_date }}
Resolution order
Nothing set anywhere → logical_date.date()
DAG-level set only → dag-level value (snapshotted on the DagRun at
creation time)
Task-level callable set → task_callable(ctx) where ctx["target_date"]
is the dag-level value
REST API
target_date is a first-class field on all DagRun endpoints:
# Trigger with an explicit processing date
curl -X POST ".../dags/my_dag/dagRuns" \
-d '{"target_date": "2025-03-31"}'
# Update after the fact
curl -X PATCH ".../dags/my_dag/dagRuns/my_run_id" \
-d '{"target_date": "2025-04-30"}'
UI
The Dag Run Details page shows a read-only Target date row when the value
is set.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
