Writing Your First DAG & Reading the UI

Chapter 3 gave you the words: DAG, task, DAG run and task instance. Now you write shop_orders_daily as a real file and run it.

You will learn to:

1. Read every line of a small DAG file.
2. Run it on your machine with airflow dags test.
3. Read runs in the Grid view and time in the Gantt view.
4. Choose between clear, mark success and a new run when a task fails.

Every output in this chapter comes from a real run with Airflow 3.1.

Here is the full DAG file. @dag turns a function into a DAG, and @task turns a function into a task:

import pendulum
from airflow.sdk import dag, task


@dag(
    schedule="0 0 * * *",
    start_date=pendulum.datetime(2026, 1, 1, tz="UTC"),
    catchup=False,
    tags=["shop"],
)
def shop_orders_daily():

    @task(retries=3)
    def load_orders() -> int:
        rows = 6
        print(f"loaded {rows} orders")
        return rows

    @task
    def build_daily_revenue(rows: int) -> str:
        print(f"building revenue from {rows} orders")
        return "daily_revenue"

    build_daily_revenue(load_orders())


shop_orders_daily()

Each setting in @dag has one job:

build_daily_revenue(load_orders()) does two things. It sets the order, load first, and it passes the 6 from load_orders to build_daily_revenue.

The last line, shop_orders_daily(), creates the DAG. Without it, Airflow finds no DAG in the file, and shows no error either.

airflow dags test runs the whole DAG once, in one process on your machine, for the day you give:

airflow dags test shop_orders_daily 2026-01-21

load_orders ran first and returned 6. build_daily_revenue got the 6 and ran second. Both succeeded, so the run succeeded.

airflow tasks test runs only one task, such as load_orders. It is the fastest way to check one change.

When a DAG is missing from the UI, run airflow dags list-import-errors first. It shows files that failed to parse. If it shows nothing, check the last line of the file.

The Grid view is the main screen for a DAG. Each column is one DAG run, and each row is one task.

Each square is one task instance. Its colour shows its state (chapter 3).

Suppose that in the run about 2026-01-20, neither task succeeded. That is one failure, not two:

So read a failed column from the top, and stop at the first failed square. Read along a row when a task fails now and then: the pattern shows across many runs.

Other views answer other questions. The Graph view shows how the tasks connect. Each task instance has a Logs tab with the real error.

Airflow 3.0 left out the Gantt view, and 3.1 brought it back, next to the Grid. It shows each task instance as a bar in time.

A long bar is a task that worked for a long time. A gap between bars is time when no task of this run was running.

Suppose a run took 20 minutes, but the bars add up to 8 minutes. The other 12 minutes were waiting: for the scheduler, a free worker or a pool slot.

Faster code does not fix waiting. More workers or other limits do, as chapter 15, Concurrency, Pools, Priorities & Deferrable Operators, explains.

Before you make anything faster, find the longest bar. Making a short task twice as fast saves almost nothing.

load_orders failed in the run about 2026-01-20, and you have fixed the cause. You have four choices:

To clear a task instance is to reset it, so Airflow runs it again. Clearing only load_orders leaves build_daily_revenue as upstream_failed, so the run ends as failed again. Clear with downstream, and both run again.

A few commands cover most daily work:

dags test runs in one process on your machine, not on your workers. A passing test is a good sign, but not proof that production works (chapter 18).

From file to screen:

1. The file defines the DAG, and the last line must call the DAG function.
2. Set schedule, start_date and catchup yourself.
3. Test with airflow tasks test and airflow dags test before you deploy.
4. In the Grid, stop at the first failed square. In the Gantt, gaps mean waiting.
5. After a fix, clear the failed task with downstream.

Check yourself: your DAG is not in the UI, and list-import-errors shows nothing. What do you check? (Answer: the call to the DAG function on the last line.)