dbt-bouncer

Columns must have a populated description.

!!! info "Rationale"

Column-level documentation is where data consumers spend most of their time: understanding what `is_active` means, whether `amount` is in cents or pounds, or which ID to join on. Without column descriptions, analysts guess, make mistakes, and create conflicting metrics. This check ensures every column is explained, which is especially valuable for data catalogues and BI tool integrations that surface these descriptions automatically.

Parameters: min_description_length (int | None): Minimum length required for the description to be considered populated.

Receives: catalog_node (CatalogNodeEntry): The CatalogNodeEntry object to check. manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: - name: check_column_description_populated include: ^models/marts yaml catalog_checks: - name: check_column_description_populated min_description_length: 25 # Setting a stricter requirement for description length

Columns that match the specified regexp pattern must have a specified test.

!!! info "Rationale"

Naming conventions communicate expectations: a column named `is_active` implies it is boolean and never null; a column ending in `_id` implies it is a valid foreign key. Without enforcement, these implicit contracts go untested, and referential integrity issues or null values can silently corrupt downstream aggregations. This check bridges naming conventions and data quality by automatically requiring specific tests on columns that match a pattern, eliminating the manual overhead of reviewing every column individually.

Parameters: column_name_pattern (str): Regex pattern to match the column name. test_name (str): Name of the test to check for.

Receives: catalog_node (CatalogNodeEntry): The CatalogNodeEntry object to check. tests (list[TestNode]): List of TestNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: - name: check_column_has_specified_test column_name_pattern: ^is_.* test_name: not_null

Columns with the specified regexp naming pattern must have data types that comply to the specified regexp pattern or list of data types.

!!! info "Rationale"

Naming conventions that encode data types (e.g. `is_` prefix for booleans, `_date` suffix for dates, `_id` suffix for integers) are a common and effective way to make schemas self-describing. Without enforcement, these conventions drift over time: a column named `is_active` might be stored as an integer in one model and a boolean in another, causing silent cast errors downstream. This check ties naming patterns to data types, catching mismatches at CI time rather than in production queries.

Note: One of type_pattern or types must be specified.

Raises: ValueError: If neither or both of type_pattern/types are supplied.

Parameters: column_name_pattern (str): Regex pattern to match the model name. type_pattern (str | None): Regex pattern to match the data types. types (list[str] | None): List of data types to check.

Receives: catalog_node (CatalogNodeEntry): The CatalogNodeEntry object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: # DATE columns must end with "_date" - name: check_column_name_complies_to_column_type column_name_pattern: .*_date$ types: - DATE yaml catalog_checks: # BOOLEAN columns must start with "is_" - name: check_column_name_complies_to_column_type column_name_pattern: ^is_.* types: - BOOLEAN yaml catalog_checks: # Columns of all types must consist of lowercase letters and underscores. Note that the specified types depend on the underlying database. - name: check_column_name_complies_to_column_type column_name_pattern: ^[a-z_]*$ types: - BIGINT - BOOLEAN - DATE - DOUBLE - INTEGER - VARCHAR yaml catalog_checks: # No STRUCT data types permitted. - name: check_column_name_complies_to_column_type column_name_pattern: ^[a-z_]*$ type_pattern: ^(?!STRUCT)

Columns must have a name that matches the supplied regex.

!!! info "Rationale"

Consistent column naming is the foundation of a readable and maintainable dbt project. Inconsistent casing, abbreviations, or special characters make SQL harder to write, cause join errors, and confuse data consumers who query the warehouse directly. A single enforced naming pattern (e.g. `^[a-z_]*$` for snake_case) eliminates an entire class of stylistic bugs and ensures that columns look the same whether viewed in dbt docs, a BI tool, or a raw SQL editor.

Parameters: column_name_pattern (str): Regexp the column name must match.

Receives: catalog_node (CatalogNodeEntry): The CatalogNodeEntry object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: - name: check_column_names column_name_pattern: [a-z_] # Lowercase only, underscores allowed

All columns in a model should be included in the model's properties file, i.e. .yml file.

!!! info "Rationale"

When a column exists in the database but is missing from the model's properties file, it cannot receive a description, a data test, or a constraint. These invisible columns accumulate over time as schemas evolve, creating gaps in data quality coverage and making it harder for consumers to discover what data is available. This check ensures the properties file stays in sync with the actual schema, giving teams a complete and testable view of every model.

Receives: case_sensitive (bool | None): Whether the column names are case sensitive or not. Necessary for adapters like dbt-snowflake where the column in catalog.json is uppercase but the column in manifest.json can be lowercase. Defaults to false for dbt-snowflake, otherwise true. catalog_node (CatalogNodeEntry): The CatalogNodeEntry object to check. manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: - name: check_columns_are_all_documented

Columns should have a populated description in public models.

!!! info "Rationale"

Public models form the stable, documented API of a dbt project — they are the models that external consumers, BI tools, and other projects are expected to query directly. Undocumented columns in a public model undermine this contract: consumers cannot tell what a field means, which ID to join on, or whether a flag is nullable. Requiring column descriptions on public models ensures the published interface is self-explanatory and trustworthy, which is especially important as teams scale and data catalogues surface model metadata automatically.

Receives: catalog_node (CatalogNodeEntry): The CatalogNodeEntry object to check. min_description_length (int | None): Minimum length required for the description to be considered populated. models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: - name: check_columns_are_documented_in_public_models

Exposures should depend on a model.

!!! info "Rationale"

Exposures document downstream consumers of dbt models — dashboards, ML models, and APIs. If an exposure references no models (or too many), it signals that the lineage metadata is incomplete or incorrect. Enforcing a model count range ensures each exposure is meaningfully connected to the data layer it represents, keeping documentation trustworthy.

Parameters: maximum_number_of_models (int | None): The maximum number of models an exposure can depend on, defaults to 100. minimum_number_of_models (int | None): The minimum number of models an exposure can depend on, defaults to 1.

Receives: exposure (ExposureNode): The ExposureNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the exposure path (i.e the .yml file where the exposure is configured). Exposure paths that match the pattern will not be checked. include (str | None): Regex pattern to match the exposure path (i.e the .yml file where the exposure is configured). Only exposure paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_exposure_based_on_model yaml manifest_checks: - name: check_exposure_based_on_model maximum_number_of_models: 3 minimum_number_of_models: 1

Exposures should be based on public models only.

!!! info "Rationale"

Public access in dbt signals that a model is stable, well-tested, and safe to depend on externally. Exposures that reference protected or private models create implicit dependencies on implementation details that may change without warning, increasing the risk of broken dashboards or pipelines when internal models are refactored.

Receives: exposure (ExposureNode): The ExposureNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the exposure path (i.e the .yml file where the exposure is configured). Exposure paths that match the pattern will not be checked. include (str | None): Regex pattern to match the exposure path (i.e the .yml file where the exposure is configured). Only exposure paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_exposure_based_on_non_public_models

Exposures should not be based on views.

!!! info "Rationale"

Views and ephemeral models recompute their SQL every time they are queried. When a BI tool or downstream application queries an exposure built on a view, it triggers a full recomputation on every refresh, which can be slow and expensive at scale. Exposures should sit on top of materialised tables to ensure consistent, performant query times for end users.

Parameters: materializations_to_include (list[str] | None): List of materializations to include in the check.

Receives: exposure (ExposureNode): The ExposureNode object to check. models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the exposure path (i.e the .yml file where the exposure is configured). Exposure paths that match the pattern will not be checked. include (str | None): Regex pattern to match the exposure path (i.e the .yml file where the exposure is configured). Only exposure paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_exposure_based_on_view yaml manifest_checks: - name: check_exposure_based_on_view materializations_to_include: - ephemeral - my_custom_materialization - view

Upstream models must have a path that matches the provided upstream_path_pattern.

!!! info "Rationale"

A well-structured dbt project enforces clear layer boundaries — e.g. staging models only reference sources, intermediate models only reference staging or other intermediates, and marts only reference intermediates. Without this check, developers can inadvertently create cross-layer dependencies (a mart model directly referencing a staging model) that erode the project's modularity and make refactoring risky.

Parameters: upstream_path_pattern (str): Regexp pattern to match the upstream model(s) path.

Receives: manifest_obj (ManifestObject): The manifest object. model (ModelNode): The ModelNode object to check. models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_lineage_permitted_upstream_models include: ^models/staging upstream_path_pattern: $^ - name: check_lineage_permitted_upstream_models include: ^models/intermediate upstream_path_pattern: ^models/staging|^models/intermediate - name: check_lineage_permitted_upstream_models include: ^models/marts upstream_path_pattern: ^models/staging|^models/intermediate

Seed cannot be referenced in models with a path that matches the specified include config.

!!! info "Rationale"

Seeds are designed for small, static reference data (e.g. country codes, status mappings). Referencing seeds in intermediate or mart layers can indicate that data which should come from a source or staging model is instead being managed as a CSV file, making it harder to audit, version, and scale.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_lineage_seed_cannot_be_used include: ^models/intermediate|^models/marts

Sources cannot be referenced in models with a path that matches the specified include config.

!!! info "Rationale"

In a well-layered dbt project, raw sources should only be referenced from staging models. Allowing intermediate or mart models to query sources directly bypasses the staging layer, leads to duplicated transformation logic, and makes it harder to swap or rename sources without cascading changes across the project.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_lineage_source_cannot_be_used include: ^models/intermediate|^models/marts

Macro arguments must have a populated description.

!!! info "Rationale"

Macros are reusable across the entire dbt project, yet their arguments are often poorly documented. Without argument descriptions, developers must read the macro's Jinja source to understand what each parameter does, which slows adoption and increases the risk of misuse — especially for macros shared across teams or packages.

Parameters: min_description_length (int | None): Minimum length required for the description to be considered populated.

Receives: macro (Macros): The Macros object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the macro path. Macro paths that match the pattern will not be checked. include (str | None): Regex pattern to match the macro path. Only macro paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_macro_arguments_description_populated yaml # Only "common" macros need to have their arguments populated manifest_checks: - name: check_macro_arguments_description_populated include: ^macros/common yaml manifest_checks: - name: check_macro_arguments_description_populated min_description_length: 25 # Setting a stricter requirement for description length

The raw code for a macro must not match the specified regexp pattern.

!!! info "Rationale"

Teams often settle on preferred SQL patterns — using `COALESCE` instead of `IFNULL`, or avoiding hardcoded warehouse-specific functions — but these conventions are easy to forget in macros that are written less frequently than models. This check provides a lightweight way to enforce banned patterns and flag code that uses deprecated or non-portable SQL constructs before they propagate across the project.

Parameters: regexp_pattern (str): The regexp pattern that should not be matched by the macro code.

Receives: macro (Macros): The Macros object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the macro path. Macro paths that match the pattern will not be checked. include (str | None): Regex pattern to match the macro path. Only macro paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: # Prefer `coalesce` over `ifnull`: [<https://docs.sqlfluff.com/en/stable/rules.html#sqlfluff.rules.sphinx.Rule_CV02](https://docs.sqlfluff.com/en/stable/rules.html#sqlfluff.rules.sphinx.Rule_CV02)> - name: check_macro_code_does_not_contain_regexp_pattern regexp_pattern: .*[i][f][n][u][l][l].*

Macros must have a populated description.

!!! info "Rationale"

Macros are reusable Jinja functions that can be called throughout a dbt project, but unlike models they are not rendered into the dbt documentation site unless explicitly described. Without a description, engineers must read the macro source to understand its purpose and usage, slowing onboarding and increasing the risk of misuse or duplication.

Parameters: min_description_length (int | None): Minimum length required for the description to be considered populated.

Receives: macro (Macros): The Macros object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the macro path. Macro paths that match the pattern will not be checked. include (str | None): Regex pattern to match the macro path. Only macro paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_macro_description_populated yaml # Only "common" macros need to have a populated description manifest_checks: - name: check_macro_description_populated include: ^macros/common

Macros may not have more than the specified number of lines.

!!! info "Rationale"

Long macros are a code smell — they are harder to test, document, and review. Keeping macros concise encourages single-responsibility design and makes it easier to spot logic errors. Teams that enforce a line limit are nudged to decompose complex macros into smaller, composable units that are individually testable.

Parameters: max_number_of_lines (int): The maximum number of permitted lines.

Receives: macro (Macros): The Macros object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the macro path. Macro paths that match the pattern will not be checked. include (str | None): Regex pattern to match the macro path. Only macro paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_macro_max_number_of_lines yaml manifest_checks: - name: check_macro_max_number_of_lines max_number_of_lines: 100

Macros names must be the same as the file they are contained in.

Generic tests are also macros, however to document these tests the "name" value must be preceded with "test_".

!!! info "Rationale"

When a macro name does not match its file name, developers searching the codebase for a macro by name will land in the wrong file, wasting time and creating confusion. Enforcing consistent naming makes macros immediately locatable by file path and helps static analysis tools resolve macro references reliably.

Receives: macro (Macros): The Macros object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the macro path. Macro paths that match the pattern will not be checked. include (str | None): Regex pattern to match the macro path. Only macro paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_macro_name_matches_file_name

Macro properties files must follow the guidance provided by dbt here.

!!! info "Rationale"

dbt's official project structure guidance recommends placing macro property files in predictable, consistently named YAML files alongside the macros they describe. Projects that scatter `.yml` files arbitrarily make it harder to locate documentation, run automated checks, and onboard new engineers. Enforcing the standard naming convention keeps the project structure navigable and aligned with community best practices.

Receives: macro (Macros): The Macros object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the macro path. Macro paths that match the pattern will not be checked. include (str | None): Regex pattern to match the macro path. Only macro paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_macro_property_file_location

Models must have the specified access attribute. Requires dbt 1.7+.

!!! info "Rationale"

Access controls determine which models can be referenced across dbt projects and packages. Enforcing access levels ensures that staging models remain internal (`protected`), while only curated mart models are exposed as `public` — preventing downstream consumers from depending on unstable intermediate transformations.

Parameters: access (Literal["private", "protected", "public"]): The access level to check for.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: # Align with dbt best practices that marts should be `public`, everything else should be `protected` - name: check_model_access access: protected include: ^models/intermediate - name: check_model_access access: public include: ^models/marts - name: check_model_access access: protected include: ^models/staging

The raw code for a model must not match the specified regexp pattern.

!!! info "Rationale"

Teams often adopt coding standards that forbid certain SQL patterns — for example, using `ifnull` instead of `coalesce`, or using deprecated functions. This check allows those standards to be enforced automatically at CI time, preventing non-compliant code from reaching production.

Parameters: regexp_pattern (str): The regexp pattern that should not be matched by the model code.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: # Prefer `coalesce` over `ifnull`: <https://docs.sqlfluff.com/en/stable/rules.html#sqlfluff.rules.sphinx.Rule_CV02> - name: check_model_code_does_not_contain_regexp_pattern regexp_pattern: .*[i][f][n][u][l][l].*

Columns defined for models must have the specified keys in the meta config.

!!! info "Rationale"

Column-level metadata such as `owner` or `pii` flags is essential for data governance, access control, and cataloguing. Without enforcement, metadata is applied inconsistently, making it difficult to identify sensitive columns or assign accountability across a large project.

Parameters: keys (NestedDict): A list (that may contain sub-lists) of required keys.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_columns_have_meta_keys keys: - owner - pii

Columns matching a regex pattern must have a relationships test, optionally validating the target column and model.

!!! info "Rationale"

Foreign-key columns that are never validated with a `relationships` test can silently contain orphaned IDs, leading to incorrect join results and data quality issues that are hard to trace. This check ensures that columns following a naming convention (e.g. `_fk`) are always backed by a referential integrity test.

Parameters: column_name_pattern (str): Regex pattern to match column names that require a relationships test. target_column_pattern (str | None): Regex pattern the target column (field) of the relationships test must match. If not provided, any target column is accepted. target_model_pattern (str | None): Regex pattern the target model of the relationships test must match. If not provided, any target model is accepted.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_columns_have_relationship_tests column_name_pattern: "_fk$" yaml manifest_checks: - name: check_model_columns_have_relationship_tests column_name_pattern: "_fk$" target_column_pattern: "_pk$" target_model_pattern: "^dim_|^fact_"

Columns defined for models must have a data_type declared.

!!! info "Rationale"

Declaring column data types is a prerequisite for enforced dbt contracts and enables downstream consumers to understand the expected format of each field without querying the warehouse. It also prevents type-mismatch errors in tools that consume the schema at build time.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_columns_have_types include: ^models/marts

Public models must have contracts enforced.

!!! info "Rationale"

Public models form the API surface of your dbt project. Without enforced contracts, column additions, removals, or type changes can silently break downstream consumers. This check ensures that every public model guarantees its schema, catching breaking changes at build time rather than in production.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_contract_enforced_for_public_model

Models must depend on the specified macros.

!!! info "Rationale"

Some teams mandate that certain model types always use shared macros for consistency — for example, requiring all incremental models to call `dbt.is_incremental()`. This check enforces those conventions, preventing models from re-implementing logic that is already standardised in a shared macro.

Parameters: criteria: (Literal["any", "all", "one"] | None): Whether the model must depend on any, all, or exactly one of the specified macros. Default: any. required_macros: (list[str]): List of macros the model must depend on. All macros must specify a namespace, e.g. dbt.is_incremental.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_depends_on_macros required_macros: - dbt.is_incremental - name: check_model_depends_on_macros criteria: one required_macros: - my_package.sampler - my_package.sampling

Models cannot reference more than one source.

!!! info "Rationale"

A model that references multiple sources often signals that raw-layer joins are being performed too early, making the model harder to test, debug, and reuse. Enforcing single-source staging models encourages a clean DAG where each staging model maps 1:1 to a source table, and joins happen in downstream intermediate or mart models.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_depends_on_multiple_sources

Models must have a description that matches the provided pattern.

!!! info "Rationale"

A free-text description field is easy to fill with placeholder or low-quality content. Requiring descriptions to match a pattern (e.g. a minimum sentence structure or a specific prefix) ensures that documentation meets a baseline standard of usefulness rather than just being non-empty.

Parameters: regexp_pattern (str): The regexp pattern that should match the model description.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_description_contains_regex_pattern regexp_pattern: .*pattern_to_match.*

Models must have a populated description.

!!! info "Rationale"

Descriptions are the primary way data consumers discover what a model represents and how to use it. Without them, analysts waste time reverse-engineering SQL logic or asking the data team. This check ensures every model is self-documenting, which is critical for onboarding, data catalogues, and self-service analytics.

Parameters: min_description_length (int | None): Minimum length required for the description to be considered populated.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_description_populated yaml manifest_checks: - name: check_model_description_populated min_description_length: 25 # Setting a stricter requirement for description length

Only specified sub-directories are permitted.

!!! info "Rationale"

A well-structured dbt project organises models into predictable directories (e.g. `staging`, `intermediate`, `marts`). Enforcing permitted sub-directories prevents ad-hoc folders from proliferating, making the project layout consistent and navigable for all contributors.

Parameters: include (str): Regex pattern to the directory to check. permitted_sub_directories (list[str]): List of permitted sub-directories.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_directories include: models permitted_sub_directories: - intermediate - marts - staging yaml # Restrict sub-directories within `./models/staging` - name: check_model_directories include: ^models/staging permitted_sub_directories: - crm - payments

Set the minimum percentage of models that have a populated description.

!!! info "Rationale"

Rather than requiring every single model to be documented immediately, this check allows teams to set a realistic target and enforce it incrementally. It prevents documentation coverage from silently regressing as new models are added, nudging teams towards full documentation over time.

Parameters: min_model_documentation_coverage_pct (float): The minimum percentage of models that must have a populated description.

Receives: models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_documentation_coverage min_model_documentation_coverage_pct: 90 yaml manifest_checks: - name: check_model_documentation_coverage min_description_length: 25 # Setting a stricter requirement for description length

Models must be documented in the same directory where they are defined (i.e. .yml and .sql files are in the same directory).

!!! info "Rationale"

Co-locating a model's SQL file and its YAML documentation makes the project easier to navigate. When documentation lives in a different directory, contributors may miss it during code review or forget to update it when changing the model. Keeping both files together reinforces the habit of treating documentation as part of the model definition.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_documented_in_same_directory

Models must have a file name that matches the supplied regex.

!!! info "Rationale"

Consistent file naming conventions (e.g. including a version suffix for mart models) make it easy to identify a model's purpose and layer at a glance. Enforcing naming patterns in CI prevents deviations that accumulate over time and make the project harder to navigate.

Parameters: file_name_pattern (str): Regexp the file name must match. Please account for the .sql extension.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_file_name description: Marts must include the model version in their file name. include: ^models/marts file_name_pattern: .*(v[0-9])\.sql$

Model can have grant privileges that match the specified pattern.

!!! info "Rationale"

Uncontrolled grant names can lead to excessive or incorrectly named privileges being applied to models, making it difficult to audit who has access to what. Enforcing a naming pattern for grants ensures consistency and makes security reviews straightforward.

Parameters: privilege_pattern (str): Regex pattern to match the privilege.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_grant_privilege include: ^models/marts privilege_pattern: ^select

Model must have the specified grant privilege.

!!! info "Rationale"

Mart models often need to be readable by BI tools or downstream consumers. Requiring a specific grant privilege (e.g. `select`) ensures that access is explicitly configured and not left to database defaults, which may vary across environments.

Parameters: privilege (str): The privilege that is required.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_grant_privilege_required include: ^models/marts privilege: select

A model must not contain hard-coded table references; use ref() or source() instead.

Scans raw_code for patterns like FROM schema.table or JOIN catalog.schema.table that are not wrapped in Jinja expressions. Hard-coded references bypass the dbt DAG, break lineage, and are environment-specific.

!!! info "Rationale"

Hard-coded table references bypass dbt's dependency graph, break lineage tracking, and are environment-specific — a reference that works in production will silently read the wrong data in development. Using `ref()` or `source()` ensures models run in the correct order, compile to the right environment, and appear correctly in lineage tools.

!!! warning

This check is not foolproof and will not catch all hard-coded table
references (e.g. references inside complex Jinja logic or comments).

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_hard_coded_references

Table and incremental models must have the specified constraint types defined.

!!! info "Rationale"

Database constraints such as `primary_key` and `not_null` enforce data integrity at the warehouse level, providing a safety net that goes beyond dbt tests. Requiring them on materialised models ensures that quality guarantees survive even when dbt tests are skipped or not run on every refresh.

Parameters: required_constraint_types (list[Literal["check", "custom", "foreign_key", "not_null", "primary_key", "unique"]]): List of constraint types that must be present on the model.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_constraints required_constraint_types: - primary_key include: ^models/marts

Model must have contracts enforced.

!!! info "Rationale"

Enforced contracts guarantee that a model's output schema — column names and types — is validated at build time. Without this, schema changes can silently break downstream consumers. Applying this check to a specific set of models (e.g. marts) provides a schema stability guarantee for those critical outputs.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_contracts_enforced include: ^models/marts

Models must have an exposure.

!!! info "Rationale"

Exposures declare how dbt models are consumed by downstream tools such as dashboards, ML pipelines, or applications. Requiring mart models to be referenced in at least one exposure ensures that every curated output has a known consumer, making it easier to assess the impact of changes and avoid maintaining unused models.

Receives: exposures (list[ExposureNode]): List of ExposureNode objects parsed from manifest.json. model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_exposure description: Ensure all marts are part of an exposure. include: ^models/marts

The meta config for models must have the specified keys.

!!! info "Rationale"

The `meta` config is a flexible, project-defined dictionary used to track ownership, maturity levels, PII classification, and other governance attributes. Requiring specific keys ensures that these attributes are consistently populated across all models, enabling automated reporting, data cataloguing, and access-control workflows that depend on them.

Parameters: keys (NestedDict): A list (that may contain sub-lists) of required keys.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_meta_keys keys: - maturity - owner

Identify if models have no upstream dependencies as this likely indicates hard-coded tables references.

!!! info "Rationale"

A model with zero upstream dependencies is almost certainly using hard-coded table references (`FROM schema.table`) instead of `ref()` or `source()`. This breaks dbt's dependency graph, meaning the model won't run in the correct order, won't appear in lineage, and won't benefit from environment-aware compilation.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_no_upstream_dependencies

Model may not end with a semi-colon (;).

!!! info "Rationale"

dbt automatically wraps model SQL before executing it, so a trailing semi-colon can cause syntax errors in certain warehouse adapters. This check catches the mistake at lint time, preventing obscure build failures that can be hard to diagnose in CI.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_semi_colon include: ^models/marts

Models must have the specified tags.

!!! info "Rationale"

Tags are used to group models for selective execution (e.g. `dbt run --select tag:daily`), documentation filtering, and governance tracking. Requiring models in specific directories to carry certain tags ensures that scheduling and operational workflows that depend on those tags remain reliable as the project evolves.

Parameters: criteria: (Literal["any", "all", "one"] | None): Whether the model must have any, all, or exactly one of the specified tags. Default: any. tags (list[str]): List of tags to check for.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_tags tags: - tag_1 - tag_2

Models must have a test for uniqueness of a column.

!!! info "Rationale"

A uniqueness test is the most fundamental data quality check — it ensures that the primary key or identifier column of a model does not contain duplicates, which would cause incorrect counts and fan-out in downstream joins. This check enforces that no model reaches production without at least one uniqueness assertion.

Parameters: accepted_uniqueness_tests (list[str] | None): List of tests that are accepted as uniqueness tests.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_has_unique_test include: ^models/marts yaml manifest_checks: # Example of allowing a custom uniqueness test - name: check_model_has_unique_test accepted_uniqueness_tests: - dbt_expectations.expect_compound_columns_to_be_unique # i.e. tests from packages must include package name - my_custom_uniqueness_test - unique

Models must have more than the specified number of unit tests.

!!! info "Rationale"

Unit tests validate a model's transformation logic with controlled, mock inputs rather than real warehouse data. Requiring them on critical models (e.g. marts) ensures that complex SQL logic is verified independently of data volume or state, catching regressions before they affect downstream consumers.

Parameters: min_number_of_unit_tests (int | None): The minimum number of unit tests that a model must have.

Receives: manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. model (ModelNode): The ModelNode object to check. unit_tests (list[UnitTests]): List of UnitTests objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

!!! warning

This check is only supported for dbt 1.8.0 and above.

Example(s): yaml manifest_checks: - name: check_model_has_unit_tests include: ^models/marts yaml manifest_checks: - name: check_model_has_unit_tests min_number_of_unit_tests: 2

Check that the latest_version attribute of the model is set.

!!! info "Rationale"

The `latest_version` attribute tells dbt which version of a model downstream consumers should default to when using `ref('model_name')` without specifying a version. Without it, dbt cannot resolve unversioned references, and consumers may inadvertently pin to an older version. Enforcing this attribute ensures the model versioning contract is fully specified.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_latest_version_specified include: ^models/marts

Models cannot have more than the specified number of upstream dependents that are not tables.

!!! info "Rationale"

Long chains of views and ephemeral models force the data warehouse to execute deeply nested queries at read time, which degrades query performance and can hit platform-specific nesting limits. Capping chained views encourages materialising intermediate results, trading a small amount of storage for significantly faster query execution.

Parameters: materializations_to_include (list[str] | None): List of materializations to include in the check. max_chained_views (int | None): The maximum number of upstream dependents that are not tables.

Receives: model (ModelNode): The ModelNode object to check. models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_max_chained_views yaml manifest_checks: - name: check_model_max_chained_views materializations_to_include: - ephemeral - my_custom_materialization - view max_chained_views: 5

Models cannot have more than the specified number of downstream models.

!!! info "Rationale"

A model with many direct downstream dependents becomes a high-impact change point — any modification to it requires testing and potentially breaking many consumers. Capping fanout encourages breaking widely-shared logic into more focused intermediate models, reducing the blast radius of changes.

Parameters: max_downstream_models (int | None): The maximum number of permitted downstream models.

Receives: model (ModelNode): The ModelNode object to check. models (list[ModelNode]): List of ModelNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_max_fanout max_downstream_models: 2

Models may not have more than the specified number of lines.

!!! info "Rationale"

Very long SQL files are a code smell that often indicates a model is doing too much — mixing staging, joining, and aggregating in a single file. Capping line counts encourages splitting large transformations into smaller, focused models that are easier to test, understand, and reuse.

Parameters: max_number_of_lines (int): The maximum number of permitted lines.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_max_number_of_lines yaml manifest_checks: - name: check_model_max_number_of_lines max_number_of_lines: 150

Limit the number of upstream dependencies a model has.

!!! info "Rationale"

A model that depends on too many upstream models, sources, or macros is likely doing too much in one place. Limiting upstream dependencies encourages splitting large transformations into smaller, testable units, which improves build times, reduces coupling, and makes the DAG easier to reason about.

Parameters: max_upstream_macros (int | None): The maximum number of permitted upstream macros. max_upstream_models (int | None): The maximum number of permitted upstream models. max_upstream_sources (int | None): The maximum number of permitted upstream sources.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_max_upstream_dependencies max_upstream_models: 3

Models must have a name that matches the supplied regex.

!!! info "Rationale"

Naming conventions such as `stg_` for staging models and `int_` for intermediate models are a cornerstone of readable dbt projects. Enforcing these patterns in CI prevents inconsistently named models from being merged, keeping the project navigable as it grows.

Parameters: model_name_pattern (str): Regexp the model name must match.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_names include: ^models/intermediate model_name_pattern: ^int_ - name: check_model_names include: ^models/staging model_name_pattern: ^stg_

Model can have the specified number of privileges.

!!! info "Rationale"

An unexpectedly large number of grants on a model may indicate privilege creep, where access has accumulated over time without a systematic review. Bounding the number of grants encourages a deliberate access-control strategy and makes security audits easier.

Parameters: max_number_of_privileges (int | None): Maximum number of privileges, inclusive. min_number_of_privileges (int | None): Minimum number of privileges, inclusive.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_number_of_grants include: ^models/marts max_number_of_privileges: 1 # Optional min_number_of_privileges: 0 # Optional

Model properties files must follow the guidance provided by dbt here.

!!! info "Rationale"

dbt's official guidance recommends a specific naming and placement convention for YAML property files (e.g. `_staging__models.yml`). Following this convention ensures that property files are easy to locate, clearly scoped, and consistent with the broader dbt community's expectations.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_property_file_location

Models must have a schema name that matches the supplied regex.

!!! info "Rationale"

Consistent schema naming (e.g. `stg_payments` for staging models or `intermediate` for intermediate ones) makes it clear where a model lives in the transformation pipeline without inspecting its SQL. This also prevents models from landing in unexpected schemas in production due to misconfigured `dbt_project.yml` settings.

Note that most setups will use schema names in development that are prefixed, for example: * dbt_jdoe_stg_payments * mary_stg_payments

Please account for this if you wish to run dbt-bouncer against locally generated manifests.

Parameters: schema_name_pattern (str): Regexp the schema name must match.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_schema_name include: ^models/intermediate schema_name_pattern: .*intermediate # Accounting for schemas like `dbt_jdoe_intermediate`. - name: check_model_schema_name include: ^models/staging schema_name_pattern: .*stg_.*

Set the minimum percentage of models that have at least one test.

!!! info "Rationale"

Rather than requiring every model to be tested immediately, this check lets teams set a realistic coverage target and enforce it progressively. It prevents test coverage from silently declining as new, untested models are added to the project, creating a ratchet towards comprehensive testing.

Parameters: min_model_test_coverage_pct (float): The minimum percentage of models that must have at least one test.

Receives: models (list[ModelNode]): List of ModelNode objects parsed from manifest.json. tests (list[TestNode]): List of TestNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_test_coverage min_model_test_coverage_pct: 90

Check that the version of the model matches the supplied regex pattern.

!!! info "Rationale"

Teams that use model versioning often enforce a convention for version identifiers — for example, numeric-only versions or semantic version strings. This check validates that version values conform to the team's chosen scheme, preventing arbitrary or malformed version strings from being introduced.

Parameters: version_pattern (str): Regexp the version must match.

Receives: model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_version_allowed include: ^models/marts version_pattern: >- # Versions must be numeric [0-9]\d* - name: check_model_version_allowed include: ^models/marts version_pattern: ^(stable|latest)$ # Version can be "stable" or "latest", nothing else is permitted

Check that the version of the model is always specified in downstream nodes.

!!! info "Rationale"

When a versioned model is referenced without specifying a version, dbt resolves it to the `latest_version`, meaning a version bump can silently redirect all downstream consumers. Requiring explicit version pins in `ref()` calls ensures that version upgrades are a deliberate, reviewed change rather than an implicit one.

Receives: manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. model (ModelNode): The ModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the model path. Model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. materialization (Literal["ephemeral", "incremental", "table", "view"] | None): Limit check to models with the specified materialization. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_model_version_pinned_in_ref include: ^models/marts

Enforce that the name of the dbt project matches a supplied regex. Generally used to enforce that project names conform to something like company_<DOMAIN>.

!!! info "Rationale"

In organisations running multiple dbt projects, consistent project naming makes it easy to identify which team or domain owns a project, automate governance policies, and set up CI/CD pipelines that apply different rules to different project types. Without a naming convention, projects can accumulate with arbitrary names that make ownership and purpose ambiguous.

Parameters: project_name_pattern (str): Regex pattern to match the project name.

Receives: manifest_obj (ManifestObject): The manifest object.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_project_name project_name_pattern: ^awesome_company_

Each result can take a maximum duration (seconds).

!!! info "Rationale"

Model execution times can creep up gradually as data volumes grow or queries become more complex. Without an explicit threshold, a model that once ran in 10 seconds can silently grow to 10 minutes, eventually causing pipeline timeouts or SLA breaches. This check acts as a performance guardrail, catching regressions early so teams can investigate and optimise before they impact production schedules.

Parameters: max_execution_time_seconds (float): The maximum execution time (seconds) allowed for a node.

Receives: run_result (RunResultEntry): The RunResultEntry object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the resource path. Resource paths that match the pattern will not be checked. include (str | None): Regex pattern to match the resource path. Only resource paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml run_results_checks: - name: check_run_results_max_execution_time max_execution_time_seconds: 60 yaml run_results_checks: - name: check_run_results_max_execution_time include: ^models/staging # Not a good idea, here for demonstration purposes only max_execution_time_seconds: 10

Each result can have a maximum number of gigabytes billed.

!!! info "Rationale"

BigQuery charges are based on the volume of data scanned per query, so a poorly optimised model or an accidental full-table scan can generate unexpectedly large bills. Without an explicit cap, a single expensive run can blow through a project's monthly data budget before anyone notices. This check provides a cost guardrail that fails a CI run or pipeline job if any model scans more data than permitted, prompting investigation and optimisation before the bill arrives.

!!! note

Note that this check only works for the `dbt-bigquery` adapter.

Parameters: max_gigabytes_billed (float): The maximum number of gigabytes billed.

Receives: run_result (RunResultEntry): The RunResultEntry object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the resource path. Resource paths that match the pattern will not be checked. include (str | None): Regex pattern to match the resource path. Only resource paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Raises: RuntimeError: If the dbt-bigquery adapter is not used.

Example(s): yaml run_results_checks: - name: check_run_results_max_gigabytes_billed max_gigabytes_billed: 100 exclude: ^seeds

Seed columns must have names that match the supplied regex.

!!! info "Rationale"

Seeds are loaded directly into the warehouse from CSV files, and their column names become part of the project's data contract. Inconsistent casing or naming conventions (e.g. mixing camelCase and snake_case) causes friction when joining seed data with other models and makes the project harder to maintain. Enforcing a naming pattern keeps seed columns consistent with the rest of the project.

Parameters: seed_column_name_pattern (str): Regexp the column name must match.

Receives: seed (SeedNode): The SeedNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the seed path. Seed paths that match the pattern will not be checked. include (str | None): Regex pattern to match the seed path. Only seed paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_seed_column_names seed_column_name_pattern: ^[a-z_]+$ # Lowercase with underscores only

All columns in a seed CSV file should be included in the seed's properties file, i.e. .yml file.

!!! warning

This check is only supported for dbt 1.9.0 and above.

!!! info "Rationale"

Seed CSV files often serve as reference data (e.g. country codes, product categories) that are queried directly by downstream models. When a column exists in the CSV but not in the properties file, it is invisible to documentation tools, data catalogues, and column-level tests. This check ensures that every column in a seed is explicitly declared, making it easier for consumers to understand the seed's schema and for teams to apply descriptions and tests uniformly.

Receives: catalog_node (CatalogNodeEntry): The CatalogNodeEntry object to check. manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. seeds (list[SeedNode]): List of SeedNode objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the seed path. Seed paths that match the pattern will not be checked. include (str | None): Regex pattern to match the seed path. Only seed paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: - name: check_seed_columns_are_all_documented

Columns defined for seeds must have a data_type declared.

!!! info "Rationale"

Without explicit `data_type` declarations, dbt seeds rely on the warehouse to infer column types from the CSV data, which can lead to unexpected type coercions (e.g. numeric IDs loaded as strings, dates loaded as text). Declaring types explicitly ensures the seed loads with the expected schema and prevents subtle data quality issues downstream.

Receives: seed (SeedNode): The SeedNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the seed path. Seed paths that match the pattern will not be checked. include (str | None): Regex pattern to match the seed path. Only seed paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_seed_columns_have_types

Seeds must have a populated description.

!!! info "Rationale"

Seeds represent static reference or lookup data that is loaded into the warehouse from version-controlled CSV files. Without descriptions, it is unclear what a seed contains, why it exists, and when it was last validated — making it difficult for new team members to assess whether data they find in the warehouse is the right dataset to use.

Parameters: min_description_length (int | None): Minimum length required for the description to be considered populated.

Receives: seed (SeedNode): The SeedNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the seed path. Seed paths that match the pattern will not be checked. include (str | None): Regex pattern to match the seed path. Only seed paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_seed_description_populated yaml manifest_checks: - name: check_seed_description_populated min_description_length: 25 # Setting a stricter requirement for description length

Seeds must have more than the specified number of unit tests.

!!! info "Rationale"

Seeds contain static data that is loaded directly into the warehouse, and their transformations (via the `ref()` function in downstream models) need to be verifiable. Unit tests on seeds validate that the downstream logic correctly handles the reference data — catching issues like missing mappings, unexpected nulls, or edge-case values before they reach production.

Parameters: min_number_of_unit_tests (int | None): The minimum number of unit tests that a seed must have.

Receives: manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. seed (SeedNode): The SeedNode object to check. unit_tests (list[UnitTests]): List of UnitTests objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the seed path. Seed paths that match the pattern will not be checked. include (str | None): Regex pattern to match the seed path. Only seed paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

!!! warning

This check is only supported for dbt 1.8.0 and above.

Example(s): yaml manifest_checks: - name: check_seed_has_unit_tests include: ^seeds/core yaml manifest_checks: - name: check_seed_has_unit_tests min_number_of_unit_tests: 2

Seed must have a name that matches the supplied regex.

!!! info "Rationale"

Seed naming conventions help analysts and engineers quickly identify reference data in the warehouse and distinguish seeds from models or sources. A consistent prefix or pattern (e.g. `ref_` or `raw_`) makes it clear what type of data an object contains and prevents naming collisions between seeds and other resources in the project.

Parameters: seed_name_pattern (str): Regexp the seed name must match.

Receives: seed (SeedNode): The SeedNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the seed path. Seed paths that match the pattern will not be checked. include (str | None): Regex pattern to match the seed path. Only seed paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_seed_names include: ^seeds seed_name_pattern: ^raw_

Semantic models should be based on public models only.

!!! info "Rationale"

Semantic models define the business-level metrics and dimensions that power tools like dbt's MetricFlow. If a semantic model references a protected or private model, it creates a hidden dependency on implementation details that can break when the underlying model is refactored. Basing semantic models on public models ensures they depend on a stable, intentionally-exposed interface.

Receives: models (list[ModelNode]): List of ModelNode objects parsed from manifest.json. semantic_model (SemanticModelNode): The SemanticModelNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the semantic model path (i.e the .yml file where the semantic model is configured). Semantic model paths that match the pattern will not be checked. include (str | None): Regex pattern to match the semantic model path (i.e the .yml file where the semantic model is configured). Only semantic model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_semantic_model_based_on_non_public_models

Severity levels for dbt-bouncer check results.

Snapshots must have a populated description.

!!! info "Rationale"

Snapshots capture slowly-changing dimension (SCD) history and represent some of the most business-critical data in a dbt project. Without descriptions, it is unclear what entity a snapshot tracks, what the key fields represent, or how frequently it is refreshed — information that is essential for analysts interpreting historical data and for engineers maintaining the snapshot strategy.

Parameters: min_description_length (int | None): Minimum length required for the description to be considered populated.

Receives: snapshot (SnapshotNode): The SnapshotNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the snapshot path. Snapshot paths that match the pattern will not be checked. include (str | None): Regex pattern to match the snapshot path. Only snapshot paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_snapshot_description_populated yaml manifest_checks: - name: check_snapshot_description_populated min_description_length: 25 # Setting a stricter requirement for description length

Snapshots must have the specified tags.

!!! info "Rationale"

Tags on snapshots enable selective execution (e.g. `dbt snapshot --select tag:nightly`) and make it possible to apply governance policies to specific groups of snapshots. Without enforced tagging, snapshots can be inadvertently skipped in scheduled runs or included in the wrong execution contexts, leading to stale historical data.

Parameters: criteria: (Literal["any", "all", "one"] | None): Whether the snapshot must have any, all, or exactly one of the specified tags. Default: all. tags (list[str]): List of tags to check for.

Receives: snapshot (SnapshotNode): The SnapshotNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the snapshot path. Snapshot paths that match the pattern will not be checked. include (str | None): Regex pattern to match the snapshot path. Only snapshot paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_snapshot_has_tags tags: - tag_1 - tag_2

Snapshots must have a name that matches the supplied regex.

!!! info "Rationale"

A consistent naming convention for snapshots (e.g. a domain prefix like `erp_` or a suffix like `_snapshot`) makes it immediately obvious in the warehouse that a table is a point-in-time history capture rather than a regular dimension or fact. Without naming conventions, snapshots can be confused with other tables, leading to incorrect use or accidental truncation.

Parameters: snapshot_name_pattern (str): Regexp the snapshot name must match.

Receives: snapshot (SnapshotNode): The SnapshotNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the snapshot path. Snapshot paths that match the pattern will not be checked. include (str | None): Regex pattern to match the snapshot path. Only snapshot paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_snapshot_names include: ^snapshots/erp snapshot_name_pattern: ^erp

All columns in a source should be included in the source's properties file, i.e. .yml file.

!!! info "Rationale"

Source tables are the entry point for raw data into a dbt project. When a column exists in the database but is absent from the source properties file, it cannot have a description, a freshness check, or a data test applied to it. Over time, undocumented columns accumulate silently, making it harder to understand what data is available and creating blind spots in data quality monitoring. This check enforces full column coverage so that every raw field is explicitly acknowledged and can be tested or documented.

Receives: catalog_source (CatalogNodeEntry): The CatalogNodeEntry object to check. sources (list[SourceNode]): List of SourceNode objects parsed from catalog.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml catalog_checks: - name: check_source_columns_are_all_documented

Sources must have a populated description.

!!! info "Rationale"

Sources represent the boundary between raw, external data and the curated dbt project. A populated description explains what the source is, where it comes from, and how it is loaded — context that is invaluable when debugging data issues or onboarding new team members. Without enforcing descriptions, sources accumulate as anonymous inputs that future maintainers cannot evaluate or trust, increasing the risk of misuse or redundant ingestion pipelines.

Parameters: min_description_length (int | None): Minimum length required for the description to be considered populated.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_description_populated yaml manifest_checks: - name: check_source_description_populated min_description_length: 25 # Setting a stricter requirement for description length

Sources must have a populated freshness.

!!! info "Rationale"

Source freshness configuration enables `dbt source freshness` to detect when upstream data stops arriving. Without it, stale data silently propagates through downstream models, and dashboards display outdated numbers without any warning. Requiring freshness definitions ensures that every source has an explicit SLA, enabling proactive alerting before business users notice a problem.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_freshness_populated

The meta config for sources must have the specified keys.

!!! info "Rationale"

The `meta` config is a free-form dictionary that teams use to attach governance information to dbt nodes — things like data owner, sensitivity classification, SLA tier, or compliance labels. Without enforcing required keys, this metadata is applied inconsistently: some sources have an owner, others do not; some are labelled PII-sensitive, others are silently omitted. This check ensures that every source carries the minimum set of metadata keys needed to support data governance, access control automation, and operational runbooks.

Parameters: keys (NestedDict): A list (that may contain sub-lists) of required keys.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_has_meta_keys keys: - contact: - email - slack - owner

Sources must have the specified tags.

!!! info "Rationale"

Tags are the primary mechanism for grouping dbt nodes into logical categories — domain areas, sensitivity levels, scheduling tiers, or compliance scopes. When sources are missing required tags, they fall outside automated workflows that rely on tag-based selection (e.g. `dbt build --select tag:pii` or scheduled refreshes filtered by domain). This check ensures that every source is tagged correctly at registration time, preventing ungrouped sources from slipping through governance and operational processes.

Parameters: criteria: (Literal["any", "all", "one"] | None): Whether the source must have any, all, or exactly one of the specified tags. Default: all. tags (list[str]): List of tags to check for.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_has_tags tags: - tag_1 - tag_2

Sources must have a populated loader.

!!! info "Rationale"

The `loader` field documents which tool or pipeline is responsible for bringing data into the warehouse (e.g. Fivetran, Airbyte, a custom ETL script). Without it, there is no traceable link between a dbt source and the upstream process that feeds it, making it difficult to investigate data quality issues, coordinate with data engineering teams, or assess the impact of changes to the ingestion layer. Requiring a populated loader turns each source into a self-documenting artifact that points clearly to its origin.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_loader_populated

Sources must have a name that matches the supplied regex.

!!! info "Rationale"

Source names appear throughout the dbt project in `{{ source() }}` calls, documentation, and lineage graphs. Inconsistent naming (mixed case, spaces, non-standard characters) makes sources harder to reference and distinguish at a glance, and can cause subtle errors when names are used in downstream string processing or data catalogue integrations. Enforcing a naming pattern ensures all sources share a predictable, readable format from the moment they are registered in the project.

Parameters: source_name_pattern (str): Regexp the source name must match.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_names source_name_pattern: > ^[a-z0-9_]*$

Sources must be referenced in at least one model.

!!! info "Rationale"

An orphaned source — one that is declared in the project but never referenced by any model — is a maintenance liability. It adds noise to the project's source catalogue, may represent a data feed that is no longer needed, and can mislead new team members into thinking data is being used when it is not. This check keeps the source catalogue clean by flagging any source that has no downstream consumers, prompting teams to either wire it into the lineage graph or remove it.

Receives: models (list[ModelNode]): List of ModelNode objects parsed from manifest.json. source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_not_orphaned

Source properties files must follow the guidance provided by dbt here.

!!! info "Rationale"

dbt's official project structure guide recommends placing source properties files in the staging layer alongside the models that consume them, with a predictable naming convention (e.g. `_<layer>__sources.yml`). Following this convention makes it immediately obvious where to find a source's configuration, prevents properties files from being scattered across arbitrary directories, and ensures that new team members can navigate the project without guesswork. This check codifies the convention so it is enforced automatically rather than relied upon by convention alone.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_property_file_location

Sources can only be referenced by models that are located in the same directory where the source is defined.

!!! info "Rationale"

dbt's best-practice project structure places source definitions alongside the staging models that consume them. When a model in a distant directory references a source, it breaks this colocation principle, making it harder to understand which models own which sources and causing confusion about where raw-to-staged transformations live. Enforcing same-directory usage keeps source ownership explicit and the staging layer well-bounded.

Receives: source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_used_by_models_in_same_directory

Each source can be referenced by a maximum of one model.

!!! info "Rationale"

A common dbt best practice is to have a single staging model per source table, acting as the sole entry point that applies initial cleaning, renaming, and casting. When multiple models reference the same source directly, that cleaning logic is duplicated or diverges, leading to inconsistent representations of the same raw data across the project. Enforcing a single consumer per source encourages the staging-layer pattern and makes it clear where the authoritative transformation of each source lives.

Receives: models (list[ModelNode]): List of ModelNode objects parsed from manifest.json. source (SourceNode): The SourceNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Source paths that match the pattern will not be checked. include (str | None): Regex pattern to match the source path (i.e the .yml file where the source is configured). Only source paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_source_used_by_only_one_model

The meta config for data tests must have the specified keys.

!!! info "Rationale"

The `meta` field on data tests is a flexible store for operational metadata such as ownership, severity context, or ticket references. Enforcing required keys ensures that every test carries the information needed to triage failures quickly — for example, knowing which team owns a failing test or what SLA it is tied to — without relying on tribal knowledge or documentation that falls out of sync.

Parameters: keys (NestedDict): A list (that may contain sub-lists) of required keys.

Receives: test (TestNode): The TestNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the test path. Test paths that match the pattern will not be checked. include (str | None): Regex pattern to match the test path. Only test paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_test_has_meta_keys keys: - owner

Data tests must have the specified tags.

!!! info "Rationale"

Tags allow teams to organise tests into logical groups (e.g. `critical`, `nightly`, `schema-only`) and run subsets selectively with `dbt test --select tag:critical`. Without enforced tagging, it becomes difficult to prioritise test failures, run fast CI checks, or set up tiered alerting based on test severity.

Parameters: criteria (Literal["any", "all", "one"] | None): Whether the test must have any, all, or exactly one of the specified tags. Default: all. tags (list[str]): List of tags to check for.

Receives: test (TestNode): The TestNode object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the test path. Test paths that match the pattern will not be checked. include (str | None): Regex pattern to match the test path. Only test paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_test_has_tags tags: - critical

Set the minimum percentage of models that have a unit test.

!!! info "Rationale"

Unit tests validate that a model's SQL logic produces the correct output for a given set of inputs, independently of live data. Tracking coverage across the project ensures that critical business logic is not left untested, which reduces the risk of silent regressions when models are refactored or when source data shapes change unexpectedly.

!!! warning

This check is only supported for dbt 1.8.0 and above.

Parameters: min_unit_test_coverage_pct (float): The minimum percentage of models that must have a unit test.

Receives: models (list[ModelNode]): List of ModelNode objects parsed from manifest.json. unit_tests (list[UnitTests]): List of UnitTests objects parsed from manifest.json.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. include (str | None): Regex pattern to match the model path. Only model paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_unit_test_coverage min_unit_test_coverage_pct: 90

Unit tests can only use the specified formats.

!!! info "Rationale"

dbt unit tests support multiple `expect` formats — `csv`, `dict`, and `sql` — each with different trade-offs in readability, portability, and maintenance overhead. Restricting permitted formats enforces a project-wide standard that keeps unit tests consistent and readable, and avoids formats that may be harder for the team to maintain (e.g. raw SQL expectations that are difficult to diff).

!!! warning

This check is only supported for dbt 1.8.0 and above.

Parameters: permitted_formats (list[Literal["csv", "dict", "sql"]] | None): A list of formats that are allowed to be used for expect input in a unit test.

Receives: manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. unit_test (UnitTests): The UnitTests object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the unit test path (i.e the .yml file where the unit test is configured). Unit test paths that match the pattern will not be checked. include (str | None): Regex pattern to match the unit test path (i.e the .yml file where the unit test is configured). Only unit test paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_unit_test_expect_format permitted_formats: - csv

Unit tests can only use the specified formats.

!!! info "Rationale"

The `given` section of a dbt unit test defines the mock input data for the test. Standardising the format across all `given` inputs (e.g. requiring `csv` for human-readable diffs in code review) keeps tests consistent and ensures that engineers reviewing test changes can quickly assess whether the input data is correct without needing to parse unfamiliar formats.

!!! warning

This check is only supported for dbt 1.8.0 and above.

Parameters: permitted_formats (list[Literal["csv", "dict", "sql"]] | None): A list of formats that are allowed to be used for expect input in a unit test.

Receives: manifest_obj (ManifestObject): The ManifestObject object parsed from manifest.json. unit_test (UnitTests): The UnitTests object to check.

Other Parameters: description (str | None): Description of what the check does and why it is implemented. exclude (str | None): Regex pattern to match the unit test path (i.e the .yml file where the unit test is configured). Unit test paths that match the pattern will not be checked. include (str | None): Regex pattern to match the unit test path (i.e the .yml file where the unit test is configured). Only unit test paths that match the pattern will be checked. severity (Literal["error", "warn"] | None): Severity level of the check. Default: error.

Example(s): yaml manifest_checks: - name: check_unit_test_given_formats permitted_formats: - csv

dbt materialization strategies.

A dictionary that can contain nested dictionaries or lists.