Implementation:Apache Airflow Timetable Protocol

Knowledge Sources	Apache Airflow
Domains	Scheduling, Python_API
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for defining DAG scheduling strategies provided by the Airflow timetable framework.

Description

The Timetable protocol defines the interface all timetables must implement. CronDataIntervalTimetable is the most common built-in implementation, parsing cron expressions to determine data intervals. Other implementations include DeltaDataIntervalTimetable (timedelta-based), ContinuousTimetable, and EventDrivenTimetable (asset-triggered).

Usage

The timetable is set via the DAG's schedule parameter. Cron strings and timedelta objects are automatically converted to the appropriate timetable class. Custom timetables should implement the Timetable protocol and be registered as Airflow plugins.

Code Reference

Source Location

• Repository: Apache Airflow
• File: airflow-core/src/airflow/timetables/base.py
• Lines: L168-382

Signature

class Timetable(Protocol):
    description: str = ""
    periodic: bool = True
    can_be_scheduled: bool = True
    run_ordering: Sequence[str] = ("data_interval_end", "logical_date")
    active_runs_limit: int | None = None

    def serialize(self) -> dict[str, Any]: ...
    def validate(self) -> None: ...
    def next_dagrun_info(
        self,
        *,
        last_automated_data_interval: DataInterval | None,
        restriction: TimeRestriction,
    ) -> DagRunInfo | None: ...

CronDataIntervalTimetable:

class CronDataIntervalTimetable(CronMixin, _DataIntervalTimetable):
    """Timetable that schedules DAG runs based on a cron expression."""
    # Inherits from CronMixin for expression parsing
    # and _DataIntervalTimetable for interval computation

Import

from airflow.timetables.base import Timetable
from airflow.timetables.interval import CronDataIntervalTimetable

I/O Contract

Inputs

Name	Type	Required	Description
expression	str	Yes (cron)	Cron expression (5/6 fields or preset)
timezone	Timezone	Yes (cron)	Schedule timezone
last_automated_data_interval	DataInterval or None	Yes	Previous run interval
restriction	TimeRestriction	Yes	Start/end date and catchup constraints

Outputs

Name	Type	Description
DagRunInfo	DagRunInfo or None	Contains data_interval and run_after datetime
serialized	dict	JSON-serializable representation for persistence

Usage Examples

Cron-based Schedule

from airflow.sdk import DAG

# Using cron string (auto-converted to CronDataIntervalTimetable)
dag = DAG(
    dag_id="daily_etl",
    schedule="0 2 * * *",    # Every day at 2 AM
    start_date=datetime(2024, 1, 1),
)

# Using cron presets
dag = DAG(dag_id="hourly", schedule="@hourly")

Custom Timetable

from airflow.timetables.base import Timetable, DagRunInfo, DataInterval, TimeRestriction

class WorkdayTimetable(Timetable):
    """Only schedule on business days."""

    def next_dagrun_info(self, *, last_automated_data_interval, restriction):
        # Custom logic to skip weekends
        ...

Related Pages

Implements Principle

• Principle:Apache_Airflow_Scheduling_Configuration