DQL

A local-first dbt analytics workspace. Git-native. Certified blocks, Apps, lineage, and governed agent answers run on your laptop.

DQL sits between dbt (modeling) and your BI tool (reporting). Every analytics answer — SQL, chart, params, tests, owner — lives in a single .dql file tracked in git. No more query sprawl, no more broken charts, no more lost work.

Highlights

OSS Apps for decision work — package dashboard pages, notebooks, AI pins, drafts, and certified blocks into local-first App folders that stay in git.

Block Studio with certified blocks — every block carries owner / domain / tags / llmContext / tests, and shows its certification status inline.

Full-stack lineage — Domain → App → Dashboard → Block → metric → dbt model → source, rendered as an interactive React Flow + dagre graph.

AI chat + provider setup — configure OpenAI, Gemini, local Ollama, custom OpenAI-compatible endpoints, Slack, and schedule delivery keys from one Settings surface; missing keys stay optional until selected.

Get started — under 2 minutes

Docker (recommended — zero local toolchain)

git clone https://github.com/duckcode-ai/dql.git && cd dql
docker compose up

Notebook on http://127.0.0.1:3474. The working directory is mounted at /workspace inside the container. When you run this from the DQL framework repo, Docker automatically creates and opens the bundled Acme Bank starter at .dql/docker-starter/acme-bank; real DQL project folders with dql.config.json open directly. Add --profile slack for the Slack bot or --profile ollama for a local LLM daemon.

npm (Node 20+ already installed)

npx create-dql-app@latest my-project
cd my-project
npm install
npm run notebook

The starter installs the DQL CLI locally as a dev dependency, so npm run notebook, npm run compile, and other scripts work without a global dql binary. Use --template acme-bank for the full Apps, lineage, and agent demo.

Either way, DuckDB runs in-memory. Drop a CSV into data/, query it, save a block, commit.

Already have a dbt project? Keep dbt as the modeling source of truth and keep DQL isolated under ./dql inside that repo:

npm i -D @duckcodeailabs/dql-cli
npx dql init ./dql
dbt build
npx dql compile ./dql
npx dql sync dbt ./dql
npx dql notebook ./dql

The generated dql/dql.config.json points back to the parent dbt project, so lineage can connect dbt sources/models to DQL blocks, dashboards, and Apps. In Block Studio, start from a dbt model for SQL blocks, a dbt semantic metric for semantic blocks, or a one-time SQL import wizard for legacy queries.

Official demos

• Acme Bank — bundled OSS workflow demo for certified blocks, Apps, dashboard pages, notebooks, lineage, agent answers, and local schedules.
• Jaffle Shop DQL — step-by-step dbt/MetricFlow demo for manifest ingestion, semantic metrics, lineage, certified blocks, Apps, tutorials, and agent routing: github.com/duckcode-ai/jaffle-shop-dql.

DQL OSS is a single-user local workspace. Hosted multi-user governance, managed secrets, audit logs, approval workflows, and permissions-aware team retrieval belong to the commercial product.

Documentation

All docs live in docs/ — plain markdown, rendered on github.com. Start with docs/README.md.

Quick links:

• Tutorials — Acme Bank end-to-end (Apps, certified blocks, agentic analytics, Slack, fraud-spike walkthrough)
• Quickstart · Concepts · Install
• Jaffle Shop walkthrough · Import dbt · Block Studio · Author a block
• CLI reference · Language reference · Connectors
• Architecture · Contributing

What's in the box

• Notebook — SQL + DQL cells with live results, charts, and params
• Block Studio — governed, versioned analytics blocks with lint + certify
• Apps — first-class consumption-layer artifact bundling dashboard pages, notebooks, AI pins, drafts, local metadata, and schedules for a domain or use case
• Local policy + RLS preview — optional single-user preview path for commercial governance patterns; @rls("col", "{user.var}") resolves at execution time from the active local persona when configured
• Agentic analytics (new in v1.4) — @duckcodeailabs/dql-agent ships a local SQLite + FTS5 knowledge graph, Skills, a block-first answer loop, and pluggable LLM providers (Claude / OpenAI / Gemini / local Ollama)
• MCP server — 10 tools (search_blocks, get_block, query_via_block, list_metrics, list_dimensions, lineage_impact, certify, suggest_block, kg_search, feedback_record)
• Slack front-end (new in v1.4) — dql slack serve runs a slash-command bot answering via the same block-first loop, with feedback buttons that feed self-learning
• dql verify (new in v1.4) — proves dql-manifest.json is reproducible from source for CI gates
• Semantic layer — import dbt metrics/dimensions; author your own
• Lineage DAG — Domain · App · Dashboard · Block · metric · dbt model · source granularity with impact analysis
• Git-native format — canonical .dql serialization, dql diff, in-app git panel
• 15 connectors — Postgres, DuckDB, Snowflake, BigQuery, Redshift, MySQL, and more
• VS Code extension — syntax, snippets, LSP (code --install-extension dql.dql-language-support)

What this repo does not include

Real authentication (login screens, OIDC, password storage), hosted/multi-tenant deployment, enforced organization RBAC, governed secrets, audit logs, and managed approval workflows live outside OSS. Local persona/policy preview, agentic block generation, MCP runtime, and scheduled runs are included in OSS.

Contributing

See CONTRIBUTING.md and docs/contribute/repo-layout.md. Bugs and feature requests: open an issue.

License

Apache-2.0.