Skip to content

Quickstart

Run ZLens on a small sample dbt project and get your first result. It takes about ten minutes.

You end with:

  • the ZLens workbench open at http://127.0.0.1:3474
  • the sample DuckDB database connected
  • a notebook with your first query result
Get started with the Jaffle Shop sample The Jaffle Shop sample is already a ZLens workspace: in its folder, npm install adds ZLens and the DuckDB driver, npm run sync imports the dbt project and npm run notebook starts the workbench. Guided Setup finds the dbt project, shows the sample's DuckDB connection already configured and tested, skips the optional AI step, and a first query runs in the starter notebook.
  1. In the jaffle-shop-duckdb folder, run npm install; it installs the ZLens CLI into the folder.
  2. Run npm install --prefix .dql/connectors duckdb to install the DuckDB driver.
  3. Run npm run sync; it imports the dbt project and ends with dbt sync complete.
  4. Run npm run notebook; it prints the local URL.
  5. In the browser, Guided Setup shows the dbt project is ready.
  6. On the database step, the sample's DuckDB connection is already configured and the test has passed.
  7. Skip the optional AI step and finish setup.
  8. Open the welcome notebook, query dev.customers for the top five customers by lifetime spend, and run the cell; the result shows as a bar chart.

Before you start

You need:

  • Node.js 20 or newer (node -v)
  • Python 3.9 to 3.13, to build the sample with dbt (python3 --version)
  • git

No warehouse account, hosted service or sign-in is needed.

1. Get the sample dbt project

The sample is the Jaffle Shop dbt project on DuckDB. Clone it and build its database:

git clone https://github.com/duckcode-ai/jaffle-shop-duckdb.git
cd jaffle-shop-duckdb
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/dbt deps --profiles-dir .
.venv/bin/dbt seed --profiles-dir .
.venv/bin/dbt build --profiles-dir . --exclude resource_type:seed

You now have jaffle_shop.duckdb and target/manifest.json in the folder.

Note

The sample also has ./setup.sh, which runs steps 1 to 3 in one go once you have cloned it. Then continue at step 4.

2. Add ZLens

The sample is already a ZLens workspace: its dql.config.json is in the jaffle-shop-duckdb folder, next to dbt_project.yml. From that folder:

npm install
npm install --prefix .dql/connectors duckdb
  • npm install installs the ZLens CLI (@zlens/cli) into this folder. No global install is needed.
  • The second command installs the DuckDB driver. Other databases need their own driver; see Connect a database.

npm 12

npm 12 runs a dependency's install script only when package.json lists it in allowScripts. ZLens needs two such scripts, which download native binaries: better-sqlite3's, which the sample already allows, and duckdb's, which ZLens allows in .dql/connectors and rebuilds when npm run notebook starts.

If you ran npm install in a copy of the sample from before that, ZLens stops with "ZLens could not load better-sqlite3". Fix that folder with:

npm install-scripts approve better-sqlite3
npm rebuild better-sqlite3

Do not run create-zlens-app in the sample

npx create-zlens-app inside the sample creates a second, empty workspace in dql/, without the sample's domain, blocks, App and notebook. If you already have a dql/ folder from an older quickstart, delete it.

3. Import the dbt project

npm run sync

ZLens reads the dbt manifest and builds its index. The last line is:

✓ dbt sync complete — manifest, metadata, and agent index share the refreshed project state (… indexed object(s)).

4. Open the workbench

npm run notebook

The terminal prints Notebook ready: http://127.0.0.1:3474 and your browser opens it. Leave the terminal running.

5. Finish the guided setup

The first time, ZLens opens Guided Setup in four steps.

  1. Where does your data model live? The sample is already a ZLens project on a dbt project, so dbt project is selected, and below it, under Connect your dbt project, you see dbt project ready with the path field showing . (this folder). Click Preview. ZLens shows the models, sources and metrics it found and says Nothing has changed yet. Click Apply project, then Continue to database. (No dbt project of your own? See No dbt? Start from your database.)
  2. Connect your database. The sample's DuckDB connection is already set up: you see DuckDB · configured and Test passed. Click Continue to optional AI.
  3. Set up an AI provider. This step is optional. Ask needs a model, but notebooks, blocks, Apps and lineage do not. Set one up now (how) or click Continue to finish.
  4. Where do you want to start? Click Finish setup.

You can run the setup again later from Settings → Overview → Guided Setup.

6. Run your first query

  1. In the left rail, click Notebooks.
  2. Click New Notebook, type a name such as Customer orders, and click Create notebook.
  3. Click Create DQL query, then Switch to SQL cell.

  4. Type this query:

    select customer_name, count_lifetime_orders, lifetime_spend
from dev.customers
order by lifetime_spend desc
limit 10

  5. Press Shift+Enter.

The cell shows Success and a table of ten customers. The notebook saves itself as notebooks/customer_orders.dqlnb.

Your own dbt project

The sample ships with its ZLens workspace. For your own dbt project, create one with npx create-zlens-app@latest dql from the dbt repo; see Add ZLens to your dbt project.

No dbt?

ZLens also works straight on your database: connect it, choose the schemas to model, and ZLens drafts the entities and joins for you to certify. See No dbt? Start from your database.

Next