/using-dbt-for-analytics-engineering

Evaluating Impact of a dbt Model Change

Assess downstream dependencies before modifying a dbt model. Determines scope of impact and recommends appropriate build selectors.

When to Use

• Before changing SQL logic in an existing model
• Before renaming, removing, or changing column types
• Before changing model materialization

Not for: New models (no downstream dependencies yet)

Workflow

flowchart TD
    A[Identify model to change] --> B{MCP tools available?}
    B -->|yes| C[Use get_model_lineage_dev]
    B -->|no| D[Use dbt ls --select model+]
    C --> E[Assess impact scope]
    D --> E
    E --> F{Column-level change?}
    F -->|yes| G[Check column lineage]
    F -->|no| H[Classify impact]
    G --> H
    H --> I{High impact?}
    I -->|yes| J[Ask user: limit depth?]
    I -->|no| K[Recommend build command]
    J --> K

Getting Downstream Dependencies

If dbt MCP Server Available

Check for these tools first - they provide richer lineage data:

CLI Fallback (Worse data but always available)

List all downstream models:

dbt ls --select model_name+ --output name

Count downstream models:

dbt ls --select model_name+ --output name | wc -l

View as JSON with details:

dbt ls --select model_name+ --output json

Column-Level Impact

When changing or removing a column, identify which downstream models reference it:

# Search for column references in downstream model SQL files
# First get the list of downstream models
dbt ls --select model_name+ --output name > /tmp/downstream.txt

# Then search for column usage in those model files
grep -r "column_name" models/ --include="*.sql" | grep -f /tmp/downstream.txt

With MCP tools, use get_column_lineage for precise tracking.

Impact Classification

Recommending Build Commands

Standard (all downstream):

dbt build --select state:modified+

Limited depth (user choice):

# Only 1 level downstream
dbt build --select state:modified+1

# Only 2 levels downstream
dbt build --select state:modified+2

# Only 3 levels downstream
dbt build --select state:modified+3

When impact is high, ask the user:

"This change affects N downstream models. Do you want to:

1. Build all downstream models with state:modified+
2. Limit to a specific depth (e.g., state:modified+2 for 2 levels)?"

Quick Reference

Common Mistakes

Not checking before changing - Always run impact assessment first, even for "small" changes.

Ignoring column-level impact - Removing a column breaks downstream models that reference it. Check column usage, not just model dependencies.

Building everything - Use --select to limit scope. Never run dbt build without selectors on large projects.