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

# Notebooks

> Interactive Python and TypeScript notebooks with pre-wired lake access.

Notebooks are interactive execution environments built into the platform. Each notebook gives you a persistent Python or TypeScript sandbox with your catalogs, lake tables, and external connections already wired in - no credentials to configure, no installs to run.

> [!NOTE]
>
> Notebooks are in **alpha**. They were previously called Tasks.

New organizations start with an example notebook that loads NYC taxi trips and charts them. Add **Python**, **TypeScript**, **Spark**, or **Markdown** cells from the add-cell button.

> [tab] Python
>
> The Python sandbox runs Python 3.13 and comes with the following libraries pre-installed:
>
> | Library | Purpose |
> | - | - |
> | `polars` | DataFrame processing |
> | `pandas` | DataFrame processing |
> | `duckdb` | In-process SQL |
> | `pyiceberg` | Iceberg catalog client |
> | `numpy` | Numerical computing |
> | `matplotlib` | Plotting |
> | `pyarrow` | Arrow/Parquet I/O |
>
> ### The `oleander` module
>
> Every cell has access to a generated `oleander` module that wires your catalog and DuckDB connection automatically:
>
> ```python theme={null}
> # Pre-wired DuckDB connection with all your Iceberg catalogs attached
> conn = oleander.conn
>
> # Default Lakekeeper catalog as a pyiceberg catalog object
> catalog = oleander.default_catalog
>
> # Get any registered catalog by name
> my_catalog = oleander.get_catalog("my_catalog_name")
> ```
>
> Query your lake directly:
>
> ```python theme={null}
> result = conn.execute("SELECT * FROM oleander.default.flowers LIMIT 10").df()
> result
> ```
>
> `oleander.scan("namespace.table")` reads a lake table as a Polars LazyFrame, so nothing is loaded until `.collect()`, and then only the columns and rows the query needs. `oleander.duckdb` is the same connection as `conn` for SQL that returns a Polars frame with `.pl()`:
>
> ```python theme={null}
> import polars as pl
>
> orders = oleander.scan("shop.orders")  # or "catalog.namespace.table"
> region_mix = (
>     orders.filter(pl.col("order_date") >= params["day"])
>     .group_by("region")
>     .agg(pl.col("amount").sum().alias("revenue"))
>     .collect()
> )
> ```
>
> oleander records what each Python cell's Polars queries and `oleander.duckdb` SQL read and wrote, so Python cells appear in [lineage](https://docs.oleander.dev/platform/observability/lineage/overview.md) like SQL cells do. Reads through pandas, pyiceberg's own `scan()`, or a separate `duckdb.connect()` are not recorded.
>
> Use pyiceberg for low-level catalog operations:
>
> ```python theme={null}
> table = catalog.load_table("default.flowers")
> df = table.scan().to_pandas()
> df.head()
> ```
>
> ### BigQuery
>
> If you have BigQuery connections configured, the DuckDB `bigquery` extension is installed automatically. BigQuery tables are accessible as `connection_name.dataset.table`:
>
> ```python theme={null}
> result = conn.execute("""
>   SELECT date, SUM(revenue) AS total
>   FROM my_bq.analytics.orders
>   WHERE date >= '2024-01-01'
>   GROUP BY 1
>   ORDER BY 1
> """).df()
> ```
>
> ### State persistence
>
> Variables persist across cell executions within a session. If you define a DataFrame in one cell, it is available in the next. State is stored in `/tmp/_oleander_state.pkl` and survives cell reruns.
>
> ### Output
>
> DataFrames are displayed as structured tables. Matplotlib figures are rendered as inline SVG. Other values are printed as text. In a server run, a cell shows only the DataFrames it created or changed, not every frame earlier cells left in scope.

> [tab] TypeScript
>
> The TypeScript sandbox runs Node 24 with `tsx` for execution. A generated `oleander` module exposes your Iceberg catalogs:
>
> ```typescript theme={null}
> import { defaultCatalog, getCatalog, catalogs } from './oleander';
>
> // List all catalogs
> console.log(catalogs.map(c => c.name));
>
> // Load a table from the default catalog
> const table = await defaultCatalog.loadTable({ namespace: ['default'], name: 'flowers' });
> ```

## Compute size

The toolbar's compute selector sizes the sandbox that runs your cells: **2**, **4**, or **8** CPUs, with 2 GB of memory per CPU. Changing it resizes the sandbox in place, so variables and state carry over. 8 CPUs is the ceiling for notebook sandboxes; it is separate from the larger tiers the [query router](https://docs.oleander.dev/platform/query-routing/overview#machine-sizing) uses for lake queries.

## Ask AI

Press <kbd>⌘I</kbd> in a cell to generate or edit its code from a plain-English prompt. The assistant knows the sandbox's libraries and your catalog structure.

## SQL cells

SQL cells run through the [query router](https://docs.oleander.dev/platform/query-routing/overview), like the lake editor. **Auto** picks the engine for each run, or you can pin **DuckDB**, **Polars**, **Bloom**, or **SparkSQL** from the cell's run settings. SparkSQL writes its result to a table and links to the Spark run instead of returning rows.

Pick a catalog to scope table autocomplete. Up to 500 rows of each result are saved with the cell.

## Spark cells

Submit inline PySpark code as a managed Spark job directly from a notebook cell. The job runs in the `oleander.tasks` namespace and returns a run ID you can track in the platform. Lineage from Spark cell runs is captured automatically.

## Notebooks from your agent

An agent connected over [MCP](https://docs.oleander.dev/mcp/protocol.md#notebooks) can write a whole notebook as YAML and save it with `notebooks_apply`. oleander saves it, runs it on the server, and returns a link to `/app/tasks/<slug>` where you see the results; a schedule can run it before you open it. Ask your agent to turn a question it has already answered into a notebook. The agent reads the format from `notebooks_guide_get` first.

The same notebooks open in the editor, and anything you build in the editor can be read and updated by the agent as YAML. The CLI's [`oleander notebooks`](https://docs.oleander.dev/cli/introduction#notebooks) commands pull a notebook to a `<slug>.notebook.yaml` file and push it back, so a notebook can live in your repo and be reviewed like other code.

Besides Markdown, SQL, Python, TypeScript, and Spark cells, a YAML notebook can hold:

* **chart**: a `line`, `bar`, `area`, `scatter`, or `number` chart over an earlier cell's result.
* **alert**: a condition on an earlier result that notifies Slack or email when it changes state.
* **webhook**: sends earlier results to a [webhook](https://docs.oleander.dev/platform/settings/webhooks.md) registered in settings. Webhooks are named in the YAML, never by URL.
* **summary**: a few sentences written from the run's numbers.

Give a cell an `id` to name its result. Later SQL cells read it by name, and Python cells read `results["id"]` as a Polars LazyFrame. `params` declares typed inputs (`date`, `number`, `string`, `enum`, or `multiselect`) that SQL reads as `:name`, Markdown as `{{ name }}`, and Python as `params["name"]`; the page shows a control for each parameter. Python packages are declared under `python.packages` with pinned versions instead of installed from a cell.

A change that adds an output table, a schedule, a delivery destination, or a budget goes through a plan: the agent shows you what would change and applies it once you agree. Edits to a scheduled or table-writing notebook land in a draft that you can run before publishing.

## Runs and the report

Running every cell from the notebook's header starts a server run, and every run is kept with its parameters, inputs, and results. A notebook has three views: **Notebook** for the cells, **Report** for the number tiles and charts (set a cell to `collapsed` so the page reads as a report), and **Lineage** for what the run read and wrote.

The report marks how each number moved since the last run and shows each tile's history across recent runs. **Lineage** is about one run: it names the run it shows, **Choose another run** switches to a run from the history, and **What changed since the run before** compares it with the run before it. A **stale inputs** chip appears when a table the run read was overdue; it opens Lineage to show which tables. Compare any two runs with `notebooks_runs_compare` or `oleander notebooks compare` to see which inputs changed and how each cell's numbers moved.

Each run appears in the [lineage graph](https://docs.oleander.dev/platform/observability/lineage/graph) as a job in the `oleander.notebooks` namespace with its cell runs nested under it.

## Triggers and delivery

Open **Triggers** on a notebook to:

* **Schedule** it every 15 minutes, hourly, daily, or on a cron. Type the schedule in plain English, like "weekdays at 9am". **Timezone** offers your own zone and UTC in one click, with every other zone a search away. Schedules are shown in your time zone, with the zone named next to the time.
* Run it when a table it read changes.
* Deliver each run, or only alerts, to a Slack channel or to organization members by email. The header shows where the notebook sends, and each run's chip and the report's **Downstream** row say whether that run was sent. Scheduled, input-triggered, and agent or API runs send; runs you start from the page don't.

Schedules run as whoever published them, and that principal's membership and compute access are re-checked at every run. Connect your Slack workspace under **Slack workspace** in [Settings → Notebooks](https://oleander.dev/app/settings/notebooks); the **Notebook destinations** switch on the same page lets an admin turn off Slack, email, and webhook delivery for the organization.

## Output tables

A SQL or Python cell with `output` also writes its result to a lake table on every run, in `overwrite`, `append`, or `merge` mode (merge takes a `key` and a `watermark`), so the table stays up to date. `expect` checks on the result (`min_rows`, `not_null`, `unique`, `rows_satisfy`, `max_row_change`) run before anything is written, and a failing check leaves the table untouched. To fill missed days after a fix, backfill a date parameter over a range with `notebooks_backfill` or `oleander notebooks backfill`.


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