dbt-graphify

Parse a dbt manifest.json into a graphify-queryable knowledge graph. Ask AI questions about your dbt lineage without reading hundreds of SQL files.

dbt manifest.json  ──►  dbt-graphify  ──►  graphify-out/graph.json
                                                    │
                              ┌─────────────────────┤
                              ▼                     ▼
                    graphify query              graph.html
                  "what breaks if I            (interactive
                  change stg_orders?"           D3 viewer)

Why

Graphify can't read dbt projects directly — Jinja2 SQL ({{ ref('model') }}) breaks its extractor, and it doesn't understand dbt's layer semantics (staging → intermediate → mart). The result is a noisy, incomplete graph that costs more tokens to query than just grepping the files.

dbt already computes the perfect graph in manifest.json. This tool reshapes it into the format graphify expects, with zero LLM calls.

Installation

pip install dbt-graphify

# With topology-based community detection (recommended):
pip install "dbt-graphify[clustering]"

# With YAML source description parsing:
pip install "dbt-graphify[yaml]"

# Everything:
pip install "dbt-graphify[all]"

No runtime dependencies without extras — stdlib only.

Usage

# Auto-detect manifest.json in standard dbt locations
dbt-graphify

# Explicit manifest path
dbt-graphify path/to/target/manifest.json

# Custom output directory
dbt-graphify --out /tmp/my-graph

# Skip graph.html generation
dbt-graphify --no-html

# Module form (no install required)
python -m dbt_graphify

Watch mode

Keep the graph in sync as you work. Run this in one terminal:

dbt-graphify --watch                                   # auto-detect manifest
dbt-graphify . --watch                                 # explicit directory
dbt-graphify path/to/target/manifest.json --watch      # specific file

In another terminal, run dbt as usual:

dbt compile   # or dbt run, dbt build, dbt parse

Every time dbt regenerates manifest.json, the graph rebuilds automatically — no manual re-runs. Press Ctrl-C to stop watching.

The graph depends entirely on manifest.json (a dbt artifact, typically gitignored), not on source file commits, so watch mode is the right way to keep it current during active development.

Fallback: no compiled manifest

If manifest.json is empty (dbt not compiled), the tool falls back to graph_summary.json, which dbt writes even during dbt parse:

cd your-dbt-project/
dbt parse               # fast, no DB connection needed
dbt-graphify            # auto-finds target/graph_summary.json

Output

All files written to graphify-out/ (or --out dir):

Querying with graphify

After running dbt-graphify, use graphify to query the graph:

graphify query "which models depend on stg_customers?"
graphify query "trace the full lineage of orders_mart"
graphify query "what breaks if I change stg_payments?"
graphify path "raw_orders" "revenue_report"
graphify explain "int_order_metrics"

Claude Code integration

Install the graphify skill and run /dbt-graphify to regenerate the graph, then use /graphify query for any lineage question:

graphify install claude   # installs the graphify skill + hook

After that, any graphify query or graphify path command in Claude Code will use the knowledge graph instead of reading raw SQL files — typically 70–90% fewer tokens per question.

Node structure

Each node in graph.json carries these flat fields (readable by graphify query):

Community detection

Communities are assigned via this priority chain so the tool works on any dbt project, not just a specific domain:

1. dbt group — if your models use dbt groups, each group becomes a community
2. dbt tags — first tag on each model becomes the community
3. Topology clustering — Louvain modularity on the DAG (requires pip install "dbt-graphify[clustering]")
4. Layer fallback — source / staging / intermediate / mart / seed (always available)

Blast-radius analysis

lineage.json contains full ancestor and descendant maps computed via BFS:

import json

with open("graphify-out/lineage.json") as f:
    lineage = json.load(f)

# Everything downstream of stg_customers
affected = lineage["descendants"]["model.my_project.stg_customers"]
print(f"Changing stg_customers breaks: {affected}")

Requirements

• Python ≥ 3.9
• A dbt project with dbt compile or dbt parse run (produces target/manifest.json or target/graph_summary.json)
• graphify (pip install graphifyy) for graph.html and query CLI — optional but recommended

License

MIT