Hi TP, Thank you for the clarification! I think that everything you just said provides more reasons to make the code use it consistently as an identifier and remove it from the scheduler query. A good side effect that I noticed only after testing, is that by replacing the *logical_date* with the *run_after* in the query, the task allocation gets more fair without causing a performance decrease.
The main concern is that it introduces behavioral changes in the task ordering. Please take a look at the PR https://github.com/apache/airflow/pull/76489 and let me know what you think. Christos On Mon, Nov 16, 2026 at 4:09 PM Tzu-ping Chung via dev < [email protected]> wrote: > 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] > >
