Lineage#
Note
The below checks require manifest.json to be present.
Checks related to model upstream dependencies and lineage.
Functions:
| Name | Description |
|---|---|
check_model_depends_on_macros |
Models must depend on the specified macros. |
check_model_depends_on_multiple_sources |
Models cannot reference more than one source. |
check_model_does_not_directly_join_to_source |
Models cannot reference a source and a model at the same time. |
check_model_does_not_rejoin_upstream_concepts |
Models cannot join back to an upstream concept that one of their other parents already depends on. |
check_model_has_exposure |
Models must have an exposure. |
check_model_has_no_upstream_dependencies |
Identify if models have no upstream dependencies as this likely indicates hard-coded tables references. |
check_model_materialization_by_fanout |
Heavily-reused models must use a durable materialization. |
check_model_max_chained_views |
Models cannot have more than the specified number of upstream dependents that are not tables. |
check_model_max_fanout |
Models cannot have more than the specified number of downstream models. |
check_model_max_upstream_dependencies |
Limit the number of upstream dependencies a model has. |
check_model_min_downstream_models |
Models must be referenced by at least the specified number of downstream models. |
check_model_depends_on_macros
#
Models must depend on the specified macros.
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:
| Name | Type | Description | Default |
|---|---|---|---|
criteria
|
Literal[all, any, one]
|
Whether the model must depend on any, all, or exactly one of the specified macros. Default: |
ALL
|
required_macros
|
list[str]
|
List of macros the model must depend on. All macros must specify a namespace, e.g. |
required |
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
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
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_depends_on_multiple_sources
#
Models cannot reference more than one source.
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 at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_does_not_directly_join_to_source
#
Models cannot reference a source and a model at the same time.
Rationale
A model that joins raw source data directly to an already-transformed model mixes two levels of abstraction in one place. The source side bypasses the staging layer, so the renaming, casting, and cleaning applied to every other consumer of that source is silently skipped. Routing every source through a staging model first keeps raw-data handling in exactly one place and makes the lineage graph read consistently from raw to curated.
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_does_not_rejoin_upstream_concepts
#
Models cannot join back to an upstream concept that one of their other parents already depends on.
Rationale
A rejoin happens when a model reads from both a parent B and one of B's own parents A. If B exists only to feed this model, then A's columns are being pulled in twice by two different routes, and the two paths can drift apart as the logic evolves. Collapsing B into its only consumer — or having that consumer read solely from B — keeps each concept entering the model exactly once and makes the lineage graph honest about what depends on what.
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
models |
list[ModelNode]
|
List of ModelNode objects parsed from |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_has_exposure
#
Models must have an exposure.
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 at execution time:
| Name | Type | Description |
|---|---|---|
exposures |
list[ExposureNode]
|
List of ExposureNode objects parsed from |
model |
ModelNode
|
The ModelNode object to check. |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
manifest_checks:
- name: check_model_has_exposure
description: Ensure all marts are part of an exposure.
include: ^models/marts
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_has_no_upstream_dependencies
#
Identify if models have no upstream dependencies as this likely indicates hard-coded tables references.
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 at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_materialization_by_fanout
#
Heavily-reused models must use a durable materialization.
Rationale
A model consumed by many downstream models but materialized as a view re-executes its full query logic on every downstream build, multiplying warehouse compute and increasing overall pipeline latency. Hub models with high fanout should be persisted (dynamic tables, incremental models, materialized views or tables) so that downstream builds read pre-computed results rather than re-running the same transformations repeatedly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
materializations
|
list[str] | None
|
Accepted durable materializations for models above the fanout threshold. Default: |
None
|
min_downstream_models
|
int | None
|
The minimum number of downstream models that triggers this check. |
3
|
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
models |
list[ModelNode]
|
List of ModelNode objects parsed from |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
manifest_checks:
- name: check_model_materialization_by_fanout
min_downstream_models: 5
materializations:
- incremental
- table
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_max_chained_views
#
Models cannot have more than the specified number of upstream dependents that are not tables.
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:
| Name | Type | Description | Default |
|---|---|---|---|
materializations_to_include
|
list[str] | None
|
List of materializations to include in the check. |
['ephemeral', 'view']
|
max_chained_views
|
int | None
|
The maximum number of upstream dependents that are not tables. |
3
|
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
models |
list[ModelNode]
|
List of ModelNode objects parsed from |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
manifest_checks:
- name: check_model_max_chained_views
materializations_to_include:
- ephemeral
- my_custom_materialization
- view
max_chained_views: 5
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_max_fanout
#
Models cannot have more than the specified number of downstream models.
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:
| Name | Type | Description | Default |
|---|---|---|---|
max_downstream_models
|
int | None
|
The maximum number of permitted downstream models. |
3
|
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
models |
list[ModelNode]
|
List of ModelNode objects parsed from |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
check_model_max_upstream_dependencies
#
Limit the number of upstream dependencies a model has.
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.
Prefer max_upstream_nodes
max_upstream_nodes limits the total number of upstream nodes of every resource type (models, seeds, snapshots, sources and any other node). A model cannot avoid the limit by depending on a resource type that has no limit of its own. Use the per-type parameters only when a resource type needs a stricter limit, for example max_upstream_sources: 1.
Note
If max_upstream_nodes is not set, max_upstream_models defaults to 5 and max_upstream_sources defaults to 1. If max_upstream_nodes is set, only the per-type limits you set are applied. Macros are not nodes, so max_upstream_macros always applies.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_upstream_macros
|
int
|
The maximum number of permitted upstream macros. Default: |
5
|
max_upstream_models
|
int | None
|
The maximum number of permitted upstream models. |
None
|
max_upstream_nodes
|
int | None
|
The maximum number of permitted upstream nodes of all resource types. Recommended. |
None
|
max_upstream_seeds
|
int | None
|
The maximum number of permitted upstream seeds. Default: no limit. |
None
|
max_upstream_snapshots
|
int | None
|
The maximum number of permitted upstream snapshots. Default: no limit. |
None
|
max_upstream_sources
|
int | None
|
The maximum number of permitted upstream sources. |
None
|
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
manifest_checks:
# Recommended: limit the total number of upstream nodes
- name: check_model_max_upstream_dependencies
max_upstream_nodes: 5
manifest_checks:
# A total limit, with a stricter limit for sources
- name: check_model_max_upstream_dependencies
max_upstream_nodes: 8
max_upstream_sources: 1
manifest_checks:
- name: check_model_max_upstream_dependencies
max_upstream_models: 3
max_upstream_seeds: 2
max_upstream_snapshots: 1
Source code in src/dbt_bouncer/checks/manifest/models/lineage.py
535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 | |
check_model_min_downstream_models
#
Models must be referenced by at least the specified number of downstream models.
Rationale
A model that nothing downstream references is dead weight: it still has to be built, tested, and understood on every run, but nothing consumes its output. Dead models usually accumulate after a mart is retired or a refactor leaves an intermediate model stranded. Flagging them prompts the team to either wire the model back into the lineage graph or delete it.
Downstream models and snapshots both count as consumers, since both build on top of the model. Tests and unit tests do not, as they do not make a model useful to anyone. The final layer of a project legitimately has no downstream models, so pair this check with include/exclude to scope it to the layers where a consumer is expected. To assert that final-layer models are consumed by something outside dbt, use check_model_has_exposure instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_number_of_models
|
int
|
Minimum number of models and snapshots that must reference the model. Must be greater than 0. |
1
|
Receives at execution time:
| Name | Type | Description |
|---|---|---|
model |
ModelNode
|
The ModelNode object to check. |
models |
list[ModelNode]
|
List of ModelNode objects parsed from |
snapshots |
list[SnapshotNode]
|
List of SnapshotNode objects parsed from |
Other Parameters (passed via config file):
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Description of what the check does and why it is implemented. |
exclude |
str | list[str] | None
|
Regex pattern(s) to match the model path. Model paths that match any pattern will not be checked. |
include |
str | list[str] | None
|
Regex pattern(s) to match the model path. Only model paths that match any pattern will be checked. |
language |
Literal[python, sql] | None
|
Limit check to models written in the specified language. |
materialization |
Literal[dynamic_table, ephemeral, incremental, materialized_view, table, view] | None
|
Limit check to models with the specified materialization. |
severity |
Literal[error, warn] | None
|
Severity level of the check. Default: |
Example(s):
manifest_checks:
- name: check_model_min_downstream_models
include: ^models/staging
min_number_of_models: 2