# Notebooks: cells, Run and outputs

**Categories:** Using AI

---

A notebook is a Retain document for questions that need numbers. It is a stack of cells: text, data, code and charts, each with its own output. You run the code on your Mac, and every result keeps a record of the code and data behind it.



### What is in a notebook



Each cell has a kind.



* **Text.** Prose, written in Markdown. Headings fold the cells under them.
* **Code.** Python or SQL. SQL runs over your data and over earlier results, and a Python cell can do the same with DataFrames.
* **Data.** Rows with their source written beside them, or a file you attached. See [Notebook setup and bringing data in](https://retainapp.ai/help/article/notebook-setup-and-data).
* **Chart.** A chart that draws a table an earlier cell produced. See [Charts, tables and .ipynb export](https://retainapp.ai/help/article/notebook-charts-and-export).
* **Math.** A formula, shown as written.

A code cell can have a name, shown as #by_team. Charts and other cells use that name to point at its result.



### How you get one



* Open the New menu and choose Scientific notebook for a blank one, then add cells yourself or ask the chat beside it.
* Pick Notebook as the deliverable when you create a document and Retain plans the analysis and writes it as a notebook.
* Import a Jupyter .ipynb file from File, Import, Jupyter Notebook.

Retain suggests an analysis when the work needs numbers, such as a figure discussed in a meeting. The notebook keeps the source of each data cell, so a number can be traced back to where it came from.



### Run a cell



Running needs Python on your Mac, which is part of the Mac app (see [The notebook sandbox](https://retainapp.ai/help/article/notebook-sandbox)). If it is not set up, the Run button says so and offers Set Up Python.



* Press the play button on a cell, or Shift-Enter to run it and move to the next one. Cmd-Enter runs it and stays.
* Run All is in the notebook's title row. Restart and Run All is in the "..." menu.
* The gutter beside a code cell shows its count, then queued, a running timer, the duration, error or interrupted. A result's row count sits under it.
* Interrupt stops a running cell. If the code does not stop within 3 seconds, Python restarts.

### What carries between cells



Each notebook has one Python session on your Mac. Variables you define in one cell are there in the next, for as long as the session runs. Data cells are available by name as DataFrames and as SQL tables, and a SQL cell's result is available to later cells by its name.



Retain marks an output that may no longer match the notebook:



* **may be out of date.** An earlier cell was edited or run again after this one.
* **stale.** This cell's own code changed since it ran.
* **from a previous session.** Python stopped since the output was made, so its variables are gone.

Python stops after 15 minutes idle, and the notebook says so. Files in the notebook's work folder are kept. Restart and Run All makes every output current again.



### Edit



Double-click a cell or press Enter to edit it, and Esc saves it. If the cell changed while you edited, you can discard your edit or save yours over it.



With a cell selected, the arrow keys (or J and K) move between cells, A adds a Python cell above, B adds one below, D twice deletes, and Cmd with an arrow moves the cell. Hovering a cell shows the same actions as a toolbar, including Ask about this cell, which sends the cell to the chat. You can also collapse a cell's code or output, fold a section, and open an outline of the headings.



### On iPhone and on Mac



On iPhone a notebook opens read-only. You see the text, code (long code is collapsed), tables, images and charts, and you can press and hold on a chart to read values. The chat on iPhone can read the notebook and answer questions, but cannot change it or run it. A chart that Python draws shows once the notebook has been run on a Mac.



On the Mac you can edit every notebook, and run it on a Mac with Apple silicon and macOS 26 or later.
