This is an automated email from the ASF dual-hosted git repository.
jedcunningham pushed a commit to branch v2-2-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 56d82fc3483f500d7a1da36019888849e8784c12
Author: Howard Yoo <32691630+howard...@users.noreply.github.com>
AuthorDate: Thu Feb 17 14:01:58 2022 -0600
added explaining concept of logical date in DAG run docs (#21433)
(cherry picked from commit 752d53860e636ead2be7c3f2044b9b312ba86b95)
---
docs/apache-airflow/concepts/dags.rst | 16 ++++++++++++++++
docs/apache-airflow/dag-run.rst | 2 ++
docs/apache-airflow/faq.rst | 7 +++++++
3 files changed, 25 insertions(+)
diff --git a/docs/apache-airflow/concepts/dags.rst
b/docs/apache-airflow/concepts/dags.rst
index 3edaf35..e339abe 100644
--- a/docs/apache-airflow/concepts/dags.rst
+++ b/docs/apache-airflow/concepts/dags.rst
@@ -157,6 +157,8 @@ The ``schedule_interval`` argument takes any value that is
a valid `Crontab <htt
For more information on ``schedule_interval`` values, see :doc:`DAG Run
</dag-run>`.
If ``schedule_interval`` is not enough to express the DAG's schedule, see
:doc:`Timetables </howto/timetable>`.
+ For more information on ``logical date``, see :ref:`data-interval` and
+ :ref:`faq:what-does-execution-date-mean`.
Every time you run a DAG, you are creating a new instance of that DAG which
Airflow calls a :doc:`DAG Run </dag-run>`. DAG Runs can run in parallel for the
@@ -177,6 +179,20 @@ In much the same way a DAG instantiates into a DAG Run
every time it's run,
Tasks specified inside a DAG are also instantiated into
:ref:`Task Instances <concepts:task-instances>` along with it.
+A DAG run will have a start date when it starts, and end date when it ends.
+This period describes the time when the DAG actually 'ran.' Aside from the DAG
+run's start and end date, there is another date called *logical date*
+(formally known as execution date), which describes the intended time a
+DAG run is scheduled or triggered. The reason why this is called
+*logical* is because of the abstract nature of it having multiple meanings,
+depending on the context of the DAG run itself.
+
+For example, if a DAG run is manually triggered by the user, its logical date
would be the
+date and time of which the DAG run was triggered, and the value should be equal
+to DAG run's start date. However, when the DAG is being automatically
scheduled, with certain
+schedule interval put in place, the logical date is going to indicate the time
+at which it marks the start of the data interval, where the DAG run's start
+date would then be the logical date + scheduled interval.
DAG Assignment
--------------
diff --git a/docs/apache-airflow/dag-run.rst b/docs/apache-airflow/dag-run.rst
index 90bb404..62555b1 100644
--- a/docs/apache-airflow/dag-run.rst
+++ b/docs/apache-airflow/dag-run.rst
@@ -84,6 +84,8 @@ scheduled one interval after ``start_date``.
If ``schedule_interval`` is not enough to express your DAG's schedule,
logical date, or data interval, see :doc:`/concepts/timetable`.
+ For more information on ``logical date``, see :ref:`concepts:dag-run` and
+ :ref:`faq:what-does-execution-date-mean`
Re-run DAG
''''''''''
diff --git a/docs/apache-airflow/faq.rst b/docs/apache-airflow/faq.rst
index 857e685..7f72a0d 100644
--- a/docs/apache-airflow/faq.rst
+++ b/docs/apache-airflow/faq.rst
@@ -214,6 +214,8 @@ This allows for a backfill on tasks that have
``depends_on_past=True`` to
actually start. If this were not the case, the backfill just would not start.
+.. _faq:what-does-execution-date-mean:
+
What does ``execution_date`` mean?
----------------------------------
@@ -248,6 +250,11 @@ misunderstandings.
Note that ``ds`` (the YYYY-MM-DD form of ``data_interval_start``) refers to
*date* ***string***, not *date* ***start*** as may be confusing to some.
+.. tip::
+
+ For more information on ``logical date``, see :ref:`data-interval` and
+ :ref:`concepts:dag-run`.
+
How to create DAGs dynamically?
-------------------------------
