EXPLAIN / EXPLAIN ANALYZE / EXPLAIN (FORMAT JSON)

[whilo]

Summary

• Postgres-style indented EXPLAIN text renderer + DuckDB-shape JSON renderer, replacing the legacy single-strategy summary that was effectively unusable through pgwire.
• EXPLAIN ANALYZE now runs the query under instrumentation and surfaces per-node actual-rows + time-ms plus an Execution Time: footer — inclusive timing per Postgres/DuckDB convention.
• SQL parser accepts the full grammar: EXPLAIN, EXPLAIN ANALYZE, EXPLAIN VERBOSE, EXPLAIN (ANALYZE), EXPLAIN (FORMAT JSON), EXPLAIN (ANALYZE, FORMAT JSON).
• Fixes regression bug: EXPLAIN ... WHERE p previously produced byte-identical output to the no-WHERE plan on PSplitAgg sub-plans (filter was applied at runtime, just dropped from the printed tree). Includes a direct regression test.

What changed

File	Change
plan.clj	plan->data data model, node-details uniform [label, value] pairs, render-text (Postgres-style), render-json (DuckDB shape), format-pred / format-agg SQL-like printers
executor.clj	*explain-collector* dynamic var; execute-node split into wrap + impl for inclusive per-node timing; explain-analyze-query entry point
sql.clj	parse-explain-prefix handles all six modifier syntaxes; new richer return shape {:options {...} :inner {...}}
server.clj	format-explain-result rewritten to dispatch on :format; one pgwire row per tree line for text, single row for JSON; inline json-write-str (no new dep)
api.clj / query.clj	:analyze? / :format opts; legacy :strategy / :n-rows / :columns keys preserved
test/stratum/explain_test.clj	12 tests / 51 assertions: text shape, JSON shape, ANALYZE timing, all SQL variants, end-to-end, legacy back-compat, the PSplitAgg-filter regression
test/stratum/asof_join_test.clj	Regex match= → Match Cond: to match the new labeled format

Sample output

EXPLAIN ANALYZE SELECT MIN(a), MEDIAN(a), MAX(a) FROM t WHERE a > 100:

 PSplitAgg  (est-rows=1 actual-rows=1 time=1.689ms)
    Aggregates: [min(a), median(a), max(a)]
    Strategies: 2
    ->  PDenseGroupBy  (est-rows=1000 actual-rows=1 time=0.696ms)
          Aggregates: [min(a), max(a)]
          Max Key: 1
          Filter: (a > 100)
          ->  PScan  (est-rows=1000 actual-rows=1000 time=0.058ms)
                Columns: [:a]
                Length: 1000
    ->  PPercentileAgg  (est-rows=1 actual-rows=1 time=0.750ms)
          Aggregates: [median(a)]
          Filter: (a > 100)
          ->  PScan  (est-rows=1000 actual-rows=1000 time=0.003ms)
                Columns: [:a]
                Length: 1000
 Execution Time: 1.760 ms

EXPLAIN (FORMAT JSON) ...:

[{"name": "PSplitAgg",
  "children": [{"name": "PDenseGroupBy", ...,
                "extra_info": {"Aggregates": "[min(a), max(a)]",
                               "Filter": "(a > 100)",
                               "__estimated_cardinality__": 1000}},
               ...],
  "extra_info": {"Aggregates": "[min(a), median(a), max(a)]",
                 "Strategies": "2",
                 "__estimated_cardinality__": 1}}]

Out of scope (deliberate)

• Logical-vs-optimized-vs-physical multi-plan output (we only have one physical plan).
• HTML / GRAPHVIZ / YAML / MERMAID formats (tooling can consume the JSON).
• Buffer / IO stats (no instrumentation today).
• Per-thread breakdown of morsel-parallel nodes (single wall-clock per node).

Test plan

• Full suite: 1024 tests, 4731 assertions, 0 failures.
• clj -M:ffix applied (cljfmt clean).
• Manual: connect via psql, run EXPLAIN, EXPLAIN ANALYZE, EXPLAIN (FORMAT JSON) against a registered table.
• Manual: verify ANALYZE timings sum sensibly on a deep plan (joins + group-by).