01 — Getting started¶

Who this is for: anyone adding DQL to a dbt project for the first time.

What you'll do: add a DQL workspace to a dbt repo, sync the dbt DAG, open the notebook, and see end-to-end lineage.

Time: 10 minutes.

Prerequisites¶

Node.js 20 or 22 LTS (check: node --version)
git (any modern version)
A dbt project — yours, or the example repo below
Optional for tutorial 04: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or a local Ollama server.

Step 1 — Pick your dbt repo¶

Your own repo: make sure the manifest is fresh, then continue to Step 2:

cd your-dbt-repo
dbt parse         # or dbt build — either writes target/manifest.json

No repo handy? Clone the example — a standard dbt + DuckDB project (the classic Jaffle Shop), fully local:

git clone https://github.com/duckcode-ai/jaffle-shop-duckdb.git
cd jaffle-shop-duckdb
./setup.sh        # creates a venv, runs dbt seed + dbt build + docs generate

You should see dbt build all models into jaffle_shop.duckdb at the repo root, and target/manifest.json written.

Note: the example repo already ships a finished DQL workspace in dql/. To follow this tutorial and build one from scratch, scaffold into a new folder (the commands below use dql-tutorial so it won't collide), or just explore the existing dql/ and its dql/TUTORIAL.md instead.

Step 2 — Scaffold the DQL workspace¶

From the dbt repo root (use dql on your own repo; on the example repo use dql-tutorial to avoid the shipped dql/ folder):

npx create-dql-app@latest dql-tutorial
cd dql-tutorial
npm install

You should see detected sibling dbt project at … during scaffolding — the generated dql.config.json is wired back to the parent dbt project. DQL stays isolated under its own folder; your dbt files are untouched.

Point the default connection at the dbt warehouse. For the example repo, edit dql.config.json:

"connections": {
  "default": {
    "driver": "duckdb",
    "filepath": "../jaffle_shop.duckdb"
  }
}

(On your own repo, use your warehouse driver instead — DQL ships 15 connectors; see connect-warehouse.)

Step 3 — Check the setup¶

npm run doctor

You should see green checks for Node version, project config, directories, the default connection, and the dbt project, plus the next commands for the local workflow.

Step 4 — Sync the dbt DAG¶

npm run sync

You should see dbt sources and models imported into the DQL manifest — for the example repo, the staging and marts models (orders, customers, products, …) with their upstream edges.

Step 5 — Open the notebook¶

npm run notebook

The CLI starts a local server on http://127.0.0.1:3474 and opens the browser UI. Open notebooks/welcome.dqlnb and run a cell against a dbt model:

SELECT date_trunc('month', ordered_at) AS month,
       SUM(order_total)                AS revenue
FROM dev.orders
GROUP BY 1 ORDER BY 1

You should see real rows from the dbt-built warehouse. (dev is the schema the example repo's dbt profile writes to — substitute your own schema on your repo.)

Step 6 — See the lineage¶

Click Lineage in the activity bar.

You should see the imported dbt DAG: seeds/sources flowing into staging models into marts. As you add blocks, dashboards, and Apps in the next tutorials, they appear downstream of the dbt models they read — the full source → dbt model → block → dashboard → App graph.

What you now have¶

A DQL workspace living inside a dbt repo (./dql), tracked in git
The dbt DAG imported into dql-manifest.json
A running local notebook querying the dbt warehouse
Lineage from sources through dbt models

Continue to tutorial 02 — Authoring blocks →