Skip to content

README.md

Latest commit

 

History

History
63 lines (49 loc) · 2.87 KB

README.md

File metadata and controls

63 lines (49 loc) · 2.87 KB
Raw

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. The DQL repo stays product-focused; the complete worked example lives in the separate duckcode-ai/jaffle-shop-duckdb repo.

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.

End-to-end Example

Use duckcode-ai/jaffle-shop-duckdb when you want the full DataLex + DQL flow with concrete files, screenshots, and video planning:

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 →