---
name: dbt-analyze
description: Analyze downstream impact of dbt model changes using column-level lineage and the dependency graph. Use when evaluating the blast radius of a change before shipping. Powered by altimate-dbt.
---

# dbt Impact Analysis

## Requirements
**Agent:** any (read-only analysis)
**Tools used:** bash (runs `altimate-dbt` commands), read, glob, dbt_manifest, lineage_check, dbt_lineage, sql_analyze, altimate_core_extract_metadata

## When to Use This Skill

**Use when the user wants to:**
- Understand what breaks if they change a model
- Evaluate downstream impact before shipping
- Find all consumers of a model or column
- Assess risk of a refactoring

**Do NOT use for:**
- Creating or fixing models → use `dbt-develop` or `dbt-troubleshoot`
- Adding tests → use `dbt-test`

## Workflow

### 1. Identify the Changed Model

Accept from the user, or auto-detect:
```bash
# From git diff
git diff --name-only | grep '\.sql$'

# Or user provides a model name
altimate-dbt compile --model <name>    # verify it exists
```

### 2. Map the Dependency Graph

```bash
altimate-dbt children --model <name>    # direct downstream
altimate-dbt parents --model <name>     # what feeds it
```

For the full downstream tree, recursively call `children` on each downstream model.

### 3. Run Column-Level Lineage

**With manifest (preferred):** Use `dbt_lineage` to compute column-level lineage for a dbt model. This reads the manifest.json, extracts compiled SQL and upstream schemas, and traces column flow via the Rust engine. More accurate than raw SQL lineage because it resolves `ref()` and `source()` to actual schemas.

```
dbt_lineage(model: <model_name>)
```

**Without manifest (fallback):** Use `lineage_check` on the raw SQL to understand:
- Which source columns flow to which output columns
- Which columns were added, removed, or renamed

**Extract structural metadata:** Use `altimate_core_extract_metadata` on the SQL to get tables referenced, columns used, CTEs, subqueries — useful for mapping the full dependency surface.


### 4. Cross-Reference with Downstream

For each downstream model:
1. Read its SQL
2. Check if it references any changed/removed columns
3. Classify impact:

| Classification | Meaning | Action |
|---------------|---------|--------|
| **BREAKING** | Removed/renamed column used downstream | Must fix before shipping |
| **SAFE** | Added column, no downstream reference | Ship freely |
| **UNKNOWN** | Can't determine (dynamic SQL, macros) | Manual review needed |

### 5. Generate Impact Report

```
Impact Analysis: stg_orders
════════════════════════════

Changed Model: stg_orders (materialized: view)
  Columns: 5 → 6 (+1 added)
  Removed: total_amount (renamed to order_total)

Downstream Impact (3 models):

  Depth 1:
    [BREAKING] int_order_metrics
      Uses: total_amount → COLUMN RENAMED
      Fix: Update column reference to order_total

    [SAFE] int_order_summary
      No references to changed columns

  Depth 2:
    [BREAKING] mart_revenue
      Uses: total_amount via int_order_metrics → CASCADING
      Fix: Verify after fixing int_order_metrics

Tests at Risk: 4
  - not_null_stg_orders_order_total
  - unique_int_order_metrics_order_id

Summary: 2 BREAKING, 1 SAFE
  Recommended: Fix int_order_metrics first, then:
  altimate-dbt build --model stg_orders --downstream
```

## Without Manifest (SQL-Only Mode)

If no manifest is available:
1. Run `lineage_check` on the changed SQL
2. Show column-level data flow
3. Note: downstream impact requires a manifest
4. Suggest: `altimate-dbt build` to generate one

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Only checking direct children | Always trace the FULL downstream tree recursively |
| Ignoring test impacts | Check which tests reference changed columns |
| Shipping without building downstream | Always `altimate-dbt build --model <name> --downstream` |
| Not considering renamed columns | A rename is a break + add — downstream still references the old name |

## Reference Guides

| Guide | Use When |
|-------|----------|
| [references/altimate-dbt-commands.md](references/altimate-dbt-commands.md) | Need the full CLI reference |
| [references/lineage-interpretation.md](references/lineage-interpretation.md) | Understanding lineage output |