uranusjr commented on a change in pull request #21433:
URL: https://github.com/apache/airflow/pull/21433#discussion_r808587498
##########
File path: docs/apache-airflow/concepts/dags.rst
##########
@@ -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.
+When the DAG run starts, it will have the start date and end date. This period
+describes the time when the DAG run 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 for the
+DAG run to be scheduled or triggered to run. 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.
Review comment:
```suggestion
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.
```
Double backticks are for code, not emphasis. (same applies for other parts
below that use backticks)
Also, perhaps it’s better to use present tense here? I feel future tense
hints that this time is toward the _end_ of the data interval, which is not
always the case. (Or maybe let’s remove the “which describes” part altogether?
The most important takeaway here is that “logical date” is abstract and have
multiple meanings, and everything else can be potentially misleading and dilute
the thing we want to get across.)
##########
File path: docs/apache-airflow/concepts/dags.rst
##########
@@ -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.
+When the DAG run starts, it will have the start date and end date. This period
+describes the time when the DAG run actually 'ran.' Aside from the DAG
Review comment:
The DAG run does not have an end date until after it _finishes_, not
when it starts. So the wording here probably needs to be tweaked slightly to
avoid confusion.
##########
File path: docs/apache-airflow/concepts/dags.rst
##########
@@ -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.
+When the DAG run starts, it will have the start date and end date. This period
+describes the time when the DAG run 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 for the
+DAG run to be scheduled or triggered to run. 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, when the DAG run is being triggered, the 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 scheduled, with certain
+schedule interval put in place, this 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.
Review comment:
```suggestion
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.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
