Documentation

Documentation Coverage

fct_documentation_coverage

with

models as (
    select * from {{ ref('int_all_graph_resources') }}
    where resource_type = 'model'
    and not is_excluded
),

conversion as (
    select
        resource_id,
        case when is_described then 1 else 0 end as is_described_model,
        {% for model_type in var('model_types') %}
            case when model_type = '{{ model_type }}' then 1.0 else NULL end as is_{{ model_type }}_model,
            case when is_described and model_type = '{{ model_type }}' then 1.0 else 0 end as is_described_{{ model_type }}_model{% if not loop.last %},{% endif %}
        {% endfor %}

    from models
),

final as (
    select
        {{ dbt.current_timestamp() if target.type != 'trino' else 'current_timestamp(6)' }} as measured_at,
        count(*) as total_models,
        sum(is_described_model) as documented_models,
        round(sum(is_described_model) * 100.00 / count(*), 2) as documentation_coverage_pct,
        {% for model_type in var('model_types') %}
            round(
                {{ dbt_utils.safe_divide(
                    numerator = "sum(is_described_" ~ model_type ~ "_model) * 100", 
                    denominator = "count(is_" ~ model_type ~ "_model)"
                ) }}
            , 2) as {{ model_type }}_documentation_coverage_pct{% if not loop.last %},{% endif %}
        {% endfor %}

    from models
    left join conversion
    on models.resource_id = conversion.resource_id
)

select * from final

fct_documentation_coverage (source) calculates the percent of enabled models in the project that have a configured description.

This model will raise a warn error on a dbt build or dbt test if the documentation_coverage_pct is less than 100%. You can set your own threshold by overriding the documentation_coverage_target variable. See overriding variables section.

Reason to Flag

Good documentation for your dbt models will help downstream consumers discover and understand the datasets which you curate for them. The documentation for your project includes model code, a DAG of your project, any tests you've added to a column, and more.

How to Remediate

Apply a text description in the model's .yml entry, or create a docs block in a markdown file, and use the {{ doc() }} function in the model's .yml entry.

Tip

We recommend that every model in your dbt project has at minimum a model-level description. This ensures that each model's purpose is clear to other developers and stakeholders when viewing the dbt docs site.

Undocumented Models

fct_undocumented_models (source) lists every model with no description configured.

Reason to Flag

Good documentation for your dbt models will help downstream consumers discover and understand the datasets which you curate for them. The documentation for your project includes model code, a DAG of your project, any tests you've added to a column, and more.

How to Remediate

Apply a text description in the model's .yml entry, or create a docs block in a markdown file, and use the {{ doc() }} function in the model's .yml entry.

Tip

We recommend that every model in your dbt project has at minimum a model-level description. This ensures that each model's purpose is clear to other developers and stakeholders when viewing the dbt docs site. Missing documentation should be addressed first for marts models, then for the rest of your project, to ensure that stakeholders in the organization can understand the data which is surfaced to them.

Undocumented Source Tables

fct_undocumented_source_tables (source) lists every source table with no description configured.

Reason to Flag

Good documentation for your dbt sources will help contributors to your project understand how and when data is loaded into your warehouse.

How to Remediate

Apply a text description in the table's .yml entry, or create a docs block in a markdown file, and use the {{ doc() }} function in the table's .yml entry.

sources:
  - name: my_source
    tables:
      - name: my_table
        description: This is the source table description

Undocumented Sources

fct_undocumented_sources (source) lists every source with no description configured.

Reason to Flag

Good documentation for your dbt sources will help contributors to your project understand how and when data is loaded into your warehouse.

How to Remediate

Apply a text description in the source's .yml entry, or create a docs block in a markdown file, and use the {{ doc() }} function in the source's .yml entry.

sources:
  - name: my_source
    description: This is the source description
    tables:
      - name: my_table