DAGs
Purpose and Scope
A DAG, or Directed Acyclic Graph, is Airflow’s primary workflow definition. “Directed” means dependencies point from one task to another, “acyclic” means the dependency graph cannot loop back on itself, and “graph” means Airflow treats the workflow as connected units of work rather than as a single script. In user-facing terms, a DAG is the thing authors create, schedule, pause, inspect, and troubleshoot. The official documentation frames DAGs as a core concept alongside DAG runs, tasks, operators, sensors, TaskFlow, XComs, variables, and params, so understanding DAGs is the entry point for both authoring and operating Airflow workflows.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts, airflow-core/src/airflow/ui/src/components/SearchDags/index.ts
This page focuses on the conceptual model and the repository surfaces that present DAGs to users. The supplied source paths are UI and documentation-support entry points: the DAG list page, filters, search button, favorites dashboard widget, and the documentation architecture diagram generator. They do not define the scheduler or parser internals, but they show that DAGs are treated as first-class navigable objects in the Airflow UI and first-class topics in the published documentation site. Read this page before deeper pages on scheduling, dynamic task mapping, DAG file processing, and serialization.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/DagsFilters/index.ts, airflow-core/src/airflow/ui/src/pages/Dashboard/FavoriteDags/index.ts, docs/images/documentation_architecture.py
Core Workflow Model
A DAG definition describes tasks and the dependencies between them. A task is an executable unit, commonly produced by an operator, sensor, or TaskFlow-decorated Python function. Dependencies define ordering: for example, extraction can run before transformation, and transformation can run before loading. The DAG itself is not one execution; it is the reusable workflow definition that Airflow can schedule repeatedly. A DAG author therefore separates structure from execution: the Python file declares what should happen, while Airflow components decide when individual runs and task instances should be created and advanced.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts
A DAG run is one scheduled or manually triggered execution of a DAG for a specific logical date or data interval. This distinction matters operationally because the same DAG can have many DAG runs, and each DAG run can contain task instances in different states. The DAG list is the user’s inventory of definitions, while graph and grid views are used to inspect the state and relationships of particular runs and tasks. The repository UI entry point DagsList reflects that the Airflow web experience starts from a collection of DAG definitions before drilling into details.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts
Airflow’s graph-oriented model is intentionally different from a plain cron job. A cron job usually launches one command; a DAG expresses a dependency-aware workflow that can branch, wait, retry, skip, and expose status at task granularity. That model enables Airflow to show not only whether a workflow succeeded, but which task is running, failed, skipped, queued, deferred, or waiting on upstream work. The official documentation groups DAG visualization topics such as TaskGroups and edge labels under DAGs because visualization is a practical part of understanding and maintaining dependency structure.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts, airflow-core/src/airflow/ui/src/components/SearchDags/index.ts
DAG Discovery in the UI
The DAG list is the top-level UI surface for finding workflow definitions. The source entry point airflow-core/src/airflow/ui/src/pages/DagsList/index.ts re-exports DagsList, making the list page available as a page-level module. In practical use, this page is where operators and DAG authors start when they need to confirm that a DAG has been loaded, check whether it is paused, inspect recent run health, or navigate to deeper task-level views. Treat the DAG list as the operational directory for the Airflow environment rather than as a static catalog.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts
Search and filtering are separate UI concerns because production Airflow installations often contain many DAGs owned by different teams. The SearchDagsButton export gives the UI a dedicated search action, while the DagsFilters export gives the DAG list page a composable filtering module. Together these entry points support the reader task of narrowing a large DAG inventory to the workflows that matter for an incident, deployment, ownership review, or routine monitoring session. These components also reinforce an important modeling point: DAG identity and metadata are intended to be discoverable at runtime.
Sources: airflow-core/src/airflow/ui/src/components/SearchDags/index.ts, airflow-core/src/airflow/ui/src/pages/DagsList/DagsFilters/index.ts
Favorites are another operational affordance layered on top of the same DAG inventory. The FavoriteDags dashboard entry point indicates that the UI can promote selected DAGs into a focused dashboard view. This is useful when an operator repeatedly watches a small set of business-critical workflows, or when a developer is iterating on a DAG and wants quick access to its latest runs. Favoriting does not change the DAG definition or schedule; it changes navigation priority for the human user inspecting the environment.
Sources: airflow-core/src/airflow/ui/src/pages/Dashboard/FavoriteDags/index.ts
Graph, Grid, and Run Inspection
Graph and grid views answer different questions about the same workflow. A graph view emphasizes dependency shape: which tasks exist, how they are ordered, where TaskGroups collapse related work, and which edges carry labels or semantic meaning. A grid-style run view emphasizes time and state: which DAG runs exist, which task instances are healthy or failed, and how current behavior compares with previous executions. The official DAG documentation places visualization near DAG authoring topics because a workflow is easier to reason about when its declared dependency structure can be inspected visually.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts
When troubleshooting, start broad and then narrow. First, find the DAG from the list, search, filter, or favorites dashboard. Next, open the DAG and choose the view that matches the question: graph for dependency structure, grid for run history and task-state comparison, and task detail views for logs or retries. This flow mirrors Airflow’s separation between definition, run, and task instance. The visible UI modules in this source set represent the discovery layer that precedes detailed runtime inspection.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts, airflow-core/src/airflow/ui/src/components/SearchDags/index.ts, airflow-core/src/airflow/ui/src/pages/DagsList/DagsFilters/index.ts, airflow-core/src/airflow/ui/src/pages/Dashboard/FavoriteDags/index.ts
Relevant Source Files
docs/images/documentation_architecture.py- Generates the documentation architecture diagram and shows how Airflow package documentation is published from the repository into the live documentation site.airflow-core/src/airflow/ui/src/components/SearchDags/index.ts- Re-exportsSearchDagsButton, the UI entry point for DAG search behavior.airflow-core/src/airflow/ui/src/pages/DagsList/DagsFilters/index.ts- Re-exportsDagsFilters, the filtering component used around the DAG list experience.airflow-core/src/airflow/ui/src/pages/DagsList/index.ts- Re-exportsDagsList, the page-level UI module for browsing DAG definitions.airflow-core/src/airflow/ui/src/pages/Dashboard/FavoriteDags/index.ts- Re-exportsFavoriteDags, the dashboard surface for user-selected DAG shortcuts.
System-to-Code Mapping
| Concept | Repository surface | What it tells you |
|---|---|---|
| DAG inventory | airflow-core/src/airflow/ui/src/pages/DagsList/index.ts | DAGs are exposed as a page-level collection that users browse before drilling into runs and tasks. |
| DAG search | airflow-core/src/airflow/ui/src/components/SearchDags/index.ts | The UI has a dedicated search control for finding DAGs by user-facing identity. |
| DAG filters | airflow-core/src/airflow/ui/src/pages/DagsList/DagsFilters/index.ts | Filtering is a separate concern from listing, which helps large environments remain navigable. |
| Favorite DAGs | airflow-core/src/airflow/ui/src/pages/Dashboard/FavoriteDags/index.ts | Frequently monitored DAGs can be promoted into the dashboard workflow. |
| Published docs | docs/images/documentation_architecture.py | DAG documentation is part of the repository-to-site documentation publishing flow. |
Practical Authoring and Operations Flow
A useful DAG workflow starts with a clear dependency model. Define the tasks, decide which tasks must wait for others, and avoid cycles by ensuring no downstream task points back to an upstream task. Then decide how the DAG should be scheduled or triggered and what runtime values it needs. After deployment, use the DAG list to verify discovery, use search or filters to locate it quickly, and use graph or grid views to validate behavior. If the DAG does not appear where expected, the next page to read is DAG file processing.
Sources: airflow-core/src/airflow/ui/src/pages/DagsList/index.ts, airflow-core/src/airflow/ui/src/pages/DagsList/DagsFilters/index.ts
For day-two operations, think in layers. The DAG definition layer answers “what workflow did we declare?” The DAG run layer answers “which scheduled or manual execution are we inspecting?” The task instance layer answers “which unit of work is currently responsible for success or failure?” Airflow’s UI entry points help the user move through those layers: dashboard favorites for quick access, list and filters for discovery, and detailed DAG pages for visualization and run inspection. Keeping those layers distinct makes troubleshooting more systematic and avoids confusing a broken run with a broken definition.
Sources: airflow-core/src/airflow/ui/src/pages/Dashboard/FavoriteDags/index.ts, airflow-core/src/airflow/ui/src/components/SearchDags/index.ts
Next Steps
After this page, read tutorial-fundamentals for a guided introduction to the workflow lifecycle, tasks-operators-and-hooks for the units that make up a DAG, scheduling-cron-timetables-and-timezones for run creation, and dag-file-processing for how Airflow discovers Python DAG files. If your concern is deployment or UI observability, continue to dag-bundles-and-serialization, scheduler, and task-logs. Those pages build on the same distinction used here: DAG definitions are authored once, DAG runs are created over time, and task instances are the concrete work Airflow executes and observes.
Sources: docs/images/documentation_architecture.py, airflow-core/src/airflow/ui/src/pages/DagsList/index.ts