dbt Wizard: an AI agent that actually understands your dbt project

By now, data and software professionals of all kinds are familiar with the power of AI copilots and assistance. It has never been easier to write software, including for data engineering.

However, the power of foundation models cannot substitute for context. For data transformation and modeling, context includes lineage, tests, contracts, semantic definitions, dependencies, and the meaning of terms like “revenue” in a given project. In short, without proper context, generic models will not understand the project they are working on and will fail, hallucinating and causing conflicting metrics, bad refactors, broken models, and wasted review cycles.

dbt Wizard is an AI agent fine-tuned specifically to understand and work on dbt projects. It accompanies dbt out of the box, is compatible with any foundation model, follows dbt formatting and guidelines, performs dbt-specific actions, and produces much more usable, more accurate output than a generic coding assistant. It is designed specifically to help analytics engineers already using dbt accelerate development with less risk (and token usage). 

[CTA_MODULE]

How dbt Wizard works

At a basic level, dbt Wizard loads a team’s full dbt project metadata as context, such as:

• Models
• Descriptions
• DAG/lineage
• Contracts
• Tests
• Semantic definitions
• Dev schema configurations

Instead of trying to guess or infer the shape and constraints of an analytics engineering project from a prompt or file attachment, it reads them directly from the dbt project. dbt Wizard includes validation behaviors such as compile checks, dbt build commands, testing, and parsing, ensuring that the output is auditable, governed, and correct.

dbt Wizard can be invoked in the dbt platform from the “dbt Wizard” home tab, or from the command line for dbt Core using the command dbt-wizard. From there, you can treat dbt Wizard like a chatbot, asking basic questions such as “What does this project do?” or “How can I optimize this project?” The agentic aspect is entrusting it with actions, such as “add documentation to my project” or “Build a new model to compute a payments metric.” dbt Wizard knows when to use the appropriate tools.

What can you do with dbt Wizard?

The central promise of dbt Wizard is to provide a conversational interface for shipping data products faster without breaking anything downstream. In practice, this encompasses the following kinds of tasks:

1. Refactor across files: Rename models and fields and expect references to update accordingly
2. Update models at scale: Write SQL, tests, and documents all together
3. Migration and modernization: Readily translate legacy logic into dbt models, tests, and docs in a single pass
4. Impact analysis and safe change management: Programmatically determine what breaks if a model, contract, or semantic definition changes
5. Enhance the semantic layer: Add or modify metrics and dimensions with the full project context
6. Build asynchronous analytics agents: Set up custom agents around your dbt projects

dbt Wizard accelerates the full range of analytics engineering tasks performed in dbt.

How dbt Wizard compares with generic coding assistants

I made a series of simple requests, beginning with “Create a dbt model to compute monthly number of 1M dollar ARR customers,” to both dbt Wizard and Claude Code, and observed the following differences.

1. BM25 metadata search over the full DAG instead of grep

dbt Wizard called mcp__dbt_index__search to find ARR-related models by semantic

relevance across node names, descriptions, and unique IDs. A vanilla agent would grep -r "ARR" across 1,200+ SQL files and get ~90 matches requiring manual triage. The index search returned a ranked list immediately and included grain, schema, and path for each hit without opening a single file.

2. describe returned grain, lineage, and compiled SQL in one call

mcp__dbt_index__describe node=revenue told me the model's grain (account_id, month), its four downstream consumers, and its compiled SQL, all without reading the file. A vanilla agent would have to open revenue.sql, then chase the select * to revenue_history_daily, then to revenue_history_daily_source, accumulating context across multiple file reads with no structural guide.

3. Traced the right ARR column through four layers of indirection efficiently

revenue exposes ~80 columns, many named *_arr*. Knowing the DAG structure (from describe + lineage) meant I could follow the exact inheritance chain:

1. revenue.sql → select * except(...) from revenue_history_daily
2. revenue_history_daily → revenue_history_daily_source ‍
3. revenue_history_daily_source → column overrides dict confirmed‍
4. mar_based_arr_with_current_month_projection_scaled as the canonical field
5. Cross-checked against arr_change_classification (a sibling BI model) to confirm it uses the same field as account_arr

Without DAG traversal tools, a vanilla agent would likely have picked arr_legacy (most literally named) or revenue (monthly billed revenue, not ARR), both wrong.

4. Knew revenue had 4 downstream consumers before touching anything

mcp__dbt_index__describe showed revenue's children upfront. That immediately ruled out modifying revenue directly and confirmed a new model was the right approach. A vanilla agent has no way to get this without running grep -r "ref('revenue')" and manually counting results. Even then, it would have no severity or blast-radius context.

5. Resolved accounts ambiguity without crashing

describe node=accounts returned an ambiguity error: both a model and a source share the name. Wizard handled this by falling back to reading the SQL file directly. A vanilla agent would either guess the wrong one or halt and ask the user to disambiguate. Neither is acceptable mid-task.

6. Spawned a typed validation agent that ran real warehouse queries

Instead of self-attesting correctness, Wizard spawned a validation subagent that:

• Ran dbt run --defer against the dev warehouse
• Queried the materialized table: 103 rows, 103 distinct months, no duplicates
• Verified sum_arr >= cnt * 1,000,000 for every row
• Confirmed no join fan-out from the accounts join

The subagent's recommendation (add not_null + unique tests on month) was applied before the session closed. A vanilla agent cannot do any of this, lacking the mechanisms to run dbt, query a warehouse, or delegate to a specialized validation role.

The bottom line is that analytics engineering is fundamentally too context-heavy for generic AI to do safely and well. dbt Wizard accesses this context and guarantees usable and more accurate output.

[CTA_MODULE]