Notebooks

Several queries in order, with their results kept together — for the questions where one answer depends on the last.

Read time: 4 min
Sections: 4

What a notebook is for

A saved query answers one question. A notebook answers a sequence of them: pull a cohort, then look at what that cohort did, then check whether the numbers reconcile. Each step is its own cell, and the results stay side by side instead of in three browser tabs.

Notebooks are for investigation, not for delivery. When a result is worth sending on a schedule, it belongs in a report.

Cells

A notebook is an ordered list of cells. A SQL cell runs against a connection and shows a result grid; a text cell holds prose — what you were checking and what you concluded, which is the part you will want six weeks later.

Cells run against the notebook's default connection unless a cell overrides it. That override is what lets one notebook compare two databases.

sql

-- Cell 1: the cohort
SELECT id, email, created_at
FROM users
WHERE created_at >= :since;

-- Cell 2: what they did
SELECT user_id, COUNT(*) AS orders
FROM orders
WHERE created_at >= :since
GROUP BY user_id;

Running

Run all executes every cell in order, from a background worker rather than in your browser — a long notebook keeps going after you navigate away. Cell status updates as it goes, and a cell that fails reports its error without stopping the ones that already ran.

Running executes what is saved, not what is on screen. Unsaved edits are saved for you before the run starts, so you never get results for a query you just changed.

Column masking policies apply to notebook results, the same as anywhere else. A column masked in the workbench is masked here.

Run history

Every run is kept with its per-cell results, so you can reopen what a notebook produced last Tuesday without re-running it against data that has since changed.