baolsen commented on a change in pull request #6999: [AIRFLOW-XXXX] Clarify
wait_for_downstream and execution_date
URL: https://github.com/apache/airflow/pull/6999#discussion_r362745478
##########
File path: docs/concepts.rst
##########
@@ -113,13 +116,138 @@ DAGs can be used as context managers to automatically
assign new operators to th
op.dag is dag # True
-.. _concepts-operators:
+.. _concepts:dagruns:
+
+DAG Runs
+========
+
+A DAG run is a physical instance of a DAG, containing task instances that run
for a specific ``execution_date``.
+
+A DAG run is usually created by the Airflow scheduler, but can also be created
by an external trigger.
+Multiple DAG runs may be running at once for a particular DAG, each of them
having a different ``execution_date``.
+For example, we might currently have two DAG runs that are in progress for
2016-01-01 and 2016-01-02 respectively.
+
+.. _concepts:execution_date:
+
+execution_date
+--------------
+
+The ``execution_date`` is the *logical* date and time which the DAG Run, and
its task instances, are running for.
+
+This allows task instances to process data for the desired *logical* date &
time.
+While a task_instance or DAG run might have a *physical* start date of now,
+their *logical* date might be 3 months ago because we are busy reloading
something.
+
+In the prior example the ``execution_date`` was 2016-01-01 for the first DAG
Run and 2016-01-02 for the second.
+
+A DAG run and all task instances created within it are instanced with the same
``execution_date``, so
+that logically you can think of a DAG run as simulating the DAG running all of
its tasks at some
+previous date & time specified by the ``execution_date``.
+
+.. _concepts:tasks:
+
+Tasks
Review comment:
Moved Task and Task Instance up (before Operator) as they are kind of more
high level concepts. We start off talking about workflow / dependencies /
orchestration, so rather continue with that and then dive lower into operator
details.
I feel this more clearly shows what a dependency looks like and what is
upstream/downstream.
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
