Notebooks are in alpha. They were previously called Tasks.
- Python
- TypeScript
The Python sandbox runs Python 3.13 and comes with the following libraries pre-installed:The
Every cell has access to a generated Query your lake directly:oleander records what each Python cell’s Polars queries and
The oleander module
Every cell has access to a generated oleander module that wires your catalog and DuckDB connection automatically: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():oleander.duckdb SQL read and wrote, so Python cells appear in lineage 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:BigQuery
If you have BigQuery connections configured, the DuckDBbigquery extension is installed automatically. BigQuery tables are accessible as connection_name.dataset.table: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.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 uses for lake queries.Ask AI
Press ⌘I 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, 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 theoleander.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 can write a whole notebook as YAML and save it withnotebooks_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 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, ornumberchart 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 registered in settings. Webhooks are named in the YAML, never by URL.
- summary: a few sentences written from the run’s numbers.
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 tocollapsed 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 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.
Output tables
A SQL or Python cell withoutput 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.