In dbt, what do dbt docs generate and dbt docs serve produce?

## The two artifacts `dbt docs generate` produces two JSON files in `target/`: - **`manifest.json`** — the full compiled representation of the project: every model, snapshot, seed, source, test, exposure and macro, with its config, its compiled SQL, its descriptions, and the dependency edges between them. It is produced by any compiling command, not only docs generate, and it is the file that powers state comparison (`--state`, `state:modified+`) in CI as well as the docs site. - **`catalog.json`** — built by actually querying the warehouse. dbt asks the information schema (or the platform's equivalent metadata views) for the columns, data types and, where available, table statistics of the relations in your project. This is why the command needs a live warehouse connection and why the catalog reflects what physically exists, not what your YAML claims exists. Comparing the two is what powers the site's ability to show you a column that exists in the warehouse but is undocumented, or a documented column that no longer exists. ## The site `dbt docs serve` starts a small local web server on a local port and opens the static site: `index.html` bundled with dbt, reading those two JSON files. What you get per node is the description, the columns with their types and descriptions, the tests attached to each column, the raw and compiled SQL, and the upstream/downstream dependencies. The lineage graph is the part people actually use — a clickable DAG you can filter with dbt's own selection syntax to answer "what breaks if I change this staging model?". Because it is static files, the normal production pattern is to run `dbt docs generate` in CI after a successful build and publish `target/index.html`, `manifest.json` and `catalog.json` to any static host or internal site. Analysts get a link; nobody installs dbt. ## Where the text comes from Descriptions live in the same YAML as tests: ```yaml models: - name: fct_orders description: One row per completed order, excluding test accounts columns: - name: status description: '{{ doc("order_status") }}' ``` For anything longer than a line, or any text repeated across models, use a **docs block**. Create a Markdown file anywhere under the models path: ```markdown {% docs order_status %} The lifecycle state of an order. | value | meaning | |-------|---------| | placed | created but not fulfilled | | shipped | handed to the carrier | | returned | received back | {% enddocs %} ``` and reference it with `{{ doc('order_status') }}`. The Markdown renders on the docs site, and defining the enumeration once means the seven models carrying a `status` column cannot drift apart. ## persist_docs Docs that live only in a dbt site are invisible to someone browsing the warehouse in a SQL client or a BI tool. `persist_docs` fixes that by pushing your descriptions into the warehouse's own table and column comments: ```yaml models: +persist_docs: relation: true columns: true ``` After that, `COMMENT ON` statements accompany the model build, and the description surfaces wherever the platform's metadata surfaces — including many BI tools and catalog products that read it. Support varies by adapter, and it adds statements to each build, but for a team whose analysts live in the warehouse UI it is the highest-leverage documentation config in dbt. ## Exposures and the boundary of the graph One more docs-relevant object: an **exposure**, declared in YAML, represents a downstream consumer — a dashboard, an ML model, an application — with its owner and the models it depends on. Exposures appear in the lineage graph and are selectable (`dbt build --select +exposure:weekly_kpis`), which turns "which dashboards break if this model changes" from tribal knowledge into a query. ## Honest limits dbt docs describes *your dbt project*. It does not discover tables dbt does not manage, it has no notion of who queried what, and the descriptions are only as current as the pull requests that touch them. It is a project catalog with lineage, not an enterprise data catalog, and a candidate who says that plainly — while also saying that a generated, version-controlled, review-gated catalog beats a hand-maintained wiki that is wrong within a month — is giving the answer an interviewer wants.