From 056b8cf3969137534f6f78b02166b71dd1b02ac6 Mon Sep 17 00:00:00 2001
From: Collin McNulty <collin.mcnulty@gmail.com>
Date: Thu, 30 Jun 2022 13:56:40 -0500
Subject: [PATCH] Document built in Timetables (#23099)

---
 docs/apache-airflow/concepts/timetable.rst | 61 ++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/docs/apache-airflow/concepts/timetable.rst b/docs/apache-airflow/concepts/timetable.rst
index 9898204e99f11..986213df8187f 100644
--- a/docs/apache-airflow/concepts/timetable.rst
+++ b/docs/apache-airflow/concepts/timetable.rst
@@ -48,3 +48,64 @@ the schedule. Some examples are:
 As such, Airflow allows for custom timetables to be written in plugins and used by
 DAGs. An example demonstrating a custom timetable can be found in the
 :doc:`/howto/timetable` how-to guide.
+
+Built In Timetables
+-------------------
+
+Airflow comes with several common timetables built in to cover the most common use cases. Additional timetables
+may be available in plugins.
+
+CronDataIntervalTimetable
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set schedule based on a cron expression. Can be selected by providing a string that is a valid
+cron expression to the ``schedule_interval`` parameter of a DAG as described in the :doc:`/concepts/dags` documentation.
+
+.. code-block:: python
+
+    @dag(schedule_interval="0 1 * * 3")  # At 01:00 on Wednesday.
+    def example_dag():
+        pass
+
+DeltaDataIntervalTimetable
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Schedules data intervals with a time delta. Can be selected by providing a
+:class:`datetime.timedelta` or ``dateutil.relativedelta.relativedelta`` to the ``schedule_interval`` parameter of a DAG.
+
+.. code-block:: python
+
+    @dag(schedule_interval=datetime.timedelta(minutes=30))
+    def example_dag():
+        pass
+
+EventsTimetable
+^^^^^^^^^^^^^^^
+
+Simply pass a list of ``datetime``\s for the DAG to run after. Useful for timing based on sporting
+events, planned communication campaigns, and other schedules that are arbitrary and irregular but predictable.
+
+The list of events must be finite and of reasonable size as it must be loaded every time the DAG is parsed. Optionally,
+the ``restrict_to_events`` flag can be used to force manual runs of the DAG to use the time of the most recent (or very
+first) event for the data interval, otherwise manual runs will run with a ``data_interval_start`` and
+``data_interval_end`` equal to the time at which the manual run was begun. You can also name the set of events using the
+``description`` parameter, which will be displayed in the Airflow UI.
+
+.. code-block:: python
+
+    from airflow.timetables.events import EventsTimetable
+
+
+    @dag(
+        timetable=EventsTimetable(
+            event_dates=[
+                pendulum.datetime(2022, 4, 5, 8, 27, tz="America/Chicago"),
+                pendulum.datetime(2022, 4, 17, 8, 27, tz="America/Chicago"),
+                pendulum.datetime(2022, 4, 22, 20, 50, tz="America/Chicago"),
+            ],
+            description="My Team's Baseball Games",
+            restrict_to_events=False,
+        ),
+    )
+    def example_dag():
+        pass