dbt persist_docs for Warehouse Comments

persist_docs pushes dbt YAML descriptions directly into the warehouse as native table and column comments, making documentation visible in SQL clients, BI tool schema browsers, and data catalogs — wherever analysts already query the warehouse — without requiring a visit to the dbt docs site.

Configuration

Enable it in dbt_project.yml at the project level or per-directory:

models:
  my_project:
    +persist_docs:
      relation: true
      columns: true

• relation: true pushes model-level descriptions as table comments
• columns: true pushes column-level descriptions as column comments

You can scope this to specific layers if you only want mart models documented in the warehouse:

models:
  my_project:
    marts:
      +persist_docs:
        relation: true
        columns: true

Or set it per-model in the model’s config block:

{{ config(
    persist_docs={"relation": true, "columns": true}
) }}

How It Works

When dbt runs a model with persist_docs enabled, it issues COMMENT ON TABLE and COMMENT ON COLUMN statements (or their platform equivalent) after materializing the model. The descriptions come from your schema YAML — either inline text or resolved {{ doc() }} references.

Key behaviors:

• Doc blocks get fully resolved. If your YAML says description: "{{ doc('customer_id') }}", the warehouse comment contains the expanded text from the doc block, not the Jinja reference.
• Markdown is stripped. Headers, bold, tables, links — all Markdown formatting is removed. The warehouse comment is plain text. Write descriptions that read well without formatting if you are using persist_docs.
• Comments persist across runs. Once a comment is set, it stays until overwritten by a subsequent dbt run. Removing a description from YAML does not remove the comment from the warehouse.
• Incremental models re-apply comments. Even on incremental runs that only insert new rows, dbt re-applies the table and column comments.

Platform Support

persist_docs works on all major warehouse platforms:

Where persist_docs Pays Off

The value is highest for teams where business users query the warehouse directly. An analyst running DESCRIBE TABLE or INFORMATION_SCHEMA queries in BigQuery sees your carefully written descriptions right there in the schema. No separate docs site needed. Data catalogs that read warehouse metadata (Dataplex, Alation, Atlan, Select Star) also pick up these comments automatically.

The dbt docs site requires someone to actively visit it. Warehouse comments appear passively — in SQL clients, BI tool schema browsers, and catalog search results — for anyone querying the warehouse. See dbt documentation patterns for broader context.

Pairing with Doc Blocks

persist_docs and doc blocks work together naturally. Write your descriptions as doc blocks for single-source-of-truth reuse across models, and enable persist_docs to push those same descriptions into the warehouse. The combination gives you:

1. One place to update each description (the doc block)
2. Consistent descriptions across all models that reference the same doc block
3. Warehouse-native visibility without requiring anyone to visit the docs site

For mart models — the layer business users query directly — this combination is most impactful. CI enforcement ensures descriptions exist before models reach production.

Limitations

• No Markdown rendering. As mentioned above, all formatting is stripped. If your doc blocks rely heavily on tables or structured formatting, the warehouse comments will be less readable than the docs site version.
• No removal. Deleting a description from YAML does not delete the warehouse comment. You need to manually run a COMMENT ON ... IS NULL statement or recreate the table.
• Performance overhead. Each column comment is a separate DDL statement. On a model with 100+ columns, the comment application adds noticeable time to the run. This is usually acceptable for mart models but may matter for high-frequency incremental runs.
• Views behave differently. On some platforms, column comments on views are not persisted or are lost when the view is recreated. Tables and materialized views are more reliable.