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

# Notebooks

> Reactive SQL and Python notebooks that you and the agent edit together.

An Alkera notebook is a reactive SQL and Python notebook that lives in a workspace. You can write cells yourself, ask the agent to build the notebook for you, or both at once. The agent edits the same notebook you have open, so you see its cells and outputs as it works.

This section covers:

* [Reactivity](/notebooks/reactivity): how cells track their dependencies and re-run.
* [SQL and Python](/notebooks/sql-and-python): querying connections and using results as dataframes.
* [Outputs and charts](/notebooks/outputs): tables, charts, and widgets.
* [Environment and kernel](/notebooks/environment): packages, the kernel, and compute.

## Create a notebook

Notebooks live in a [workspace](/workspaces/overview), and their kernel runs on the workspace's [machine](/workspaces/machines). Like any workspace file, a notebook is saved in Files and copied onto the machine while the workspace is awake. See [Where workspace files live](/workspaces/files#where-workspace-files-live).

* **Ask the agent.** In any chat, ask for a notebook: "Build a notebook that tracks weekly signups by channel." The agent creates it, adds cells, and runs them.
* **Create one yourself.** Open the workspace's files and click **New notebook**. It opens with one empty cell.

A new notebook opens in the **Notebook** view. Switch to **Source** to edit the underlying file as text.

## Cells

A notebook is a list of cells. Each cell is one of:

* **Python**: any Python code.
* **SQL**: a query against a [connection](/foundations/plugins-and-connections), or DuckDB over the notebook's own data. See [SQL and Python](/notebooks/sql-and-python).
* **Markdown**: text, headings, and notes.

To add a cell:

* Click **Add a cell** at the end of the notebook.
* Open a cell's **⋯** menu and choose **Insert cell above**, **Insert cell below**, or one of the **Insert Markdown** and **Insert SQL** items.
* Select a cell and press <kbd>A</kbd> to insert above or <kbd>B</kbd> to insert below.

Drag a cell's handle to reorder it.

Run a cell with its **Run cell** button or <kbd>Cmd</kbd> + <kbd>Enter</kbd> (<kbd>Ctrl</kbd> + <kbd>Enter</kbd> on Windows and Linux). See [Keyboard shortcuts](/notebooks/shortcuts) for the rest.

## Build it with the agent

The agent has full control of notebooks through its notebook tools. It can:

* Create notebooks, and add, edit, move, and delete cells.
* Run a cell, the whole notebook, the stale cells, or everything upstream or downstream of a cell.
* Read outputs, variables, and dataframes, and follow the dependency graph.
* Install packages and change notebook settings.
* Show any cell's output, such as a table or chart, right in the chat.

Notebook steps in the chat carry **Go to cell**, which opens the notebook at that cell. Running cells and installing packages are actions the agent asks before taking, depending on your [permission mode](/foundations/agent-and-tools#permission-modes).

## Work together

Notebooks are edited live by everyone in them, including the agent.

* Avatars in the toolbar show who is in the notebook. Each cell shows who is editing it, and the agent appears as **Alkera**.
* Typing from several people in one cell merges as they type.
* Everyone shares one kernel, so everyone sees the same outputs. Each run records who ran it, such as "by Alkera agent for Alice".
* A cell is not re-run automatically while someone is editing it.

## The file format

A notebook is a plain Python file ending in `.alknb.py`. It builds on [marimo](https://marimo.io)'s file format: each cell is a function, so the notebook is readable Python, diffs cleanly in git, and runs in marimo with the `alkera` package installed.

```python theme={null}
# >>> alkera
# format = "1.0"
# dataframe = "polars"
# <<< alkera
import marimo
app = marimo.App()

with app.setup(alkera_id="0000000001"):
    import alkera

@app.cell(alkera_id="0000000002")
def _():
    orders = alkera.sql(
        rf"""
        SELECT * FROM analytics.orders
        """,
        connection="Snowflake prod",
    )
    return (orders,)
```

Alkera adds a settings block at the top, a stable ID on each cell, and the `alkera` module for SQL, charts, Markdown, and widgets. Outputs are saved next to the notebook, not in the file.

## View and download

In [Files](/workspaces/files), a notebook previews read-only with its saved outputs. Previewing never starts a kernel. **Download** saves the `.alknb.py` file. Individual outputs can be downloaded as images or copied as CSV.

## In this section

<Columns cols={2}>
  <Card title="Reactivity" icon="arrows-rotate" href="/notebooks/reactivity">
    The dependency graph, stale cells, and run modes.
  </Card>

  <Card title="SQL and Python" icon="database" href="/notebooks/sql-and-python">
    SQL cells, connections, and dataframes.
  </Card>

  <Card title="Outputs and charts" icon="chart-line" href="/notebooks/outputs">
    Tables, charts, widgets, and more.
  </Card>

  <Card title="Environment and kernel" icon="microchip" href="/notebooks/environment">
    Packages, the kernel, and compute.
  </Card>

  <Card title="Keyboard shortcuts" icon="keyboard" href="/notebooks/shortcuts">
    Every notebook shortcut.
  </Card>

  <Card title="Dashboards" icon="gauge" href="/notebooks/dashboards">
    Coming soon: share a notebook as an interactive dashboard.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.