Repository navigation
Update the docs after the G1–G11 consolidation groups land #677
Description
Context
The open PRs above #577 are being consolidated into groups G1–G11:
- G1 (feat(planner): run the planning stages as the planner pipeline; retire MajorPass #674, refactor(planner): name the planner pipeline Stage 1 to Stage 3 and its fields by stage #675, merged): the planner pipeline
run_stage1_to_stage3. - G2 (refactor(planner): move Pass 1 helpers out of the legacy search; drop show_post_asap_ir, erp and empirical_comparison #676): removes the legacy replacement search, the legacy cost models and
dag_export. - G3–G11: the crate arrangement by planning stage, the Examples 1–4 work, materialization, deployment inputs, windows, and the viewer.
The user decided that these consolidation PRs do not change the Markdown docs. The docs are updated once, after the groups are done.
Docs to update after G1–G11
Many Markdown docs still describe the legacy search (MajorPass, global_selection, search_workload, the replacement strategies, dag_export, show_post_asap_ir, the legacy cost models). After the groups land they should describe the planning stages as implemented. Candidates, from the edits drafted in #676 and then reverted, and from the open docs PR #637:
- User guides:
docs/user_guide_docs/run-a-query.md(global_selection, the old binaries),stage-viewer.md(once G11 rebuilds the viewer onstage_pipeline). - Developer docs:
library-api.md,asap-aware-mapping-architecture.md,asap-aware-mapping-contracts.md,extend-asap-aware-mapping.md,end-to-end-accuracy-guarantees.md,replacement-explanations.md,offline-sketch-evidence.md,physical-handoff-costs.md,storage-operation-costs.md,planner-vocabulary-migration.md,target-candidate-api-migration.md,metrics-observability-corpora.md,README.md. - Design docs (architecture, concepts and proposals that reference the legacy search):
asap-aware-mapping.md,asap-aware-plan-search.md,evidence-dependent-candidates.md,input-output-workflow.md,updated_interface_with_pluggable_optimization.md,accuracy-models.md,planner-pipeline.md,post-asap-ir.md, theasap-aware-mapping/proposals,asapquery-rule-coverage.md,error-resource-profile.md; the decisionsconcat-unique-keys.mdandcse-cost-model.md(links to deleted files). - Root
README.mdanddocs/README.md.
Conventions to follow
- Names: use the planner-layering.md stage names. Code identifiers carry the stage number and name (
stage0_query_language_frontends,stage1_logical_asap_optimization,stage2_physical_asap_optimization,stage3_plan_selection; the pipelinerun_stage1_to_stage3/Stage1ToStage3Pass). - Docs to leave alone:
planner-layering.mdandasap-primitive-schema.mdkeep their own wording, e.g. "language-specific frontends". Change them only if the user asks. - Superseded docs: mark docs that describe removed designs as historical rather than deleting them, unless the user decides otherwise.
- Accuracy: describe actual behavior. Regenerate examples with
stage_pipelinerather than writing expected numbers by hand.
Done when
No Markdown doc describes removed APIs as current, and the user guides' commands and examples run as written.
Related: #637 (open docs PR, to fold in or close), #676, #528.
Activity
zzylol commentedon Oct 14, 2026
Doc follow-up for the
ResultGuarantee→AccuracyGuaranteerename (code rename: #691; reason: pairs withAccuracyTarget, see #690). These Markdown docs still sayResultGuaranteeand should sayAccuracyGuarantee(line numbers at main8eae5229):docs/design_docs/architecture/evidence-dependent-candidates.md: lines 13, 22, 28docs/design_docs/concepts/accuracy-models.md: lines 42docs/design_docs/concepts/post-asap-ir.md: lines 74, 93docs/design_docs/proposals/asap-aware-mapping/analytical-resource-cost.md: lines 871docs/design_docs/proposals/asap-aware-mapping/end-to-end-accuracy-guarantees.md: lines 203, 206, 219, 233, 236, 453docs/design_docs/proposals/asap-aware-mapping/summary-properties.md: lines 117docs/design_docs/proposals/asap-primitive-schema.md: lines 873, 907, 1327docs/design_docs/proposals/operator-sharing.md: lines 64, 348, 351, 384docs/develop_docs/end-to-end-accuracy-guarantees.md: lines 31, 58, 63, 64, 66, 70docs/develop_docs/pre-asap-ir.md: lines 35No serde wire name changes:
AccuracyGuaranteeis a struct, so its name does not appear in JSON.zzylol commentedon Oct 14, 2026
Docs made stale by #693 (HLL confidence from a deployment distinct-count bound, #678):
docs/design_docs/concepts/accuracy-models.md, "Example: bounded Classic HLL": the section still says a deployment suppliesEstimatorContract::ClassicHlland that the planner picks precision from the target. Both are gone. Now the deployment declaresDataWorkload.max_distinct_per_evaluation[source]. Stage 1 sizes precision from ε only and leaves δ symbolic asclassic_hll_failure_probability[p=P](max_distinct[source]). Stage 3 binds δ: a bound outside the contract's range gives δ = 1, and a missing bound leaves the target unmet.docs/design_docs/architecture/input-output-workflow.md,DataWorkloadstruct and field table: addmax_distinct_per_evaluation(it must be positive).stream_normsfrom feat(planner): compose accuracy guarantees through arithmetic over approximate values (#669, part a) #687 is also missing there.zzylol commentedon Oct 14, 2026
Doc follow-ups from G4 (#692), which changes no Markdown:
planner-layering-example1-acceptance.mdsays every candidate has three exact accumulators. In feat(planner): Example 1 completion — identical-expression CSE, whole-expression top-k heaps, counter-sample weights, per-second plan-selection cost #692, Q2's Count-Min and CountSketch heaps are whole-expression heaps that absorbsum_over_time, so those candidates have two (Q1's rate and sum).http_requests_totala counter (DataWorkload.metric_types), so plan selection confirms the weights and rejects the Count-Min candidate only because a top-k output has no guarantee. Without the declaration it is still rejected on its weights.planner-layering.mdExample 1 says Pass 2 gives "2 input choices (separate or shared)". Following Algorithm 2 line 31 (one candidate per non-empty subset of the sharing groups), feat(planner): Example 1 completion — identical-expression CSE, whole-expression top-k heaps, counter-sample weights, per-second plan-selection cost #692 gives 3: separate, shared scan, and shared scan and range selector. Example 1 therefore has 9 Stage 1 candidates (3 × 3).