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
>

Reply via email to