[milindsrivastava1997]

Why. Reading the planner's data structures (memo groups, candidates, the plan each stage produces) currently requires the Stage Viewer or reading raw JSON. A text dump is easier to diff, grep and paste into issues; #1117, #1124 and #1126 were all written from it.

What. tools/dag-viewer/print_stages.py prints a stage_pipeline document as text:

• Stage 0's DAG.
• The memo after each step (stage0, pass1, pass2, concrete_states): each group with its children, parents, queries and roots, then its candidates with origin, reads, implements and accuracy budget parts.
• Stage 1 and Stage 2 candidates, and Stage 2's pruned candidates counted by reason.
• Stage 3's search status, selected DAG, per-node cost and per-query accuracy.

--enumerated prints every memo choice in memo.enumeration as a logical DAG.

How. It reads only the document. It sits next to the Stage Viewer, which reads the same format, so the viewer's CI step runs its test.

Key code interfaces added / modified: None; one new script.

Major algorithm changes: None.

Before this PR: the memo was visible only in the Stage Viewer or as raw JSON.

After this PR, for quantile_over_time(0.5, data[5m]) and quantile_over_time(0.9, data[5m]), both every 1m:

MEMO after pass2: Stage 1, Pass 2: local window composition
  G2 Aggregate quantile(q=0.5)  children=[1] parents=[] queries=[0] ROOT of q[0]
      cand 1 [pass1] Project ← SummaryEstimate Quantile(q=0.5) ← SummaryAgg Kll(failure_probability=1e-7 k=567)  reads=[1] implements=[2] budget_parts=1
      cand 3 [panes NEW] Project ← SummaryEstimate Quantile(q=0.5) ← SummaryMerge[newest all] ← PaneChain[5x60s] Kll(failure_probability=1e-7 k=567)  reads=[0] implements=[2] budget_parts=1
      cand 5 [panes NEW] Project ← SummaryEstimate Quantile(q=0.5) ← SummaryMerge[newest all] ← PaneChain[20x15s] Kll(failure_probability=1e-7 k=567)  reads=[0] implements=[2] budget_parts=1
...
STAGE 3: plan selection
  cost: 0.0213596 cost/s
    #2 SummaryAgg: 0.00335958  build Kll into 10000 states: 200000 rows x depth 1; x 0.0167/s; ...

Tests. test_print_stages.py plans that two-query workload with the built stage_pipeline and checks both modes. It is added to the viewer's CI step.

The committed examples/ documents predate #1108's format (the README calls them historical snapshots), so the script does not read them.

A follow-up PR renames stage_pipeline to explain_workload_plan.

🤖 Generated with Claude Code

[zzylol]

#1159 now prints the same content in Rust, as stage_pipeline --text (--out - for stdout), so the text and the viewer document come from one binary and one planning run. It covers this script's sections:

• the memo after each step, with new candidates;
• the selected choice;
• Stage 3's search status, cost per node and accepted accuracy per query;
• --enumerated with --max-enumerated.

It also prints Stage 2's whole PhysicalASAPMemoCandidates, which the JSON document does not hold. If that works for you, this PR could close in favor of #1159; the explain_workload_plan rename stays as its own PR.

[milindsrivastava1997]

Closing in favor of #1159, which prints the same stages as text from the planner's own data structures (stage_pipeline --text) instead of re-reading the JSON document.