manipatnam commented on code in PR #64162:
URL: https://github.com/apache/airflow/pull/64162#discussion_r3578421162
##########
airflow-core/docs/authoring-and-scheduling/timetable.rst:
##########
@@ -151,6 +151,63 @@ must be a :class:`datetime.timedelta` or
``dateutil.relativedelta.relativedelta`
def example_dag():
pass
+.. versionadded:: 3.0.0
+ The ``run_immediately`` argument was introduced in Airflow 3.
+
+The optional ``run_immediately`` argument controls which cron point is
scheduled when a Dag is first
+enabled or re-enabled after a pause. It has no effect when ``catchup=True``
(in that case the
+scheduler always continues from where it left off).
+
+* ``run_immediately=True`` *(default)* — schedule the **most recent past**
cron point immediately.
+* ``run_immediately=False`` — skip the past cron point and wait for the **next
future** cron point.
+* ``run_immediately=timedelta(...)`` — schedule the most recent past cron
point only if it fired
+ within the given window; otherwise wait for the **next future** cron point.
+
+.. code-block:: python
+
+ from datetime import datetime, timedelta
+
+ from airflow.timetables.trigger import CronTriggerTimetable
+
+
+ @dag(
+ # Runs every 10 minutes.
+ # run_immediately=False: always skip the most recent past slot and wait
+ # for the next 10-minute boundary.
+ schedule=CronTriggerTimetable(
+ "*/10 * * * *",
+ timezone="UTC",
+ run_immediately=False,
+ ),
+ start_date=datetime(2024, 1, 1),
+ catchup=False,
+ ...,
+ )
+ def example_dag():
+ pass
+
+
+ @dag(
+ # Runs hourly.
+ # run_immediately=timedelta(minutes=10): run the most recent past slot
+ # only if it fired within the last 10 minutes; otherwise wait for next.
+ schedule=CronTriggerTimetable(
+ "0 * * * *",
+ timezone="UTC",
+ run_immediately=timedelta(minutes=10),
+ ),
+ start_date=datetime(2024, 1, 1),
+ catchup=False,
+ ...,
+ )
+ def example_dag_with_buffer():
+ pass
+
+.. note::
+
+ ``run_immediately`` is a parameter of ``CronTriggerTimetable``, **not** of
the ``DAG``
+ constructor. Passing it directly to ``DAG(run_immediately=...)`` has no
effect.
Review Comment:
Thanks for highlighting that the earlier wording was wrong. I have corrected
it.
--
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]
