---
title: "Definition"
source: dbt Core Documentation
source_url: https://github.com/dbt-labs/docs.getdbt.com
licence: Apache-2.0
domain: data-and-analysis
subdomain: dbt-docs
date_added: 2026-04-25
---

<Tabs
  defaultValue="models"
  values={[
    { label: 'Models', value: 'models', },
    { label: 'Sources', value:'sources', },
    { label: 'Seeds', value: 'seeds', },
    { label: 'Snapshots', value: 'snapshots', },
  ]
}>

<TabItem value="models">

<File name='dbt_project.yml'>

```yml
models:
  [<resource-path>](/reference/resource-configs/resource-path):
    +persist_docs:
      relation: true
      columns: true

```

</File>

<File name='models/<modelname>.sql'>

```sql

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

select ...

```

</File>

</TabItem>

<TabItem value="sources">

This config is not implemented for sources.

</TabItem>

<TabItem value="seeds">

<File name='dbt_project.yml'>

```yml
seeds:
  [<resource-path>](/reference/resource-configs/resource-path):
    +persist_docs:
      relation: true
      columns: true

```

</File>

</TabItem>

<TabItem value="snapshots">

<File name='dbt_project.yml'>

```yml
snapshots:
  [<resource-path>](/reference/resource-configs/resource-path):
    +persist_docs:
      relation: true
      columns: true

```

</File>

<VersionBlock firstVersion="1.9">
<File name='snapshots/snapshot_name.yml'>

```yaml

snapshots:
  - name: snapshot_name
    [config](/reference/resource-properties/config):
      persist_docs:
        relation: true
        columns: true
```

</File>
</VersionBlock>

<File name='snapshots/<filename>.sql'>

```sql
{% snapshot [snapshot_name](snapshot_name) %}

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

select ...

{% endsnapshot %}

```

</File>

</TabItem>

</Tabs>

## Definition

Optionally persist [resource descriptions](/reference/resource-properties/description) as
column and relation comments in the database. By default, documentation
persistence is disabled, but it can be enabled for specific resources or groups of
resources as needed.

## Support

The `persist_docs` config is supported on the most widely used dbt adapters:
- Postgres
- Redshift
- Snowflake
- BigQuery
- Databricks 
- Apache Spark

However, some databases limit where and how descriptions can be added to database objects. Those database adapters might not support `persist_docs`, or might offer only partial support.

Some known issues and limitations:

<WHCode>


- Column-level comments require `file_format: delta` (or another "v2 file format").


- If a column name in a SQL model is in a mixed-case format (for example, `ca_net_ht_N`), the docs for that column will not be persisted. For the docs to persist, there are two options: 

    - Define the column name in the corresponding YML file using lowercase or uppercase letters only.
    - Use the [`quote`](../resource-properties/columns.md#quoter) configuration in the corresponding YML file.

  See the following sample steps on how to use the `quote` field for columns in a mixed-case format.

    1. Create the following SQL and YML files:

        <File name='<modelname>.sql'>

            ```sql
            {{ config(materialized='table') }}

            select 1 as "ca_net_ht_N" # note the use of double quotes for the column name
            ```
        </File>

        <File name='<modelname>.yml'>

            ```yml
            models:
              - name: <modelname>
                description: This is the table description

            columns:
              - name: "ca_net_ht_N"
                description: This should be the description of the column
                quote: true
            ```
        </File>

    2. Run `dbt build -s models/<modelname>.sql --full-refresh`. 

    3. Open the logs at `logs/dbt.log` and check the column description:

        ```log
        alter table analytics.<schema>.<modelname> alter
            "ca_net_ht_N" COMMENT $$This should be the description of the column$$;
        ```


</WHCode>

## Usage

### Documenting columns and relations

Supply a [description](/reference/resource-properties/description) for a model:

<File name='models/schema.yml'>

```yml

models:
  - name: dim_customers
    description: One record per customer
    columns:
      - name: customer_id
        description: Primary key

```

</File>

Enable `persist_docs` for columns and relations in your project:

<File name='dbt_project.yml'>

```yml
models:
  +persist_docs:
    relation: true
    columns: true
```

</File>

Run dbt and observe that the created relation and columns are annotated with
your descriptions:

<Lightbox src="/img/reference/persist_docs_relation.png"
          title="Relation descriptions in BigQuery"/>

<Lightbox src="/img/reference/persist_docs_columns.png"
          title="Column descriptions in BigQuery"/>
