> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nightshift.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Notebooks

> Saved, re-runnable SQL analysis — built by your agent, auditable by you

A notebook is a named list of SQL cells stored in Nightshift. It's the natural home for
analysis you want to keep: the agent writes the queries, runs them, and the results are
snapshotted so you (or anyone on your team) can review the work later without re-running
anything.

Notebooks are the middle ground between a one-off query and a full [App](/apps):

|               | Lives where                      | Best for                                    |
| ------------- | -------------------------------- | ------------------------------------------- |
| **Query**     | The chat                         | Quick questions, exploration                |
| **Notebook**  | Saved in Nightshift              | Analysis you'll revisit, rerun, or hand off |
| **Dashboard** | Rendered in chat                 | A visual read on the data, right now        |
| **App**       | Deployed at `apps.nightshift.sh` | Live, shareable, always-current             |

## Creating a notebook

Just ask. A prompt like:

> "Explore last month's orders and save your working queries as a notebook called *Monthly Revenue*"

will have Claude create the notebook and fill it with SQL cells as it works. A few things
worth knowing about how this behaves:

* **Cells don't run on creation.** Adding a cell just saves the SQL. A cell only executes
  when it's explicitly run — so a notebook can be drafted end-to-end before anything
  touches your data.
* **Running a cell snapshots the result.** When a cell runs, its result (columns, rows,
  row count, and when it ran) is saved onto the cell. That snapshot is what renders in
  chat and in the console.
* **Stale results are flagged.** If a cell's SQL is edited after its last run, the saved
  result is marked as *"query edited since, run to refresh"* — you'll never mistake an old
  answer for a current one.

## Running notebooks from chat

When Claude shows you a notebook in chat, it's not a screenshot — it's live. Each cell has
a **Run** button, and there's a **Run all** for the whole notebook. Clicking Run executes
that cell's SQL through your Nightshift identity, so the same [policies](/policies) that
govern the agent govern the button: if you can't read a table, neither can the cell.

This makes notebooks a nice handoff artifact. The agent does the analysis, you press Run a
week later to refresh the numbers.

## Notebooks in the console

Every notebook is visible in the [console](https://console.nightshift.sh), with its cells,
saved results, and run timestamps. Since results are snapshots, the console shows you
exactly what the agent saw when it ran the query — which makes notebooks a lightweight
audit trail for how a conclusion was reached.

## Tips

* **One question per cell.** Cells are the unit of re-running and reviewing. A notebook of
  focused cells is easier to audit than one giant query.
* **Promote reusable transforms to views.** If several cells share the same cleanup SQL,
  ask Claude to create a view and query that instead. Notebooks are for analysis, views
  are for shared shape.
* **Name notebooks for the question they answer.** "Churn by signup cohort" beats
  "analysis-2". Future-you is the audience.