From what I remember: The first text is meant to scare users off using logical_date as much as possible since traditionally people had all kind of incorrect assumptions toward the value (carried over from Airflow 2 execution_date).
There’s no single concept to the field. It is what it is out of an (arguably) incorrect initial design decision made at the Airflow’s conception, years of further incorrect understanding from both users and maintainers that assign incorrect values to the field out of incorrect expectations, and finally, with AIP-39 and later Airflow 3, set at what it is out of compatibility concerns. People who have used the field (since execution_date) can continue to use the field and trust the code to not break with Airflow upgrades. If you are looking into what field to use for your new code, the only correct way to treat logical date is to pretend it does not exist. You don’t need to understand it (unless you want to become a maintainer of Airflow’s scheduling logic), and understanding it has no value to whatever you want to do as a dag/task author. As a maintainer of Airflow, you should treat logical date exactly as described in the second text you mention: an identifier(-ish, because it’s not even unique) value to a scheduled dag run. For new logic, just set it to a convenient value that works. Airflow does not care (other than rendering it as a part of the dag run id in the default format, and showing it in a few places in the UI). Don’t think too hard. It is a corpse that’s been buried, and should stay buried. If anything, try to pile more dirt over it. Do not dig. TP > On 16 Nov 2026, at 21:39, Christos Bisias <[email protected]> wrote: > > Hello, > > Bumping this. Any thoughts on the topic? > > Christos > > On Wed, Nov 4, 2026 at 9:22 PM Christos Bisias <[email protected]> > wrote: > >> Hello everyone, >> >> I've been looking into the *logical_date* and it seems that there are >> some inconsistencies in the documentation. In particular, >> >> >> https://airflow.apache.org/docs/apache-airflow/stable/templates-ref.html#variables >> >> *"This value does not contain any semantics, but is simply a value for >> identification."* >> >> >> https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html#running-dags >> >> *"there is another date called logical date (formally known as execution >> date), which describes the intended time a Dag run is scheduled or >> triggered."* >> >> One says that it's just an identifier while the other indicates that it's >> the intended start time. >> >> I looked at the code to get a better understanding of the field and I also >> tried to track down all the changes in the commit history since AIP-39 >> that introduced the *data_interval* and the *Timetable* interface. >> >> The concept doesn't become clear from the code either. It seems that the >> *logical_date* hasn't been updated entirely and some of the current >> behavior is derived from the old functionality from when it was still named >> *execution_date*. >> >> The *logical_date* is supposed to be an identifier for Dag runs and for >> scheduled runs it’s tied to the *data_interval_start*. The *data_interval* >> shows what date we are processing. Let’s say that we have 2 scenarios >> with a custom timetable or a manual trigger: >> >> >> 1. A Dag run starts today morning and it's supposed to be doing prep >> work for tomorrow. The user wants the *data_interval* and the >> *logical_date* to be tomorrow >> 2. A Dag run starts today morning and it's supposed to be doing >> processing for yesterday. The user wants the *data_interval* and the >> *logical_date* to be yesterday >> >> >> Case 2 works while for case 1, the Dag starts running and then the >> scheduler logs an error *"Logical date is in future: "* until the future >> date arrives. There used to be an option to allow a *logical_date* >> to point to the future but it was removed. >> >> The *run_after* field points at “when this should start”, and the >> scheduler already uses that to make sure that a Dag run isn't in the >> future. Therefore, the *logical_date* future restriction, which seems to >> have been a leftover from when it was still named *execution_date*, has >> become redundant and it could be removed. >> >> The scheduler still uses the *logical_date* to order the task instances >> during scheduling. If the future value constraint is removed, then >> *run_after* must be used for ordering in the scheduler, otherwise a run >> with a future logical date starts and then sorts behind every other run >> whenever slots are contended. >> >> The code changes are relatively small and so I've opened a PR but I think >> this also deserves a discussion for more visibility. >> >> PR: https://github.com/apache/airflow/pull/76489 >> >> The patch doesn't change how *logical_date* is derived. Furthermore, >> future logical dates will start only after the *run_after* time. >> >> Please let me know what you think. Thanks! >> >> Christos >> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
