Notebook cells

SQL cells, Markdown cells, keyboard navigation, and how the active connection threads through everything.

For: analysts and developers.

A notebook is a list of cells. Each cell is either SQL or Markdown. This page explains how to work with them efficiently.

Cell types

Type	What goes in it	What it shows
SQL	One SQL statement (or several, separated by `;`)	The result of running the query against the active connection
Markdown	Prose, headings, lists, tables, code blocks, links	Rendered output in preview mode

There's no chart cell or Python cell. If you want a chart, export the data to CSV and chart it in your tool of choice, or embed an image in a Markdown cell.

Add a new cell

Click the + button between any two cells.
Use the keyboard: Cmd+Shift+A to add a SQL cell below, Cmd+Shift+M for Markdown.
Right-click any cell → Add cell below (same type) or pick a type.

Move and delete

Action	How
Move up	Drag the cell handle, or `Cmd+Option+Up`
Move down	Drag, or `Cmd+Option+Down`
Duplicate	Right-click → Duplicate, or `Cmd+D` while focused on the cell
Delete	Click the trash icon, or `Cmd+Backspace`

A confirmation appears for cells that contain content. Empty cells delete without prompting.

SQL cells

Autocomplete

The SQL editor inside a cell behaves identically to the main query editor: table and column suggestions scoped to the FROM/JOIN clause, keyword completion, and bracket matching.

The completion is scoped to the notebook's active connection, not whatever connection you have open in the main window.

Running

Each SQL cell has a Run button in its top-right corner. Click to execute.

Inside a SQL cell, the keyboard is:

Action	Shortcut
Run this cell	`Cmd+Return`
Run this cell and move to next	`Cmd+Shift+Return`
Run all cells in the notebook	`Cmd+Option+Return` (or `Run All` in the toolbar)
Cancel running cell	`Cmd+.`

The result appears below the cell in a compact data grid. The grid is the same as elsewhere in QueryDeck — sort columns by clicking headers, copy cells, copy as INSERT.

Result options

The toolbar above the result lets you change how it's displayed:

Option	Effect
Table	Default. Compact rendering.
JSON	Render the result as a JSON code block. Useful for documents that will be exported and read.
Hide	Don't render the result. Useful for cells that exist only to side-effect (like a `SET TIMEZONE`).

Caching

When a SQL cell finishes, the result is cached with the notebook. Reopening the notebook later shows the cached result without re-running.

To refresh a cell, click Run again. The cached result is replaced.

To refresh every cell in order, Run All.

Markdown cells

Edit and preview

A Markdown cell has two modes: edit and preview. Toggle with Cmd+E while focused on the cell.

In edit mode, you're typing markdown. In preview mode, the rendered output is shown and the source is hidden.

Supported syntax

QueryDeck renders GitHub-flavored markdown:

Syntax	Result
`# Heading`	Heading (levels 1-6)
`bold`, `italic`, `~~strike~~`	Inline formatting
Lists, ordered and unordered	Standard rendering
Tables with `\|` separators	HTML tables
`inline code` and triple-backtick blocks	Monospace
Fenced code with language	Syntax highlighting (SQL, JSON, TypeScript, Python, etc.)
`[link](url)`	Clickable in preview
`![image](url)` or `![image](file.png)`	Inline image
`> blockquote`	Indented quote

For images:

External URLs work in the app and stay as URLs in exports.
Local file paths are embedded in PDF and HTML exports so the file is self-contained.

Linking to specific cells

When you reference a SQL cell from a Markdown cell, use a relative anchor like "the query below" or "the result above". Cell-specific anchors aren't a thing yet — vote via the feedback button.

Cell selection

Click anywhere on a cell to focus it. The focused cell has a colored left border.

Multi-select:

Cmd+click to add a cell to the selection.
Shift+click to select a range.

With multiple cells selected:

Delete removes them all.
Cmd+C copies the selection (text only).
Move keys move the whole group.

The connection swap

When you change the notebook's active connection from the dropdown at the top:

Every SQL cell's cached result is invalidated (because it came from a different database).
The autocomplete index switches to the new schema.
The cell text is not changed.

To re-run against the new connection, click Run All.

If the new connection doesn't have a table your SQL cell references, the cell will error on run. The cell text stays — you can edit and re-run.

Read-only cells

For long-form documentation cells, you can lock a Markdown cell to prevent accidental edits: right-click → Lock cell. Click Unlock to edit again. Locked cells render normally and export normally.

SQL cells can't be locked (defeats the purpose) but their connection scope can be restricted — pin a SQL cell to a specific connection via the right-click menu, even if the notebook's active connection changes.

What's next

Overview for the conceptual model
Export — PDF, HTML, .ipynb
Query editor — same behavior as inside cells, with more keyboard options

Notebook cells

On this page