// 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.
| 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. |
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
Use when the user wants to:
Do NOT use for:
dbt-develop or dbt-troubleshootdbt-testAccept from the user, or auto-detect:
# From git diff
git diff --name-only | grep '\.sql$'
# Or user provides a model name
altimate-dbt compile --model <name> # verify it exists
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.
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:
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.
For each downstream model:
| 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 |
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
If no manifest is available:
lineage_check on the changed SQLaltimate-dbt build to generate one| 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 |
| Guide | Use When |
|---|---|
| references/altimate-dbt-commands.md | Need the full CLI reference |
| references/lineage-interpretation.md | Understanding lineage output |
REQUIRED before writing or modifying ANY dbt model. Invoke this skill FIRST whenever a task says "create", "build", "add", "modify", "update", "fix", or "refactor" a dbt model, staging file, mart, incremental, or snapshot. Skipping this skill is the leading cause of silent-correctness bugs — models that compile and `dbt build` cleanly but produce wrong values. It contains the patterns that prevent the most common such bugs encountered in real dbt projects: • Incremental high-water marks (`>=` vs `>` ties → silent row dropout) • Snapshot strategy selection (timestamp vs check, `unique_key` choice) • `LEFT JOIN + COUNT(*)` phantom rows from unmatched parents • Type harmonization in `COALESCE` / `CASE` / `UNION` legs • Date-spine completeness (every period present, even empty ones) • Off-by-one window boundaries (`BETWEEN d - (N-1) AND d` for N-wide) • Uniqueness enforcement when schema implies a key • Window-function `LIMIT` with deterministic tiebreaker • Verifying transformation correctness with dbt unit te
REQUIRED after building or modifying ANY dbt model that has columns declared in `schema.yml` / `_models.yml`. Run `altimate-dbt schema-verify --model <name>` to diff actual columns against the spec, and treat any `mismatch` verdict as "not done." The most common reason "the build is green but the tests still fail" is that the model produces the right *data values* in the wrong *column shape* — extra columns, missing columns, wrong order, wrong types. Many dbt equality tests grade the column tuple `(name, type, position)` exactly, and the agent's prior bias is to add "helpful" extras (`p1`/`p2`/`p3` rank breakdowns, name-resolved variants, lineage metadata) or reorder columns "more logically." Both break the contract. This skill enforces the mechanical check that catches those bugs before declaring done. Use it before declaring any model task complete.
Generate dbt unit tests automatically for any model. Analyzes SQL logic (CASE/WHEN, JOINs, window functions, NULLs), creates type-correct mock inputs from manifest schema, and assembles complete YAML. Use when a user says "generate tests", "add unit tests", "test this model", or "test coverage" for dbt models.
Validate that two tables or query results are identical — or diagnose exactly how they differ. Discover schema, identify keys, profile cheaply, then diff. Use for migration validation, ETL regression, and query refactor verification.
Add schema tests, unit tests, and data quality checks to dbt models. Use when validating data integrity, adding test definitions to schema.yml, writing unit tests, or practicing test-driven development in dbt. Powered by altimate-dbt.
Document dbt models and columns in schema.yml with business context — model descriptions, column definitions, and doc blocks. Use when adding or improving documentation for discoverability. Powered by altimate-dbt.