OpenParable
Skip to content
← Back to skills

Dbt Analyze

Development
dbt-analyze

Dbt Analyze is an Agent Skill for development published in the AltimateAI/altimate-code repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/AltimateAI/altimate-code/blob/HEAD/.opencode/skills/dbt-analyze/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/dbt-analyze, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

# 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

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:
ClassificationMeaningAction
BREAKINGRemoved/renamed column used downstreamMust fix before shipping
SAFEAdded column, no downstream referenceShip freely
UNKNOWNCan'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

MistakeFix
Only checking direct childrenAlways trace the FULL downstream tree recursively
Ignoring test impactsCheck which tests reference changed columns
Shipping without building downstreamAlways altimate-dbt build --model <name> --downstream
Not considering renamed columnsA rename is a break + add — downstream still references the old name

Reference Guides

GuideUse When
references/altimate-dbt-commands.mdNeed the full CLI reference
references/lineage-interpretation.mdUnderstanding lineage output