Notebooks.

A notebook in Orchid is a single .orchid file with a stack of typed cells — Python, SQL, markdown, or chart — each keeping its own output.

What a notebook is

Open a project, hit New notebook, and Orchid creates a fresh .orchidfile in your project root. It opens with one empty Python cell. Type, run, repeat — every cell saves its source and last output back into the file.

The format is YAML, so notebooks read cleanly in git diffs and merge by hand when they have to. You can also open one in any text editor and not break anything.

A notebook with mixed Python, SQL, and chart cells, the variables tab open at the bottom./docs-images/notebooks/overview.png
One file. Four cell types. Variables shared across cells.

The four cell types

Pick the right cell for the job. Press / at the start of an empty cell to swap its type.

  • Code cells — Python in the project's bundled interpreter. Variables persist across cells.
  • SQL cells — pick a connection in the header; results land as a DataFrame.
  • Markdown cells — prose, math, images, captions.
  • Chart cells — bind to a DataFrame, configure axes, no plotting code.

Cell mechanics — adding, moving, deleting, run order — are covered in Cells & blocks.

Outputs stay with the file

Each cell's last output is serialized into the notebook. Re-opening the file on another machine shows you the previous results immediately, without re-running anything. Large outputs spill to a side directory so the YAML stays diff-friendly — details in Outputs & exports.

orchid: '1.0'
metadata:
  title: Monthly revenue review
  created: '2026-05-14T09:12:00Z'
  python_version: '3.11'
blocks:
  - id: q1
    type: sql
    integration: warehouse
    output_variable: monthly_revenue
    source: |-
      SELECT date_trunc('month', created_at) AS m, sum(amount) AS revenue
      FROM orders GROUP BY 1 ORDER BY 1;
  - id: c1
    type: chart
    library: plotly
    source: |-
      import plotly.express as px
      fig = px.bar(monthly_revenue, x='m', y='revenue')
      fig
Tip

Shift+Enter runs and advances. Cmd+Enter runs in place. Run all runs the whole notebook top-to-bottom. / at the start of an empty cell opens the type picker.

Where to next