Skip to content

DQL Tutorials

Hands-on walkthroughs that take you from a plain dbt project to certified blocks, dashboards in an App, agent answers, and a CI gate.

Every tutorial works on your own dbt repo. If you don't have one handy, the duckcode-ai/jaffle-shop-duckdb repo is a Jaffle Shop dbt + DuckDB project that already ships a fully-built DQL workspace (10 certified blocks + an executive App dashboard) — clone it, ./setup.sh, then cd dql && npm install && npm run notebook to explore a finished result, and follow its dql/TUTORIAL.md for a guided tour.

Reading order

  1. 01 — Getting started — add DQL to a dbt repo, sync the dbt DAG, open the notebook.
  2. 02 — Authoring blocks — write a certified block on top of a dbt model: SQL, metadata, tests, the certification gate.
  3. 03 — Dashboards & Apps — compose certified blocks into a dashboard page inside an App.
  4. 04 — Agentic analytics — the knowledge graph, governed agent answers, the uncertified → certified promotion loop, and the MCP server.
  5. 05 — CI and dql verify — keep dql-manifest.json reproducible and gate drift in CI.

Stuck? See the troubleshooting guide.

Mental model in one paragraph

dbt models your warehouse; DQL governs what happens after. Analysts author certified .dql blocks (SQL + governance metadata + tests) on top of dbt models. Apps bundle dashboard pages and notebooks into a consumption surface for a domain. dql compile writes dql-manifest.json, which powers lineage (source → dbt model → block → dashboard → App), the local knowledge graph, and the agent: it retrieves certified blocks first; if nothing matches, an LLM proposes SQL marked Uncertified that analysts review and certify back into blocks. dql verify keeps the manifest in lock-step with source so CI can gate changes.

If you'd rather skim the architecture first, jump to ../architecture/overview.md.

Conventions

  • Code blocks fenced with bash are commands you run; the prompt is implied.
  • Code blocks fenced with text are screen output you should see.
  • File-content blocks are labelled with their path as a comment on the first line so you can copy them as-is.
  • "You should see" boxes describe the expected outcome of a step. If you don't see it, jump to the troubleshooting guide.

Ready? Start with tutorial 01 →