Airflow - Logical Date

 

dag3 = DAG(
    dag_id="example_branch_datetime_operator_3",
    start_date=pendulum.datetime(2021, 1, 1, tz="UTC"),
    catchup=False,
    tags=["example"],
    schedule="@daily",
)
# [START howto_branch_datetime_operator_logical_date]
empty_task_13 = EmptyOperator(task_id="date_in_range", dag=dag3)
empty_task_23 = EmptyOperator(task_id="date_outside_range", dag=dag3)

cond3 = BranchDateTimeOperator(
    task_id="datetime_branch",
    use_task_logical_date=True,
    follow_task_ids_if_true=["date_in_range"],
    follow_task_ids_if_false=["date_outside_range"],
    target_upper=pendulum.datetime(2020, 10, 10, 15, 0, 0),
    target_lower=pendulum.datetime(2020, 10, 10, 14, 0, 0),
    dag=dag3,
)

# Run empty_task_13 if cond3 executes between 2020-10-10 14:00:00 and 2020-10-10 15:00:00
cond3 >> [empty_task_13, empty_task_23]
# [END howto_branch_datetime_operator_logical_date]

What does the 'use_task_logical_date=True' mean?

 

In BranchDateTimeOperator, the parameter:

use_task_logical_date=True

controls which timestamp the operator uses to evaluate the datetime condition.

---

✅ Meaning of use_task_logical_date=True

When this is True, the operator uses the task's logical date (formerly called execution_date) to compare against:

target_lower
target_upper

✔ Logical Date = The period the DAG run represents

For a daily DAG:

• A run scheduled at 2021-01-02 00:00 has logical date 2021-01-01 00:00
  (it represents the day that just finished)

So with use_task_logical_date=True, the operator evaluates:

2021-01-01 00:00 UTC ∈ [target_lower, target_upper] ?

---

❌ When use_task_logical_date=False

Then the operator uses the current actual time when it is running (wall-clock time), e.g.:

pendulum.now("UTC")

This is much less deterministic for batch pipelines, so Airflow generally recommends using logical dates.

---

📌 Summary

Setting	Operator uses	Example
use_task_logical_date=True (default for batch jobs)	The DAG run's logical date	2021-01-01 00:00
use_task_logical_date=False	The actual current runtime	2021-01-02 00:00:05, etc.

---

🔎 What it means in your DAG:

Your DAG starts 2021-01-01 with @daily.
Since catchup=False, the first run has logical date 2021-01-01 00:00.

Your targets are:

2020-10-10 14:00:00 → 2020-10-10 15:00:00

The logical date 2021-01-01 is NOT in that window, so:

→ follow_task_ids_if_false = ['date_outside_range']