Picasso — Plan-Space Visualisation

Picasso is the plan-space visualiser for Samyama Graph. Given a Cypher pattern (or template), it sweeps a parameter or schema dimension, runs EXPLAIN at every grid point, colours each cell by the plan signature the planner chose, and reports a plan-stability score for the sweep.

Picasso ships as a page in samyama-insight at /picasso, backed by the engine’s HTTP EXPLAIN endpoint. No JDBC, no separate tool — it is part of the management UI.

What it answers

• Does the planner change its mind across a selectivity range? A stable plan-diagram means the cost model produces consistent decisions across the parameter space.
• Where are the plan boundaries? Adjacent cells with different signatures expose the selectivity points where the planner flips between strategies.
• How many physical plans does the planner actually consider for this pattern? The “Distinct Plans” metric counts the unique plan signatures observed during the sweep.

Two modes

Graph Pattern Mode

Sweep schema dimensions for a fixed Cypher pattern.

• Inputs: Label, EdgeType, optional second Label.
• Per grid cell, the page sends EXPLAIN MATCH (a:Label1)-[:EdgeType]->(b:Label2) ... and records the plan signature.
• Useful for understanding which label/edge-type combinations the planner treats as “the same plan shape” vs. distinct.

Parameter Sweep Mode

Sweep a numeric range for $param1 (and optionally $param2) in a Cypher template.

• Input: a Cypher template like MATCH (n:Person) WHERE n.age > $param1 RETURN n and a (min, max, step) range.
• 1D sweep produces a line; 2D sweep produces a heatmap.
• Useful for stressing the planner’s selectivity estimation: at low $param1 the predicate is highly selective and IndexScan should fire; at high $param1 it should fall back to NodeScan + filter. The grid makes the transition visible.

Metrics surfaced

Why we did not adopt IISc Picasso

The original Picasso project at IISc (Bangalore) is a JDBC-driven plan-diagram tool for PostgreSQL / Oracle / SQL Server / DB2. It runs a sweep, pulls each EXPLAIN over JDBC, and renders the result.

A JDBC adapter for a RESP/HTTP Rust engine would have meant a multi-week protocol-bridge project. The native alternative — connect the Picasso UI directly to the existing HTTP EXPLAIN endpoint — was simpler, kept the toolchain Rust-end-to-end, and ships every time the management UI ships. So Picasso lives in samyama-insight, talks HTTP, and inherits the planner improvements from each release without a separate integration step.

What’s behind the plan diversity

The planner enumerates up to 64 candidate plans per MATCH via plan_enumerator.rs (ADR-015). For each pattern node it tries that node as the entry point, picks a traversal direction by comparing avg_out_degree vs avg_in_degree from GraphCatalog, and chooses Expand vs ExpandInto based on which endpoints are bound at expansion time. Selectivity-aware predicate pushdown via the IndexManager (ADR-029) further differentiates plans.

So the plan diagram Picasso paints is not a single “this is the only plan” verdict — it’s a window into the cost-driven choice across the candidate space.

Remaining gaps

• Histograms / MCV lists — range and inequality predicates today fall back to default selectivity constants (0.33 and 0.1). Adding equi-depth histograms would tighten the cost-driven plan choice and make Picasso’s reduction-factor analysis (the ratio of chosen-plan-cost to cheapest-plan-cost) meaningful.
• Cost-vs-actual annotations — PROFILE produces actual row counts per operator; the Picasso grid does not yet overlay that delta on the plan diagram.
• 3D cost surface — the classic IISc Picasso renders a 3D surface of estimated cost across selectivity space; the Samyama page surfaces distinct-plan count and stability score but not the cost surface itself.
• Plan-diagram regression tests — there is no test today that asserts “this schema/parameter grid produces exactly N distinct plans”. Worth adding to catch silent planner regressions.

Pointers

• UI: samyama-insight/src/pages/Picasso.tsx
• E2E: samyama-insight/e2e/06-picasso.spec.ts
• Planner: samyama-graph/src/query/executor/plan_enumerator.rs
• ADRs: ADR-015 (graph-native query planning), ADR-017 (adjacency-aware aggregation), ADR-027 (aggregation pushdown), ADR-029 (IndexManager)
• Deeper assessment: samyama-cloud/papers/picasso-assessment.md