Skip to content

ZLens Tutorials

Archived page

This page was written for an earlier version of ZLens and may not match the current product. See About the archive for the current page.

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 ZLens 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 ZLens 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 zlens verify — keep dql-manifest.json reproducible and gate drift in CI.

End-to-end Example

Use duckcode-ai/jaffle-shop-duckdb when you want a complete dbt + ZLens project to explore. It is already a ZLens workspace, so you do not run create-zlens-app in it. Follow its README (or the Quickstart): build the dbt project, install ZLens into the sample's own workspace, and take the tour of its domain, certified blocks, App, lineage and Ask.

Stuck? See the troubleshooting guide.

Mental model in one paragraph

dbt models your warehouse; ZLens 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. zlens 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. zlens 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 →