Atlas Catalog
A server-indexed, searchable documentation browser for every model, source, seed, snapshot, exposure, metric, macro, and analysis in your dbt project. Browse descriptions, columns, tests, lineage, compiled SQL, warehouse stats, and coverage scores - all without downloading multi-MB manifest files.
The catalog is organized into these tabs:
- Overview - your project's landing page, built from the
__overview__doc block - Browse - a searchable, filterable list of every node with a detail pane
- Graph - a full, zoomable whole-project lineage DAG
- Coverage - animated scorecards showing documentation and test coverage gaps
- Mesh - declare upstream project dependencies and see how ready your project is for dbt Mesh
- Organization - a company-wide view of every project, its public data products, and cross-project lineage
Why Atlas Catalog
| Challenge with other tools | How Atlas Catalog solves it |
|---|---|
dbt docs serve requires downloading the full manifest to the browser, which is slow for large projects | Server-indexed: only the slice you need is fetched, so browsing is instant even for 5,000+ node projects |
| Only models and sources get docs pages; exposures, metrics, and macros are invisible | All eight node types get first-class pages with type-specific detail views |
No project-level landing page unless you view the raw __overview__ block | A dedicated Overview tab renders your project's doc block as a polished landing page |
| No whole-project lineage graph without downloading and parsing the full manifest | A zoomable DAG graph is rendered server-side and viewable in both the catalog and the shared docs portal |
| Documentation coverage is invisible until someone runs a manual audit | Coverage scorecard with animated rings shows doc/test gaps at a glance, broken down by schema and type |
| Fixing documentation gaps means switching to a code editor, writing YAML, re-generating docs | One-click "Document with Atlas" sends the undocumented model to Atlas AI for instant doc generation |
| Column lineage requires separate tooling or is unavailable entirely | Column-level lineage is built into the node detail pane, computed on demand from compiled SQL |
| Docs go stale because they only reflect parse-time metadata | Warehouse-aware metadata (real types, row counts, storage, source freshness) is ingested after every run |
| Regenerating docs overwrites the previous version, so last month's documentation is gone | Every generation publishes a version you can browse, compare, and share, and nothing you already published is ever rewritten |
| Sharing docs externally requires granting platform access | Share docs via tokenized links with public, password, or SSO access gates - no login needed for recipients |
| "Who owns this?" is a Slack question, and the answer is a string in a YAML file that may name someone who left | Business and Technical owners are real members, adopted from dbt, assigned in bulk, or inherited from folder, layer, and tag rules, with an ownership score that shows the gaps |
Project Overview
The Overview tab is the landing page for your project's catalog. If your dbt project includes a {% docs __overview__ %} block, its content is rendered here as formatted markdown with any nested {{ doc() }} references already resolved.
When no overview block exists, a summary card shows your project's total entry count and doc-block count so the page is never blank.
To add an overview, create a __overview__ doc block in any of your dbt project's docs files.
Searchable Node Index
The Browse tab lists every node with type-colored indicators:
- Models, Sources, Seeds, Snapshots - your core data assets
- Exposures - dashboards, notebooks, and ML applications
- Metrics - semantic-layer metric definitions
- Macros - reusable Jinja functions with arguments and source
- Analyses - ad-hoc analytical queries
Full-text search filters the list as you type. A labeled, collapsible filter panel keeps the controls organized instead of a wall of unlabeled dropdowns, and lets you narrow the list by:
- Type (model, source, test, semantic model, and the rest)
- Schema and database
- Layer: the layers your project actually has. dbdeux reads your folder structure, so the standard staging, intermediate, and marts appear in that order, and any additional layer your team uses (reports, exports, and so on) shows up automatically instead of being lumped into "other"
- Health: healthy, caution, degraded, or unknown, each with a live count
- Documentation and test status
The stats band at the top shows totals by type with animated coverage rings. Tests and semantic models are first-class, browsable entries alongside models and sources.
Click any node to open its detail pane.
Node Detail Pane
Each node's detail view shows:
Description and Metadata
- Node description (from your YAML or schema files)
- Materialization type, schema, database, and tags
- Package name and file path
- Meta: any
metafields your team declared on the node in YAML (owner, tier, domain, and anything else you track) rendered as a readable block, so your own conventions are visible in the catalog rather than buried in a file
Long detail views are organized into collapsible sections, so you can fold away what you are not looking at and keep the parts you care about in view.
Columns
A sortable table of every column with:
| Column | Source |
|---|---|
| Name | Manifest |
| dbt type | Manifest (parse-time) |
| Warehouse type | catalog.json (actual type in the database, e.g., NUMBER(38,0)) |
| Description | Manifest |
| Tests | Inline chips showing attached generic tests (not_null, unique, etc.) |
| Position | catalog.json (ordinal position in the relation) |
Warehouse Stats
After a dbt docs generate run, the detail pane shows live warehouse metadata:
- Row count and storage size (bytes)
- Adapter-specific extras (clustering key, last modified, partitioning) displayed as label-value pairs
- These fields update automatically after every run, so your docs never go stale
Source Freshness
For source nodes, the detail pane shows:
- Last loaded at timestamp
- Freshness status (pass, warn, error) with a visual staleness indicator
- Criteria (warn-after and error-after thresholds)
- Freshness data comes from
dbt source freshnessruns and updates automatically
The catalog always overlays the latest freshness result for each source, drawn from your most recent scheduled or on-demand freshness check. You do not have to hunt for the run that produced it. Whenever a job checks source freshness, the catalog reflects the new status.
Compiled SQL
View the rendered SQL for any model, with syntax highlighting. Useful for understanding what dbt actually sends to your warehouse after resolving refs, macros, and Jinja.
Lineage
Model-level upstream and downstream dependencies are shown inline. Click any linked node to navigate to its detail view.
Exposure Details
Exposure nodes display type-specific fields:
- Type (dashboard, notebook, ML model, application)
- URL linking to the external asset
- Maturity level
- Owner name and email
- Dependent models listed as upstream lineage
Metric Details
Metric nodes show:
- Metric type and label
- Expression (the calculation formula)
- Filter conditions
- Upstream semantic model linkage
Macro Details
Macro nodes include:
- Arguments table with name, type, and description for each declared argument
- Macro source - the full Jinja body with syntax highlighting
Governance Metadata
When your project uses dbt's governance features, the detail pane surfaces them so consumers know how a model is meant to be used:
- Contract - a badge when the model declares an enforced contract, signalling that its column names and types are guaranteed
- Access - the model's access level (
public,protected, orprivate), so it is clear which models are safe for other teams to reference - Group - the owning group a model belongs to, along with the group owner, so it is clear who is responsible for a set of models
- Version - the model version, with an "outdated" indicator when a newer version exists so you can steer consumers to the latest one
- Deprecation date - a clear sunset date when a model is scheduled to be retired
These fields stay hidden for models that do not use governance, so the pane stays clean for everyone else.
Project DAG Graph
The Graph tab renders a full, zoomable whole-project lineage graph. Unlike dbt docs serve, the graph layout is computed server-side from the ingested manifest, so the browser never parses multi-MB artifacts.
Key capabilities:
- Longest-path layered layout - nodes flow left to right, grouped by dependency depth
- Zoom, pan, and minimap - navigate large graphs with standard controls
- Search - find and center any node by name
- Type-colored nodes - each node type has a distinct color matching the Browse list
- Click-to-inspect - clicking a node opens its full detail pane inline beside the graph, without navigating away
- Full transitive highlight - clicking a node highlights its entire upstream and downstream lineage, not just its direct neighbors, so you can see everything a change could touch at a glance
- Shared portal support - the same graph is available in the no-login docs portal via share links
When a project is too large, the graph shows the closest neighbors and displays a "showing N of M nodes" indicator.
Focused Lineage
Instead of taking in the whole graph at once, focus on a single node's neighborhood. Pick a node as the anchor and choose how many hops of upstream and downstream lineage to show. The graph redraws to just that neighborhood, so tracing how one model connects to its sources and consumers stays readable even in a large project. Focus mode works the same way on the authenticated graph and in the no-login docs portal.
Hide-Layer Filters
Large graphs often carry layers you do not need in a given view. Hide-layer filters let you exclude nodes by tag, file path, schema, or type so the graph shows only what is relevant. For example, hide staging models to see just marts, or hide tests to focus on data flow. You can also multi-select specific models to hide, or use Hide this model directly on a node to drop it from the view without building a filter expression. The filters apply in both Browse and Graph, and are carried into share links, so a link opens with exactly the view you curated.
Catalog Versions and History
Each time your docs are generated from an environment, whether from a scheduled job or from the editor, the catalog publishes a version of that documentation. Versions are never rewritten, so the catalog is a history you can go back through rather than a single view that the next run replaces.
The easiest way to keep this current is to let a job do it: tick Generate docs on run on any scheduled job and your documentation refreshes after each successful build. This works the same way for projects hosted by dbdeux, which have no repository, so a managed project's documentation history is just as complete.
Browse a Point in Time
Two pickers sit in the catalog header:
- Environment, which scopes the list to a single environment. Only environments that actually published documentation appear, so the list never offers you an empty choice
- Version, which is Latest (live) by default. Pick any published version to pin the whole page to it
While a version is pinned, a banner keeps it obvious what you are looking at: the version number, the environment it came from, when it was generated, and who or what generated it. Everything you do while pinned, including browsing, searching, the graph, and node details, reads from that version. Clear the pin to return to the live view.
This answers the questions a single mutable catalog cannot:
- What did this model look like before last night's release?
- When did that column change type, and who shipped it?
- What did the stakeholder actually see when we sent them the docs last quarter?
Compare Two Versions
Choose a base (older) and a head (newer) version and compare them. The summary counts what moved between the two:
- Models added, removed, and changed
- Columns added and removed, and column types changed
- Descriptions changed
- Tests added and removed
Below the summary, each affected model is listed with what changed about it, so a schema change review becomes reading a diff rather than clicking through nodes and remembering what they used to say. This is useful before announcing a breaking change, during an incident review, and for showing an auditor exactly what changed between two dates.
Pin a Share Link to a Version
When you share docs, you can pin the link to a specific version instead of the live view. Recipients keep seeing exactly that version even after your team regenerates docs, which makes a link you put in a data contract or a board pack stable. Versions that an active share link points to are never removed from history, so a pinned link cannot quietly break.
How Long History Is Kept
History is kept per project and environment according to your plan. Older versions beyond that are cleaned up automatically, with pinned versions always preserved. Your current allowance is visible under Plan & Limits in Organizations.
Model Health, Performance, and Recommendations
Each model carries an at-a-glance health verdict so you can spot trouble without opening every node:
- A colored dot marks each model healthy (green), caution (amber), degraded (red), or unknown (gray)
- The last run status is shown inline, so you know whether a model built cleanly on its most recent run
- Health counts appear in the filter panel, so you can jump straight to everything that needs attention
Open a model to see its performance history: the execution time of each recorded run, so you can see whether a model is trending slower over time and catch a regression before it becomes a problem.
Where dbdeux can suggest an improvement (for example a missing test, an absent description, or a model that has been slow across recent runs), it surfaces a recommendation on the node, turning the catalog from a passive reference into an active checklist for keeping your project healthy.
Custom References (Annotations)
Attach arbitrary metadata to any catalog node or individual column. References are user-curated attributes that live outside your git-managed schema YAML, so anyone on the team can add context without opening a pull request.
How it works
- Click Add reference on any node's detail pane to create a new label-value pair
- Pick a value type so the reference renders correctly:
- Link: a clickable URL (e.g., a Jira ticket, wiki page, or dashboard)
- Email: a click-to-mail address for the owner or on-call contact
- Date: a formatted date (e.g., a review or deprecation date)
- Code: monospace text for identifiers like a ticket key or commit SHA
- Text: plain notes
- Add free-form tags to group and categorize references
- Search and filter references by label, value, or tag to find them quickly on busy nodes
- Each reference shows its provenance: who added it and when
- References are scoped per project and tied to the node's unique identifier, so they survive manifest re-ingestion
- Column-level references work the same way: in the columns table, each column has its own "Add" control
Common uses
| Label | Type | Example value |
|---|---|---|
| Requirement Link | Link | https://jira.example.com/browse/DATA-1234 |
| Data Owner | Text | analytics-eng@company.com |
| SLA | Text | Refreshed daily by 06:00 UTC |
| PII Classification | Link | https://wiki.example.com/data-classification |
| Deprecation Notice | Text | Replaced by stg_customers_v2 after Q3 |
References are visible to anyone browsing the catalog and editable by any project member with write access. In a shared docs portal they are shown read-only alongside the node and its columns, so the context your team curated travels with the documentation you send out instead of being visible only to signed-in members.
Column-Level Lineage
For each output column of a model, Atlas Catalog traces which upstream columns it derives from. The lineage is computed on demand from the model's compiled SQL using dialect-aware parsing, so it works across all supported warehouses.
This helps with:
- PII tracking: Follow sensitive columns through your entire pipeline
- Impact analysis: Know exactly which output columns are affected when you rename or remove an upstream column
- Debugging: When a metric looks wrong, trace the specific column back to its source
If parsing is incomplete (e.g., complex dynamic SQL), partial results are shown with an "approximate" indicator rather than failing.
Owners
Every data question eventually becomes a people question: who decides what this metric means, and who do I page when this model breaks? Those are two different people, so Atlas Catalog tracks two kinds of owner on every model, source, seed, snapshot, exposure, and metric:
| Owner kind | The question they answer |
|---|---|
| Business owner | Who to ask about meaning, definitions, and business rules |
| Technical owner | Who maintains the code and fixes it when it breaks |
Owners are real members of your organization, picked from a member search by name or email, so an owner is always someone you can actually reach rather than a string in a YAML file. If an owner later leaves the organization, their assignments stay visible and are clearly marked, so you can see exactly which objects need a new home instead of discovering it during an incident.
The right owner is not always a member yet. If the person who really knows fct_revenue has never signed in to dbdeux, type their email address into the same owner picker: they are invited to the organization and pencilled in as owner in one step. Until they accept, the object shows a dashed invited chip with their address so nobody wonders whether the assignment was made, and the moment they first sign in the chip becomes a normal owner with their name. A pending owner can be cancelled from the chip, and the invitation itself is managed with everyone else's under Organizations, Members. Owner invitations grant at most the Member role; administrators are invited from the Members tab.
Three Ways an Owner Gets Assigned
Adopt from dbt. If your project already records ownership in meta (keys such as owner, business_owner, steward, technical_owner, or maintainer), in a model group's owner, or in an exposure's owner block, the catalog reads those hints, matches them to organization members by email or display name, and offers them as one-click Adopt suggestions on the object. Nothing is written until you accept, and adopted owners carry an Adopted from dbt meta marker so it is clear where they came from.
Assign by hand. Add or change owners directly on any object from its detail pane. To cover many objects at once, switch Browse into selection mode, tick the entries you want (or everything loaded), and use Assign owners to add the same people to all of them in one action. Objects that already have that person keep their existing assignment untouched.
Ownership rules. For a project with hundreds of models, naming owners one at a time does not scale, so you can give every object in a folder, a modeling layer (staging, intermediate, marts, and any other layer your project produces), or a dbt tag a default owner. Rules re-apply automatically on every new catalog version, so a model added to models/marts next week is owned the moment it lands. Owners that came from a rule show an inherited chip naming the rule that assigned them. Hand-picked owners are never overwritten by a rule, and if you remove an inherited owner from one object, the catalog remembers that choice and does not put it back. Deleting a rule removes only the owners it assigned.
Find Objects by Owner
Browse gains an owner filter: everything, mine, unowned, or a specific member. Combined with the existing layer, schema, group, and health filters, "unowned marts models" or "everything Priya owns that is degraded" is one filter combination rather than a spreadsheet exercise. Owner names also match in the search box.
Owners Everywhere the Catalog Is Read
Owners appear on the node detail pane, in Browse, in the read-only portal behind a share link (names only, never email addresses, so a public link does not leak contact details), and to a connected AI assistant when it asks about a model. Every assignment, removal, adoption, and bulk change is recorded in the Audit Log.
Owners Hear About It
In most catalogs an owner is a label: it tells you who to chase, and then you chase them yourself over chat. In dbdeux, being an owner means the catalog keeps you in the loop without anyone having to remember you exist.
Owners are told, by email and in Slack when the project has a channel set up, when one of three things happens to an object they own:
| Alert | When it fires | What it tells you |
|---|---|---|
| Owned model changed | A new catalog version is published and a model you own is different from the previous version | Which models changed, with the columns added or removed, tests added or removed, and whether the description changed, plus a link to the catalog version |
| Slimmer CI failure | A pull request build fails on a model you own, or on one of its tests | The model, the failing test or step, and the pull request, so the technical owner sees a break before it is merged |
| Questions and change requests | Someone asks a question or requests a change on an object you own | The request itself, with a link to the thread on the object |
Each person decides what they want to hear about. User Preferences gains an Owner alerts section with a switch for each of the three, so a business owner who wants questions but not build failures can say so. Test failures are attributed to the model they test, so the owner of fct_revenue hears about not_null_fct_revenue_customer_id failing without owning the test separately.
Ask a Question or Request a Change
Every catalog object has two buttons at the bottom of its detail pane: Ask a question and Request a change from the owners. Both take a one-line title and as much context as you like ("which column, which report, what you expected to see" for a question; "new column, changed logic, deprecation, tests to add" for a change), and both go straight to the object's Business and Technical owners.
The result is a Requests to owners thread that lives on the object, not in someone's inbox:
- Owners reply in the thread, and everyone who can see the object can read the answer, which turns a one-off question into documentation
- A change request moves through Open, In progress (the owner clicks Start working), and then Resolved or Declined, so the person who asked can see where it stands without following up
- Status can be changed by the requester, the object's owners, or an organization admin, and every status change and reply is recorded in the Audit Log
- If an object has no owners yet, the request is still saved on it. Nobody is alerted until owners are assigned, the thread says so plainly, and once owners exist they can pick it up from there
Compare this with the usual pattern of pasting a model name into a team channel and hoping the right person is online: the question reaches the right people by definition, the answer stays attached to the object it was about, and the coverage scorecard already tells you which objects have nobody to ask.
Coverage Scorecard
The coverage view provides animated ring charts showing your project's documentation health:
- Node documentation % - what fraction of models/sources have descriptions
- Node test % - what fraction have at least one test. Sources are excluded from test coverage, because sources are usually validated downstream and flagging every source as untested only produces noise you learn to ignore
- Column documentation % - what fraction of columns across all nodes have descriptions
- Ownership % - what fraction of objects have at least one named owner, with a business-owned and technical-owned split, a per-layer breakdown, a count of objects whose only owners have left the organization, and a plain-language recommendation for what to do next
Breakdown by Schema or Type
Below the rings, a per-slice breakdown shows dual progress bars (documentation and testing) for each schema or resource type. This makes it easy to spot which corner of your project needs attention.
Gap Lists
Drill into three categories:
- Undocumented - nodes with no description at all
- Partially documented - nodes that have descriptions but some columns lack them
- Untested - models and other data assets with zero tests. A source without tests is never treated as a problem, and a test is never itself flagged as untested
- Unowned - objects with no owner of either kind. From this tab you can open bulk assignment for the whole list, or open the ownership rules drawer to cover them with a folder, layer, or tag rule instead of naming them one by one
Each row includes a "View" link to jump to the node and a "Document with Atlas" button that sends the node to Atlas AI for one-click documentation generation.
Ask Atlas in the Catalog
Atlas is available directly inside the catalog. Open the chat panel from a node and ask questions grounded in that exact node: what a model does, where a column comes from, what depends on it, or how to document it. A visible context chip shows which node the conversation is grounded in, so you always know what Atlas is reasoning about, and it never silently answers about the wrong model. The chat is scoped to the catalog's selected project, so answers stay grounded in the project you are actually browsing.
When you use Document with Atlas on an undocumented model, it opens this in-catalog panel and generates a description without sending you to the editor. The generated documentation is written back into a shared, folder-level schema file following the dbt-standard naming convention _<directory>__models.yml (for example _netsuite__models.yml), so a folder's models are documented together in one place rather than scattering a separate YAML file next to every model.
Column names are written back exactly as your warehouse reports them. A column that is upper case or mixed case is quoted in the YAML, because an unquoted CUSTOMER_ID and a quoted "CUSTOMER_ID" are not the same thing to dbt, and getting that wrong is how documentation silently stops matching a column. When Atlas updates a file that already documents some columns, it matches existing entries whether or not they were quoted, so re-documenting a model adds what is missing instead of creating a second entry for a column you already described.
Sharing Catalog Docs
Share your project's documentation externally with stakeholders who do not have a platform account:
Access Modes
| Mode | How it works |
|---|---|
| Public | Anyone with the link can view (default) |
| Password | Viewer enters a passphrase once; only its hash is stored |
| SSO | Only signed-in members of your organization can access |
Email Sharing
After generating a link, use the built-in email composer to send it directly to stakeholders. The email includes a branded template with a direct link to the docs portal.
Docs Portal
Recipients see a read-only documentation portal with the full catalog: searchable node list, descriptions, columns, tests, lineage, and your curated references. No login required for public and password-gated links. Any focused-lineage view and hide-layer filters you set are preserved in the link, so recipients open the exact view you intended. The portal header states which environment the documentation came from, so a reader is never left guessing whether they are looking at production.
Share links resolve correctly for projects that live in a shared workspace, so a catalog you share from an organization workspace opens for its intended audience rather than failing to authorize.
How It Compares
| Capability | Atlas Catalog | dbt docs / Explorer | Other tools |
|---|---|---|---|
| Browsing speed | Instant (server-indexed, paginated) | Slow for large projects (full manifest download) | Varies |
| Node type coverage | All 8 types: models, sources, seeds, snapshots, exposures, metrics, macros, analyses | Models and sources only | Varies |
| Project overview | Rendered __overview__ doc block with resolved refs | Raw markdown block | Not available |
| Whole-project DAG | Server-rendered, zoomable, with inline detail pane | Client-rendered (downloads full manifest) | Separate tools |
| Coverage scoring | Built-in with animated scorecards and gap lists | Not available | Requires separate tooling |
| One-click doc fix | "Document with Atlas" sends to AI for instant generation | Manual YAML editing | Manual |
| Column lineage | Built-in, dialect-aware, on demand | Not available in dbt docs | Separate paid tools |
| Warehouse metadata | Row counts, storage, types, freshness - auto-updated | Requires separate dbt docs generate and manual viewing | Varies |
| External sharing | Tokenized links with public/password/SSO gates, including overview and graph | Not available | Requires platform access |
| Freshness tracking | Inline staleness indicator with pass/warn/error | Separate dbt source freshness command | Separate monitoring |
| Custom references | Attach arbitrary label-value annotations (links, text) to any node or column | Not available | |
| Ownership | Business and Technical owners who are real members, adopted from dbt meta, assigned in bulk, or inherited from folder / layer / tag rules, with an ownership coverage score and unowned list | Owner shown only if declared in meta or a group; no coverage, no rules | Usually a separate data catalog product |
| Documentation history | Every generation publishes an immutable version you can browse, compare, and pin a link to | Latest generation only, previous docs are overwritten |