Notebook format.

A .orchid file is YAML — readable in any text editor, friendly to git diffs, and stable across Orchid versions.

The shape

Three top-level keys:

  • orchid — schema version, a string (e.g. '1.0')
  • metadata — title, timestamps, runtime hints
  • blocks — an ordered array of cells

That's it. No magic, no hidden state — what you see is what loads.

A full example

orchid: '1.0'
metadata:
  title: Monthly revenue review
  created: '2026-04-12T09:14:00Z'
  modified: '2026-04-29T17:02:11Z'
  python_version: '3.11'
blocks:
  - id: blk_01HW3K
    type: markdown
    source: |-
      # April revenue review
      Numbers as of the morning of 2026-05-01.

  - id: blk_01HW3L
    type: sql
    integration: warehouse
    source: |-
      SELECT segment, sum(mrr) AS mrr
      FROM revenue.monthly
      WHERE month = '2026-04-01'
      GROUP BY 1
      ORDER BY 2 DESC;
    output_variable: revenue_by_segment
    outputs:
      - type: dataframe
        summary: '4 rows × 2 columns'
        variable: revenue_by_segment
        data:
          columns: [segment, mrr]
          rows:
            - [enterprise, 148000]
            - [mid_market, 72100]
            - [startup, 18250]
            - [self_serve, 3960]

  - id: blk_01HW3M
    type: code
    language: python
    source: |-
      print(revenue_by_segment.head())
    outputs:
      - type: text
        data: |
          segment       mrr
          enterprise   148000
          mid_market    72100
          startup       18250
          self_serve     3960

Top-level keys

orchid

Schema version as a string. '1.0' is the current public schema and what every Orchid 1.x release ships with. Future breaking format changes increment this — non-breaking additions keep '1.0'. The app refuses to open higher versions than it understands; lower versions auto-migrate transparently.

metadata

Only four fields are recognized; the first is required:

  • title — string, shown in the project shelf and tab
  • created — ISO 8601 timestamp (UTC) of file creation
  • modified — ISO 8601 timestamp of the last save
  • python_version — pin for the kernel; if missing, falls back to the project default (typically '3.11')

Anything else you add under metadata is preserved on save — Orchid never deletes keys it doesn't recognize. Use it for team conventions (ticket IDs, owners).

blocks

An ordered array. Each block has an id and a type. The id is stable across saves — agent comments and pin references use it. Reorder blocks by reordering the array; Orchid does not depend on positional indexes.

Block types

code

Python in the bundled interpreter. Variables persist across cells in the same notebook.

- id: blk_01HW3M
  type: code
  language: python
  source: |-
    import pandas as pd
    df = pd.read_csv("data/sales.csv")
    print(df.shape)

sql

A query against a connected integration. The integration field names the profile defined in your project. The result is bound into the Python kernel as a DataFrame named by output_variable.

- id: blk_01HW3L
  type: sql
  integration: warehouse
  output_variable: events_today
  mode: dataframe
  source: |-
    SELECT * FROM events WHERE day = current_date;

markdown

GitHub-flavored markdown. No code execution, no outputs.

- id: blk_01HW3K
  type: markdown
  source: |-
    ## Key takeaway
    Enterprise revenue is up 12% MoM, driven by three accounts.

chart

Plotly chart bound to a DataFrame. The block uses library: plotly and stores a typed chart_spec describing the encoding. The chart renders from cached output without re-running the kernel.

- id: blk_01HW3N
  type: chart
  library: plotly
  source: |-
    # Chart: April MRR by segment
    import plotly.io as pio
    fig = pio.from_json(chart_spec_json)
    fig
  outputs:
    - type: chart
      data:
        application/vnd.plotly.v1+json:
          data: [{type: bar, x: [enterprise, mid_market], y: [148000, 72100]}]
          layout: {title: 'April MRR by segment'}

For custom Plotly figures, use a code block instead. Build the figure and render it with fig.show() or by leaving it as the last expression in the cell.

What's inside outputs

Each block carries an optional outputs array — the last run's results, serialized so reopening the file doesn't require re-running. Each entry has a type, an optional summary, an optional variable (name in the kernel), and a data payload whose shape depends on the type.

  • type: text — stdout, returned values, or short text payloads
  • type: dataframe — tabular result with columns and rows (large rows may be truncated; truncated / truncatedAt mark the cap)
  • type: chart — Plotly figure JSON
  • type: image — PNG/JPEG payload
  • type: error — exception type, message, traceback

Sidecar files

When an output is too large for the YAML body, Orchid keeps a reference and writes the payload alongside the notebook:

my-project/
├── revenue-review.orchid
└── .orchid/
    └── outputs/
        ├── blk_01HW3L.parquet     # DataFrame for the SQL block
        └── blk_01HW3N.png         # rendered chart

The notebook itself stays compact and diffable. The sidecar directory is .gitignore-friendly — commit it if you want the outputs to travel with the notebook, ignore it if you only care about the source.

Outputs are advisory

Orchid treats output blocks as a cache, not a contract. You can hand-delete the outputs array (or the spill files) and the next run will regenerate them. Useful for shrinking large notebooks before checking in.

Version compatibility

The orchid: '1.0' schema is the public, stable format for the 1.x line. Forward compatibility rules:

  • Unknown keys are preserved on save — newer Orchid versions stay safe to open in older.
  • Unknown type values render as a placeholder block, but their YAML is preserved.
  • Unknown output type entries are kept verbatim — round-tripping never loses data.

Hand-editing tips

  • YAML cares about indentation — stick to two spaces.
  • Use the |- literal scalar for multi-line sources; it preserves whitespace.
  • Block ids look intimidating but you can replace them with any unique string — chart references and comments adapt.
  • To reorder blocks, just move the YAML entries — Orchid trusts the array order.
  • Strip outputs: arrays to slim down a notebook before sharing the source.

Git-diff friendliness

Because each block has a stable id and outputs spill to sidecar files, edits produce local, readable diffs. A typical change touches a handful of lines under the block whose source you modified — no giant base64 blobs, no notebook-merge tooling required.

For team workflows, the rules of thumb are:

  • Commit the .orchid file. Always.
  • Commit .orchid/outputs/ if reviewers should see your charts without re-running.
  • Ignore .orchid/outputs/ if the notebook is the only thing you want to review.
  • Use orchid run --no-save in CI to sanity-check that everything still executes.
A side-by-side git diff of a .orchid file, showing one block's source changing and the rest untouched./docs-images/reference/notebook-format-diff.png
A typical diff — the YAML stays local to the block you edited.

Related

  • Notebooks — the user-facing tour of cells and execution.
  • CLI — running and exporting notebooks from the terminal.
  • Configuration — project-level keys that affect how notebooks run.