Catchup and backfill behavior in Apache Airflow - Commands & Configuration

Introduction

Airflow schedules tasks to run at specific times. Sometimes, tasks miss their scheduled runs. Catchup and backfill help run those missed tasks so your data stays complete and up to date.

When your Airflow scheduler was down and missed running tasks on their scheduled dates.

When you add a new DAG with a start date in the past and want to run all missed tasks since then.

When you want to rerun tasks for past dates to fix data or update reports.

When you want to control whether Airflow automatically runs missed tasks or not.

When you want to manually trigger runs for specific past dates.

Config File - example_dag.py

example_dag.py

from airflow import DAG
from airflow.operators.bash import BashOperator
from datetime import datetime, timedelta

with DAG(
    dag_id='example_catchup_backfill',
    start_date=datetime(2024, 6, 1),
    schedule_interval='@daily',
    catchup=True,
    max_active_runs=1
) as dag:

    task1 = BashOperator(
        task_id='print_date',
        bash_command='date'
    )

dag_id: The unique name of the workflow.

start_date: When the DAG starts scheduling tasks.

schedule_interval: How often the DAG runs (daily here).

catchup: If True, Airflow runs all missed tasks since start_date.

max_active_runs: Limits how many DAG runs can run at the same time.

task1: A simple task that prints the current date.

Commands

Lists all DAGs available in Airflow to confirm your DAG is loaded.

Terminal

airflow dags list

Expected Output

example_catchup_backfill

example_other_dag

Manually triggers a DAG run for June 5, 2024, to backfill or rerun that date's tasks.

Terminal

airflow dags trigger example_catchup_backfill --run-id manual__20240605

Expected Output

Created <DagRun example_catchup_backfill @ 2024-06-05 00:00:00: manual__20240605, externally triggered: True>

→

--run-id - Sets a custom run identifier for tracking this manual run.

Runs all missed DAG runs from June 1 to June 3, 2024, to backfill data for those dates.

Terminal

airflow dags backfill example_catchup_backfill -s 2024-06-01 -e 2024-06-03

Expected Output

Running backfill for example_catchup_backfill from 2024-06-01 to 2024-06-03

[2024-06-01 00:00:00] Task print_date succeeded

[2024-06-02 00:00:00] Task print_date succeeded

[2024-06-03 00:00:00] Task print_date succeeded

Backfill done.

→

-s - Start date of backfill range.

→

-e - End date of backfill range.

Pauses the DAG to stop automatic scheduling and catchup runs.

Terminal

airflow dags pause example_catchup_backfill

Expected Output

Dag example_catchup_backfill is paused

Unpauses the DAG to resume automatic scheduling and catchup runs.

Terminal

airflow dags unpause example_catchup_backfill

Expected Output

Dag example_catchup_backfill is unpaused

Key Concept

If you remember nothing else, remember: catchup=True makes Airflow run all missed scheduled tasks since the start date automatically, while backfill lets you manually run tasks for past dates.

Common Mistakes

Setting catchup=False but expecting Airflow to run missed tasks automatically.

With catchup=False, Airflow skips all past missed runs and only runs the latest scheduled task.

Set catchup=True in the DAG if you want Airflow to run all missed tasks automatically.

Running backfill without specifying start and end dates.

Backfill needs a date range to know which past tasks to run; without it, the command fails or runs unexpected dates.

Always use -s and -e flags with airflow dags backfill to specify the exact date range.

Pausing a DAG and expecting scheduled tasks to run.

Paused DAGs do not schedule or run any tasks, including catchup or backfill.

Unpause the DAG to allow scheduled and catchup runs.

Summary

Set catchup=True in your DAG to let Airflow automatically run all missed scheduled tasks since the start date.

Use airflow dags backfill with start and end dates to manually run tasks for specific past dates.

Pause and unpause DAGs to control whether scheduled and catchup runs happen automatically.

Practice

1. What does setting catchup=True do in an Airflow DAG?

easy

A. It manually triggers DAG runs for a specific date range.

B. It disables all scheduled DAG runs.

C. It deletes all past DAG runs.

D. It runs all missed DAG runs automatically to catch up.

Solution

1. Step 1: Understand catchup parameter

   The catchup parameter controls whether Airflow runs missed DAG runs automatically.

2. Step 2: Effect of catchup=True

   When catchup=True, Airflow schedules and runs all DAG runs that were missed since the last run.

3. Final Answer:

   It runs all missed DAG runs automatically to catch up. -> Option D

4. Quick Check:

   catchup=True means run missed DAG runs [OK]

Hint: Catchup=True means Airflow fills missed runs automatically [OK]

Common Mistakes:

• Confusing catchup with manual backfill
• Thinking catchup disables scheduling
• Assuming catchup deletes runs

2. Which of the following is the correct way to disable catchup in an Airflow DAG definition?

easy

A. dag = DAG('my_dag', backfill=False)

B. dag = DAG('my_dag', catchup=True)

C. dag = DAG('my_dag', catchup=False)

D. dag = DAG('my_dag', schedule_interval=None)

Solution

1. Step 1: Identify catchup parameter usage

   The catchup parameter is used to enable or disable catchup behavior in DAGs.

2. Step 2: Disable catchup by setting catchup=False

   Setting catchup=False disables automatic running of missed DAG runs.

3. Final Answer:

   dag = DAG('my_dag', catchup=False) -> Option C

4. Quick Check:

   Disable catchup with catchup=False [OK]

Hint: Use catchup=False to stop automatic missed runs [OK]

Common Mistakes:

• Using backfill parameter instead of catchup
• Setting schedule_interval to None disables scheduling, not catchup
• Setting catchup=True enables, not disables

3. Given a DAG with start_date='2024-04-01', schedule_interval='@daily', and catchup=True, if the DAG was paused and resumed on 2024-04-05, which DAG runs will Airflow execute immediately after resuming?

medium

A. Runs for 2024-04-01 to 2024-04-05

B. Only the run for 2024-04-05

C. No runs will be executed automatically

D. Runs for 2024-04-02 to 2024-04-04 only

Solution

1. Step 1: Understand catchup=True behavior

   With catchup=True, Airflow runs all missed DAG runs from start_date to current date.

2. Step 2: Identify missed runs

   The DAG was paused from 2024-04-01 to 2024-04-04, so runs for 2024-04-01, 02, 03, 04 were missed. On resuming 2024-04-05, Airflow runs all missed plus current.

3. Final Answer:

   Runs for 2024-04-01 to 2024-04-05 -> Option A

4. Quick Check:

   Catchup runs all missed dates including current [OK]

Hint: Catchup runs all missed dates from start_date to now [OK]

Common Mistakes:

• Thinking only current date runs after resume
• Ignoring runs before resume date
• Assuming no runs run automatically after pause

4. You want to run DAG runs manually for the dates 2024-03-01 to 2024-03-05 without enabling catchup. Which command should you use?

medium

A. airflow dags backfill -s 2024-03-01 -e 2024-03-05 my_dag

B. airflow dags trigger my_dag --start-date 2024-03-01 --end-date 2024-03-05

C. airflow dags run my_dag 2024-03-01 to 2024-03-05

D. airflow dags catchup my_dag -s 2024-03-01 -e 2024-03-05

Solution

1. Step 1: Identify manual run command for date range

   The airflow dags backfill command runs DAG runs manually for a specified date range.

2. Step 2: Confirm correct syntax

   Using -s and -e flags with backfill specifies start and end dates for manual runs.

3. Final Answer:

   airflow dags backfill -s 2024-03-01 -e 2024-03-05 my_dag -> Option A

4. Quick Check:

   Backfill runs DAG manually for date range [OK]

Hint: Use airflow dags backfill with -s and -e for manual runs [OK]

Common Mistakes:

• Using trigger command with date range flags (not supported)
• Trying to use catchup command (does not exist)
• Using dags run with invalid date range syntax

5. You have a DAG with catchup=False and a start_date set to 2024-01-01. You want to run all DAG runs from 2024-01-01 to 2024-01-10 manually. What is the best approach to achieve this without enabling catchup?

hard

A. Set catchup=True and wait for Airflow to run all missed DAG runs automatically.

B. Use the backfill command for the date range 2024-01-01 to 2024-01-10.

C. Manually trigger the DAG once on 2024-01-10; Airflow will run all previous runs.

D. Change the start_date to 2024-01-10 and run the DAG normally.

Solution

1. Step 1: Understand catchup=False effect

   With catchup=False, Airflow skips running missed DAG runs automatically.

2. Step 2: Use backfill to run missed DAG runs manually

   To run missed DAG runs without enabling catchup, use the backfill command specifying the date range.

3. Final Answer:

   Use the backfill command for the date range 2024-01-01 to 2024-01-10. -> Option B

4. Quick Check:

   Backfill runs missed DAG runs manually without catchup [OK]

Hint: Backfill runs missed DAG runs manually when catchup is off [OK]

Common Mistakes:

• Enabling catchup when not desired
• Assuming one trigger runs all missed dates
• Changing start_date to skip missed runs