Notebooks
Multi-language cells, the keyboard model, Jupyter import, and scheduled runs.
A notebook is the long-form surface under Developer → Notebooks. Where the SQL editor is built around one query at a time, a notebook is a sequence of cells — SQL, Python, Spark, and markdown — that you run in order and keep as a document.
If you've used Jupyter or a Databricks notebook, the model will feel familiar, down to the keyboard shortcuts.
Cells and languages
Each cell declares its own language, chosen from the picker on the cell:
| Language | Runs on |
|---|---|
| SQL | Your selected lakehouse connection. |
| Spark - SQL | A Spark cluster. |
| Spark - Python (PySpark) | A Spark cluster. |
| Spark - Scala | A Spark cluster. |
| Python | The Python runtime, when it's enabled. |
| Markdown | Nothing — it's prose, rendered in place. |
The Spark languages only appear when the project has a Spark connection, and Python only when the Python runtime is enabled for the connector. A cell in a language that's no longer available stays visible but is marked unavailable rather than silently rewritten.
A Python cell runs to completion once started — there's no stop. SQL cells can be cancelled normally.
Running cells
Press Run on a cell, or use the keyboard. If the engine behind the cell is asleep, running a cell starts it and then runs — you don't have to wake compute separately first.
| Action | Shortcut |
|---|---|
| Run the selected cell | Shift + Enter |
| Run selection / statement at cursor | Cmd/Ctrl + Shift + Enter |
| Run all cells | Cmd/Ctrl + Alt + Enter |
| Run cell and insert below | Alt + Enter |
From a cell's menu you can also Run all cells above, Run this cell and all below, Run this section (everything under the nearest markdown heading), and Stop all running cells.
A SQL cell holding several statements runs them in order and shows per-statement results.
Command mode and edit mode
The notebook is modal, the same way Jupyter is:
- Esc enters command mode — keys act on cells.
- Enter enters edit mode — keys type into the selected cell.
In command mode:
| Key | Action |
|---|---|
| A / B | Insert a cell above / below |
| J / K or arrows | Select the next / previous cell |
| Y / M | Change the cell to code / markdown |
| C / X / V | Copy / cut / paste below |
| Z | Undo a cell deletion |
| Shift + M | Merge with the cell below |
Delete, Duplicate, Move up / down, and Split at cursor are on the cell menu and in the palette.
Cmd/Ctrl + Shift + P opens the cell command palette — every command above, searchable, with its shortcut shown. It's the fastest way to find something you only need occasionally.
Organizing a long notebook
Three things keep a large notebook navigable:
- Table of contents — built from your markdown headings, with a click-to-jump outline.
- Find and replace across cells — Cmd/Ctrl + Shift + F, spanning the whole notebook rather than one cell.
- Run this section — execute just the cells under one heading.
Results
A cell's output uses the same grid as the SQL editor, so Filter, Columns, Summary, CSV, JSON, and Chart all work per cell. Cells remember their output height, so a notebook re-opens laid out the way you left it.
Long tracebacks collapse behind a Show Full Traceback toggle.
When a cell errors
An errored cell offers Explain this error and Fix this cell, both driven by an LLM connector you pick. They read the traceback the cell already produced.
The important part is what happens next: a fix comes back as a proposed change you have to accept. You can Accept it, or Accept and run. Nothing is applied to your cell until you say so.
Saving, versions, and sharing
- Autosave keeps your typing safe as you work, and an explicit save cancels any pending autosave so the two can't race.
- Save to server stores the notebook centrally; Version history lists previous versions and restores one.
- Share hands a notebook to teammates. A read-only share really is read-only.
Jupyter import and export
Notebooks import and export real .ipynb files:
- Import accepts nbformat 4.x. Code, markdown, and raw cells all map across; cell ids are preserved on nbformat ≥ 4.5; the kernel spec maps onto our cell languages. Outputs are dropped — only the source comes in.
- Export emits valid nbformat 4.5, so
nbconvert,nbdime, and GitHub's renderer all handle the file.
An .ipynb that declares itself Jupyter but isn't a shape we read — nbformat 3 keeps its cells under worksheets — is rejected by name rather than importing as an empty notebook.
Scheduled runs
A notebook can run on a schedule as an automation task — see Databasin Notebook in The task types. The notebook's run panel shows Recent runs for that schedule: when each started, how long it took, progress, and the per-cell detail where the run recorded it.
Scheduled notebook runs used to report unfinished and cancelled runs as successes. That's fixed — but it's still worth opening the run panel after you first schedule a notebook, to confirm the result matches what you expect.