The Canvas

Notebooks use a canvas view that shows cells as a visual DAG (Directed Acyclic Graph). This makes data flow explicit and pipelines easy to understand.

Canvas Features

Navigation

• Drag to pan — Click and drag the canvas background
• Scroll wheel — Zoom in/out (0.05x to 4x zoom)
• Pinch — Zoom on trackpad
• Fit view — Button to zoom to fit all cells

Working with Cells

• Drag cells — Reposition cells anywhere on the canvas
• Create edges — Drag from one cell's handle to another
• Search — Press Cmd+K to find and jump to any cell
• Viewport persistence — Your view position is saved in the URL

Cell Dependencies (DAG)

Cells can depend on other cells, forming a directed acyclic graph:

[Raw Orders] ──→ [Aggregated] ──→ [Chart]
      ↓
[Raw Customers] ──────────────→ [Joined Data]

Creating Dependencies

On the Canvas:

1. Hover over a cell's edge handle
2. Drag to the target cell
3. Release to create the edge

Via Agent: The agent automatically creates edges when building multi-step analyses.

Edge Labels

Edges can have labels to describe the relationship:

• "orders_data"
• "customer_lookup"
• "aggregated_metrics"

These help the agent understand how to reference upstream data.

Execution Modes

DB Mode (Default)

Cell queries your database directly:

-- Runs against your PostgreSQL/MySQL
SELECT * FROM orders WHERE created_at > '2024-01-01'

Requires a connection to be selected.

Derived Mode

Cell reads from upstream cell results via DuckDB:

-- Reads from incoming edge outputs
SELECT customer_id, SUM(total) as revenue
FROM orders_data  -- Alias from incoming edge
GROUP BY customer_id

To use derived mode:

1. Remove the connection from the cell
2. Create incoming edges from source cells
3. Reference edge labels as table names

When to Use Derived Mode

Use Case	Why
Multi-step transforms	Avoid round-trips to your DB
Joining across databases	Combine data from different connections
Complex aggregations	Break into manageable steps
Caching	Upstream results are cached

Run Downstream

After editing an upstream cell, run it and all dependent cells:

1. Right-click the cell (or use the menu)
2. Select Run Downstream
3. All downstream cells execute in dependency order

Stale Detection

When an upstream cell changes, downstream cells are marked stale — indicating they may need to re-run.

Frozen Cells

Pin a cell to a specific result to prevent re-execution:

1. Run the cell to get results
2. Click Freeze in the cell menu
3. The cell won't re-run even if upstream changes

Useful for:

• Locking expensive computations
• Creating stable snapshots
• Reproducible reports