FAQ¶
What is ZLens?¶
An open-source analytics language, CLI, and notebook. Every analytics answer
— SQL, chart config, owner, tests, parameters — lives in a single .dql
file in git. See Concepts.
Do I need a cloud warehouse to try it?¶
No. ZLens supports local DuckDB and file queries. Install the project-local DuckDB driver, then query CSV, Parquet, or JSON files from the notebook:
npm install --prefix .dql/connectors duckdb
Databricks SQL is built in. Snowflake uses a project-local snowflake-sdk
install.
Do I need dbt?¶
No. ZLens works on a dbt project or straight on your database. Without dbt,
it reads your tables' columns, keys and comments, drafts models and joins,
and you certify them: see
No dbt? Start from your database.
npx create-zlens-app my-app --warehouse <driver> creates a database-only
project, and Guided Setup offers Database only as its first choice.
If you already use dbt, create-zlens-app auto-detects a sibling dbt
project (or takes --dbt <path>). Run dbt build, then zlens compile .,
zlens sync dbt ., and zlens agent reindex to refresh manifest metadata,
semantic metrics, lineage, and the agent index. See
Add ZLens to your dbt project.
How is this different from a Jupyter notebook?¶
| Jupyter | ZLens notebook | |
|---|---|---|
| Primary language | Python | SQL |
| Runtime | Python kernel | DuckDB (or your warehouse) |
| Chart setup | matplotlib/Plotly code | declarative, auto-rendered |
| File format | .ipynb JSON |
.dqlnb JSON |
| Git diff | noisy (outputs embedded) | clean (outputs sidecar) |
How is this different from Metabase, Looker, or Hex?¶
Those are BI tools — queries live in a database or cloud service. ZLens keeps every artifact in git. You get code review, diff, branching, and blame on your analytics. See Migrate from other tools.
What's the difference between custom and semantic blocks?¶
type = "custom"— the block's SQL executes directly against a connectiontype = "semantic"— the block references a semantic-layer metric; SQL is generated
Start with custom blocks if you're new.
Can I use ZLens from code, not just the CLI?¶
Yes. The useful entry points:
@zlens/core— parser, AST, formatter, semantic analysis@zlens/dql-compiler— IR lowering, codegen@zlens/runtime— browser runtime@zlens/connectors— database drivers
Does certification hit a real database?¶
Yes. Certify in Block Studio runs the block and its tests on your
connection before it marks the block certified. From the terminal,
zlens certify <file.dql> runs the same rules and writes nothing. See
Save and certify.
What's not in the open-source repo?¶
Hosted multi-user workspaces, governed secrets, audit logs, organization memory, approval workflows, managed alerting, regulatory governance packs, and permissions-aware team retrieval. See Compatibility.