Lineage
The Lineage page shows an interactive dependency graph for any project in your organization. It visualizes how data flows from sources through transformations to outputs, and lets you inspect individual models and their connections.
Accessing Lineage
Navigate to Get Insights → Lineage from the main navigation. Select a project from the dropdown to load its dependency graph.
The Lineage page works with both SQLMesh and dbt projects.
How the Graph Is Built
The graph is served from a cached snapshot. On first load, dagctl checks whether a cache exists for the selected project:
- Cache exists - The graph loads immediately from the cached data.
- No cache - The page shows a "Building DAG Cache" message and triggers a background rebuild. Reload the page after a minute or two to check status.
Use the Refresh Cache button in the cache status bar to force a rebuild after model changes. The status bar also shows when the cache was last updated and how long extraction took.
Warning
The graph reflects the state of your project at the time the cache was last built. Changes committed after the last refresh will not appear until you rebuild the cache.
Reading the Graph
- Nodes represent individual models, sources, seeds, snapshots, and other artifacts depending on the framework.
- Edges are directed arrows showing dependency direction: source → dependent.
- Colors indicate model type. The same color scheme is used in the Catalog.
| Color | Type (SQLMesh) | Type (dbt) |
|---|---|---|
| Blue | VIEW | MODEL |
| Emerald | TABLE | - |
| Amber | SEED | - |
| Violet | INCREMENTAL | - |
| Purple | INCREMENTAL_BY_TIME_RANGE | - |
| Fuchsia | INCREMENTAL_BY_UNIQUE_KEY | - |
| Cyan | FULL | - |
| Pink | SCD_TYPE_2 | SNAPSHOT |
| Sky | EXTERNAL | SOURCE |
| Gray | - | TEST |
| Teal | - | EXPOSURE |
The graph layout flows left to right. Upstream models (dependencies) appear to the left; downstream models (dependents) appear to the right.
Circular Dependencies
If the graph contains a cycle, an alert appears at the top of the page. Cycle edges are highlighted in red with dashed lines and labeled with a warning. Circular dependencies will cause issues with execution ordering and should be resolved in your project code.
Filtering
Use the filter bar above the graph to narrow the view:
| Filter | Behavior |
|---|---|
| Select Model | Picks a specific model from a searchable dropdown and centers the graph on it |
| Include dependencies | When a model is selected, also show all upstream and downstream nodes |
| Model Types | Limit the graph to one or more model kinds |
| Tags | Limit the graph to models with specific tags (when tags are defined) |
Clear all filters to return to the full graph.
Large Projects
Projects with more than 100 models do not render the full graph on initial load. The page instead shows filter controls and a summary. Apply a model name or type filter first, then click Apply Filters to load the relevant subgraph. This prevents browser performance issues with very large DAGs.
Interactive Controls
The graph canvas supports:
- Pan - Click and drag the canvas background.
- Zoom - Scroll wheel or pinch gesture. Zoom controls are also in the bottom-left corner.
- Click node - Opens model details inline below the graph in the data view table.
- Minimap - Bottom-right corner shows a minimap of the full graph for orientation.
Data View
Below the graph, a tabbed table shows the same data in structured form:
- Models tab - Sortable, searchable table of all visible models with name, type, tags, and description. Click a row to expand it and see columns, owner, dialect, and other metadata.
- Dependencies tab - A flat list of all edges in the current view, showing source model and target model.
Key Takeaways
- ✅ Select a project from the dropdown to load its lineage graph
- ✅ The graph is cached - use the Refresh Cache button after deploying model changes
- ✅ Projects over 100 models require filters before the graph renders
- ✅ Circular dependencies are detected and highlighted automatically
- ✅ Click any node or table row to see model metadata including columns and tags
- ✅ Works with both SQLMesh and dbt projects