dbt-lens 0.3.0

CLI tool for navigating and understanding dbt projects

dbt-lens

CLI tool for navigating and understanding dbt projects. Read your manifest.json and get instant answers about impact, lineage, and project health — no warehouse connection required.

Install

pip install dbt-lens

Quick Start

# Generate your manifest first
dbt compile

# See what breaks if you change a model
dbt-lens impact stg_orders

# Trace a column back to its source
dbt-lens trace mrt_daily_revenue.gross_revenue

# Git-aware blast radius
dbt-lens diff

# Project health report
dbt-lens health

Commands

Navigation

Command	Description
impact <model>	Show downstream models/tests affected by a change
upstream <model>	Trace a model back to its sources
find <query>	Fuzzy search across models, columns, macros

Column Lineage

Command	Description
trace <model.column>	Trace a column's lineage back through upstream models to its source
explain <model>	Auto-generated model summary: sources, joins, filters, aggregations

Git Integration

Command	Description
diff	Git-aware impact analysis — changed files → downstream blast radius → dbt selector
macro-impact <macro>	Show all models affected by a macro, including transitive macro chains

Project Health

Command	Description
health	Test coverage, documentation gaps, model size warnings, source freshness

Global Options

Option	Default	Description
--manifest PATH	target/manifest.json	Path to manifest.json
--format terminal|json	terminal	Output format
--dialect DIALECT	auto-detect	sqlglot dialect override (bigquery, snowflake, postgres)

Examples

Impact analysis

$ dbt-lens impact stg_orders

stg_orders (staging | view)
├── int_orders_enriched (intermediate | view)
│   └── dim_order (dimension | table) ← 2 tests
│       └── mrt_order_summary (mart | table) ← 1 test
└── ...

 5 models affected │ 3 tests │ 3 layers deep

Column trace

$ dbt-lens trace mrt_order_summary.customer_name

mrt_order_summary.customer_name
  <- dim_customer.name
    <- stg_customers.name
      <- customers.name

Diff

$ dbt-lens diff

 Modified files (vs main):
  models/staging/stg_orders.sql

 Blast radius:
  stg_orders → 5 downstream models, 3 tests

 Total: 5 unique models affected

 Suggested selector:
  dbt build -s stg_orders+

Macro impact

$ dbt-lens macro-impact filter_test_emails

 Macro chain:
  filter_test_emails
  └── filter_and_validate_emails (depends on filter_test_emails)

 Models using this chain (direct + transitive): 2
  dimension:    2

Requirements

• Python >= 3.9
• dbt-core >= 1.4 (manifest v7+)
• No warehouse connection needed — reads manifest.json only

License

MIT