Notebooks
A notebook is a hosted, Marimo-based interactive Python notebook backed by a Sail (Spark) session. It is the third interactive surface alongside sessions and saved queries: where a session is a connection you attach your own client to, a notebook is the editor and the runtime, hosted for you in the browser.
When to use a notebook
- Exploratory Python + Spark in one place. You want to write PySpark and see results without wiring up a local client or managing tokens.
- Shareable analysis. A notebook belongs to a member and can be shared with teams, so a colleague can open the same analysis against the same compute.
- Authoring before you productionize. Prototype a transform in a notebook, then lift the working logic into a job once it's stable.
When not to use one:
- Scheduled or batch work. Use a job — notebooks are interactive and don't carry schedules, versioning, or run history.
- Connecting an external client (BI tool, local PySpark, a service). Use a session; it exposes Spark Connect over gRPC for exactly that.
Prerequisites
- A compute profile (workload config) on an
activecluster. The profile defines the Sail pod the notebook runs on — instance type, libraries, and environment. - A catalog if you want to query your tables (recommended).
Create a notebook
- Open Notebooks in the sidebar and click Create notebook.
- Fill in:
- Name — e.g.
Daily Sales Analysis. - Description (optional).
- Compute profile — the profile whose Sail pod backs the notebook. Pick an existing one or create a new one inline.
- Team(s) — who can open and run the notebook.
- Name — e.g.
- Click Create. The notebook starts in
stopped.
Start, open, and stop
A notebook has its own lifecycle, independent of the workload it runs:
| Status | Meaning |
|---|---|
stopped | No Sail or Marimo pods are running |
starting | The platform is provisioning the Sail and Marimo pods |
running | Fully active and ready to use |
stopping | Tearing the pods down |
error | Provisioning or teardown failed; check the status message |
- Start provisions the pods and moves the notebook to
running. The first start takes longer if the cluster has to schedule new compute. - Open launches the Marimo editor against the running notebook.
- Stop tears the pods down to reclaim compute. Your notebook contents persist; only the runtime goes away.
Stop notebooks you're not using
A running notebook holds compute. Stop it when you step away — starting it again is quick on a warm cluster.
Change the compute profile
The compute profile is editable only while the notebook is stopped. To move a notebook to bigger compute (or a different cluster), stop it, change the profile, and start it again.
Share with a team
Notebooks follow the same team sharing model as jobs and queries:
- Add a team to grant its members access to open and run the notebook.
- Remove a team to revoke access.
The creating member owns the notebook; shared teams get access according to their team roles.