Notebooks overview
Combine SQL queries, prose, and inline results into a document you can re-run, share, and version.
For: analysts, developers writing data reports, anyone who needs to explain what their queries do.
A QueryDeck notebook is a document made of cells. Some cells are SQL — they run against a connection and show their result below. Some cells are Markdown — they hold the prose that explains what's happening. You can re-run the SQL anytime, export the notebook to PDF or HTML, and share it.
If you've used Jupyter or Hex before, the model is familiar. The difference is that QueryDeck notebooks are SQL-first, run against your real connections, and ship as part of a native macOS app instead of a browser.
Open the notebooks panel
| Way to open | Where |
|---|---|
| Sidebar | The NOTEBOOKS section |
| Command palette | Cmd+K, type "notebook" |
| Menu | File → New Notebook |
A new notebook opens with one empty SQL cell. Add more from the + button between cells, or via the right-click menu.
When to use a notebook
| Situation | Why a notebook helps |
|---|---|
| Recurring report | Re-run the notebook weekly, results refresh in place |
| Investigation | Cells let you build up the answer step by step with notes |
| Onboarding doc | Show the new hire the queries with explanations |
| Code review | Share a notebook with stakeholders who don't run a DB client |
| Pre-meeting prep | Build the chart and the explanation, present as PDF |
Notebooks aren't a replacement for saved queries — saved queries are single queries you re-run. Notebooks are sequences with context.
Anatomy of a notebook
┌─────────────────────────────────────────────────────────┐
│ Weekly user growth Connection ▾ │
├─────────────────────────────────────────────────────────┤
│ │
│ # Weekly signups │ ← markdown cell
│ Tracking new accounts grouped by ISO week. │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ SQL [Run] │ │ ← sql cell
│ │ SELECT date_trunc('week', created_at) AS wk, │ │
│ │ COUNT(*) AS signups │ │
│ │ FROM users GROUP BY wk ORDER BY wk DESC; │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ wk signups │ │ ← result inline
│ │ 2026-05-19 142 │ │
│ │ 2026-05-12 138 │ │
│ │ 2026-05-05 127 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ + Add cell │
└─────────────────────────────────────────────────────────┘Each cell has a type (SQL or Markdown), content, and (for SQL) an optional inline result.
Cells in detail
There are two cell types:
- SQL — a SQL editor with autocomplete and a Run button. When run, the result appears inline below.
- Markdown — a text editor with a preview toggle. Supports GitHub-flavored markdown including tables and code blocks.
See Cells for keyboard navigation, autocomplete, and how cells interact with the active connection.
The connection
A notebook is associated with one connection at a time. The connection name is shown at the top of the notebook. Click to change.
When you change the connection, the schema autocomplete updates and all SQL cells lose their cached results (because they were computed against a different database). The cell text is preserved.
Running cells
Each SQL cell has a Run button (or use the keyboard inside the cell). Cells run independently — there's no "kernel state" carried between cells like in Jupyter.
To run every cell in order, use Run All in the notebook toolbar. QueryDeck runs them sequentially against the active connection. If any cell errors, execution stops there.
Run All is the right move before exporting — it makes sure every result in the notebook reflects the current database state.
Saving and loading
Notebooks save automatically as you type. They live as files on disk under:
~/Library/Application Support/QueryDeck/notebooks/Each notebook is a single .qdnb file. The format is JSON with cells, metadata, and the last cached result for each SQL cell.
To open an existing notebook, double-click the file or use File → Open Notebook. To share, copy the file. The recipient opens it in their QueryDeck, picks a connection, and re-runs.
Sharing without QueryDeck
For people without QueryDeck, export to PDF or HTML — see Export. The exported file is self-contained: prose, queries, and the result snapshots.
Versioning
Notebooks are JSON files, so they work in Git. A typical workflow:
- Create a
notebooks/folder in your project. - Save notebooks there with descriptive names (
weekly_growth.qdnb,support_metrics.qdnb). - Commit. Pull requests diff cleanly enough — added cells, edited SQL, changed prose.
We don't ship Git integration in the app yet. You manage the files yourself.