From 93ca79f3449863d311f179b9a91a6543a341a099 Mon Sep 17 00:00:00 2001 From: zzylol <50204836+zzylol@users.noreply.github.com> Date: Sat, 14 Nov 2026 19:50:12 +0000 Subject: [PATCH 1/2] docs(planner): outline egg-style tutorials in the asap-planner crate Add a doc-only tutorials module with six chapter outlines, each rendered from its own markdown file, and link them from the crate docs. --- crates/planner/src/lib.rs | 12 +++++++ .../planner/src/tutorials/_01_background.md | 27 +++++++++++++++ .../src/tutorials/_02_planning_a_workload.md | 28 +++++++++++++++ .../src/tutorials/_03_accuracy_targets.md | 21 ++++++++++++ .../src/tutorials/_04_deployment_and_cost.md | 22 ++++++++++++ .../src/tutorials/_05_executing_a_plan.md | 20 +++++++++++ crates/planner/src/tutorials/_06_extending.md | 24 +++++++++++++ crates/planner/src/tutorials/mod.rs | 34 +++++++++++++++++++ 8 files changed, 188 insertions(+) create mode 100644 crates/planner/src/tutorials/_01_background.md create mode 100644 crates/planner/src/tutorials/_02_planning_a_workload.md create mode 100644 crates/planner/src/tutorials/_03_accuracy_targets.md create mode 100644 crates/planner/src/tutorials/_04_deployment_and_cost.md create mode 100644 crates/planner/src/tutorials/_05_executing_a_plan.md create mode 100644 crates/planner/src/tutorials/_06_extending.md create mode 100644 crates/planner/src/tutorials/mod.rs diff --git a/crates/planner/src/lib.rs b/crates/planner/src/lib.rs index 11a98a6fa..f6628b986 100644 --- a/crates/planner/src/lib.rs +++ b/crates/planner/src/lib.rs @@ -16,6 +16,17 @@ //! ([`InstallablePlan`]). A caller who already holds pre-ASAP IR — a //! new frontend, a deserialized plan, a test that does not want to build SQL //! and a catalog — calls [`optimize`] with its own [`ParsedWorkload`]. +//! +//! # Tutorials +//! +//! The [`tutorials`] introduce the planner chapter by chapter, in order: +//! +//! 1. [Background](tutorials::_01_background) +//! 2. [Planning a workload](tutorials::_02_planning_a_workload) +//! 3. [Accuracy targets](tutorials::_03_accuracy_targets) +//! 4. [Deployment capabilities and cost](tutorials::_04_deployment_and_cost) +//! 5. [Executing a plan](tutorials::_05_executing_a_plan) +//! 6. [Extending the planner](tutorials::_06_extending) use asap_types::workload::parsed_workload::{ParsedWorkload, ParsedWorkloadError}; use asap_types::workload::SqlDialect; @@ -28,6 +39,7 @@ use asap_frontend_sql::{lower_sql_dialect, SqlError}; mod models; mod pass; mod run; +pub mod tutorials; pub use models::PlanningModels; pub use pass::{ optimize, OptimizationInput, OptimizationInputError, OptimizationPass, OptimizeError, diff --git a/crates/planner/src/tutorials/_01_background.md b/crates/planner/src/tutorials/_01_background.md new file mode 100644 index 000000000..40f6d7f29 --- /dev/null +++ b/crates/planner/src/tutorials/_01_background.md @@ -0,0 +1,27 @@ +# Background: why plan monitoring queries + +*This chapter is an outline; its content follows.* + +This chapter explains the problem ASAPPlanner solves and the vocabulary the +other chapters use. It is for anyone new to the planner, user or +contributor, and assumes only familiarity with a query language such as +PromQL or SQL. + +- Repeated monitoring queries: dashboards and alerts run the same queries on + a schedule over a growing data workload, so work can be shared and kept + between runs. +- Sketches: a summary such as a Count-Min sketch or KLL answers a statistic + approximately from a fraction of the state an exact answer needs + (`SketchAlgorithm`, `StatisticKind`). +- Materialization: a computation may be not materialized, built at ingestion + time, or built at query time (`ExecutionTiming`, `MaterializedView`). +- Memo group: one distinct sub-expression of the workload, shared by every + query that contains it (`Memo`, `MemoGroup`). +- Candidate: one way to compute a memo group, exact or with a sketch, shared + or reused (`CandidateForMemoGroup`). +- Plan: one candidate chosen per memo group, joined into the + [`PhysicalASAPDAG`](crate::PhysicalASAPDAG) that Stage 3 selects as the + cheapest plan meeting every query's requirements. +- The stages from workload to plan, in one picture: the + [planner pipeline](https://github.com/ProjectASAP/ASAPPlanner/blob/main/docs/design_docs/concepts/planner-pipeline.md); every term + is defined in the [glossary](https://github.com/ProjectASAP/ASAPPlanner/blob/main/docs/design_docs/concepts/glossary.md). diff --git a/crates/planner/src/tutorials/_02_planning_a_workload.md b/crates/planner/src/tutorials/_02_planning_a_workload.md new file mode 100644 index 000000000..68249cdb0 --- /dev/null +++ b/crates/planner/src/tutorials/_02_planning_a_workload.md @@ -0,0 +1,28 @@ +# Planning a workload + +*This chapter is an outline; its content follows.* + +This chapter plans one PromQL query over a data workload from start to +finish and reads what the planner returns. It is for users who call the +planner as a library and want the selected plan, its cost and the accuracy +each query gets. + +- The query workload: a [`PlanningWorkload`](crate::PlanningWorkload) holding + a `QueryWorkload` of `QueryWorkloadEntry` values, each a query with its + `QueryRequirements`, predictability and recurrence. +- The data workload: a `DataWorkload` describing the series the queries + read, their rate and their labels. +- The call: [`UserInput::new`](crate::UserInput::new) with + [`FrontendInput::Promql`](crate::FrontendInput::Promql) and + `PlanningModels::builtin()`, then + [`plan_installable`](crate::plan_installable). +- Reading the result: [`InstallablePlan`](crate::InstallablePlan) holds the + selected [`PhysicalASAPDAG`](crate::PhysicalASAPDAG) (`dag`, whose + `roots[i]` answers query `i`) and the `query_texts`; + [`SelectedPlanReport`](crate::SelectedPlanReport) holds its + `cost_per_second` and `predicted_usage`. +- The full selection report: [`run_planning`](crate::run_planning) returns a + [`PlanningRun`](crate::PlanningRun) whose `selection` holds the plan and its + [`Selection`](crate::Selection): `selected_plan_cost_per_second` and + `accepted_accuracy_per_query` ([`AcceptedAccuracy`](crate::AcceptedAccuracy)). +- Seeing the same plan from the command line: `asap-planner --output text`. diff --git a/crates/planner/src/tutorials/_03_accuracy_targets.md b/crates/planner/src/tutorials/_03_accuracy_targets.md new file mode 100644 index 000000000..9fcd0a0f3 --- /dev/null +++ b/crates/planner/src/tutorials/_03_accuracy_targets.md @@ -0,0 +1,21 @@ +# Accuracy targets + +*This chapter is an outline; its content follows.* + +This chapter shows how a query states how accurate its answer must be, and +how that choice decides between an exact computation and a sketch. It is for +users who want cheaper plans in exchange for a bounded error. + +- Where a target lives: `QueryRequirements::accuracy` on each + `QueryWorkloadEntry`; the default is exact. +- The builder: `AccuracyTarget::exact()`, or + `AccuracyTarget::max_error(ε)` refined with `.failure_probability(δ)`, + `.accuracy_metric(AccuracyMetric)` and `.accuracy_scope(AccuracyScope)`; + the same target in JSON. +- The three metrics in `AccuracyMetric` and what ε means in each. +- Exact versus sketch: one quantile query planned with + `AccuracyTarget::exact()` and again with a loose target, and the plans and + costs side by side. +- Reading what was accepted: [`AcceptedAccuracy`](crate::AcceptedAccuracy) in + [`Selection`](crate::Selection), and why a target no candidate meets makes + selection fail. diff --git a/crates/planner/src/tutorials/_04_deployment_and_cost.md b/crates/planner/src/tutorials/_04_deployment_and_cost.md new file mode 100644 index 000000000..155fa29ed --- /dev/null +++ b/crates/planner/src/tutorials/_04_deployment_and_cost.md @@ -0,0 +1,22 @@ +# Deployment capabilities and cost + +*This chapter is an outline; its content follows.* + +This chapter shows that the plan depends on the deployment as well as the +queries: what it can store and run, and what resources cost. It is for +users integrating the planner into a deployment and for anyone asking why +the planner chose one plan over another. + +- [`DeploymentCapabilities`](crate::DeploymentCapabilities): its + `supported_summaries` ([`SupportedSummary`](crate::SupportedSummary)), + `raw_data_retained` and `query_time_results_retained`, set through + `PlanningModels::with_deployment_capabilities`. +- [`CostInputs`](crate::CostInputs): its [`CostModel`](crate::CostModel) + (cost model 1, 2 or 3, with [`ResourceUnitCost`](crate::ResourceUnitCost)), + [`ResourceSpeed`](crate::ResourceSpeed) and measured operation costs, set + through `PlanningModels::with_cost_inputs`. +- One query, several plans: the same query planned with and without raw + data retained, and under two cost models, with each selected plan and its + cost. +- Why a candidate lost: reading [`Selection`](crate::Selection) and + [`RejectionCause`](crate::RejectionCause). diff --git a/crates/planner/src/tutorials/_05_executing_a_plan.md b/crates/planner/src/tutorials/_05_executing_a_plan.md new file mode 100644 index 000000000..b9230caba --- /dev/null +++ b/crates/planner/src/tutorials/_05_executing_a_plan.md @@ -0,0 +1,20 @@ +# Executing a plan + +*This chapter is an outline; its content follows.* + +This chapter takes the selected plan from the planner and runs it with +`asap-executor`, at ingestion time and at query time. It is for developers +building a deployment runtime on top of the planner. + +- The input: an [`InstallablePlan`](crate::InstallablePlan) from + [`plan_installable`](crate::plan_installable), its `dag` and the + materialized views it installs (`InstallablePlan::materialized_views`). +- Compile: `asap_executor::physical_planner::compile` turns the DAG, its views + and its roots into a `CompiledPhysicalDAG`, opening no reader. +- Instantiate: `CompiledPhysicalDAG::instantiate` binds every raw data and + materialized view slot to a `DataStore`, here an `InMemoryDataStore`. +- Execute: `PhysicalDAG::execute` with a `RunContext` whose `Scope` is + `Ingestion` (to build views) or `Query` (to answer a query at an + evaluation time). +- Reading the results: the returned batches, one per root, and checking them + against the exact answer. diff --git a/crates/planner/src/tutorials/_06_extending.md b/crates/planner/src/tutorials/_06_extending.md new file mode 100644 index 000000000..e447ff9c0 --- /dev/null +++ b/crates/planner/src/tutorials/_06_extending.md @@ -0,0 +1,24 @@ +# Extending the planner + +*This chapter is an outline; its content follows.* + +This chapter walks through the two most common contributions: a new sketch +family and a new reuse rule. It is for contributors, and complements the +recipes in [extend ASAP-aware mapping](https://github.com/ProjectASAP/ASAPPlanner/blob/main/docs/develop_docs/extend-asap-aware-mapping.md). + +- Adding a sketch family, one stage at a time: + - its type and parameters (`SketchAlgorithm`, `SketchParams`, + `parameter_list`) and its capability row + (`SketchAlgorithm::capability`, read by `SummaryTypeCapability`); + - offering it in Pass 1 (`ALGORITHM_PREFERENCE`, `summary_candidates`); + - its error model (`theoretical_guarantee`) and its cost + (`sketch_shape`); + - its executor kernel (`summary_kernels`, `EVALUATED_READOUTS`). +- Adding a reuse rule: a memo rule under Pass 2's `rules` that adds groups + (`Memo::find_or_add_group`) or candidates (`Memo::add_candidate`), called + from `generate_logical_asap_memo_candidates`. +- The rules every extension keeps: no stage calls another, every candidate + is kept until Stage 3, and summary families are read only through + `SummaryTypeCapability`. +- Testing an extension: unit tests beside the change and an end-to-end test + in `integration-tests` that the planned workload uses it. diff --git a/crates/planner/src/tutorials/mod.rs b/crates/planner/src/tutorials/mod.rs new file mode 100644 index 000000000..c02639c7c --- /dev/null +++ b/crates/planner/src/tutorials/mod.rs @@ -0,0 +1,34 @@ +//! # Tutorials +//! +//! A guide-level introduction to ASAPPlanner, read in order. Each chapter is +//! a doc-only module whose page comes from a markdown file beside this one, +//! so it renders next to the API docs and its code blocks run as doctests. +//! +//! 1. [`_01_background`]: monitoring queries, sketches and materialization; +//! memo groups, candidates and plans. +//! 2. [`_02_planning_a_workload`]: planning a PromQL workload and reading +//! the selected plan. +//! 3. [`_03_accuracy_targets`]: stating how accurate each query must be. +//! 4. [`_04_deployment_and_cost`]: how deployment capabilities and cost +//! inputs change the plan. +//! 5. [`_05_executing_a_plan`]: running the selected plan with +//! `asap-executor`. +//! 6. [`_06_extending`]: adding a sketch family or a reuse rule. + +#[doc = include_str!("_01_background.md")] +pub mod _01_background {} + +#[doc = include_str!("_02_planning_a_workload.md")] +pub mod _02_planning_a_workload {} + +#[doc = include_str!("_03_accuracy_targets.md")] +pub mod _03_accuracy_targets {} + +#[doc = include_str!("_04_deployment_and_cost.md")] +pub mod _04_deployment_and_cost {} + +#[doc = include_str!("_05_executing_a_plan.md")] +pub mod _05_executing_a_plan {} + +#[doc = include_str!("_06_extending.md")] +pub mod _06_extending {} From 8ed6ce90d799db0cba56ee60c6136b334f186e21 Mon Sep 17 00:00:00 2001 From: zzylol <50204836+zzylol@users.noreply.github.com> Date: Sat, 14 Nov 2026 19:59:53 +0000 Subject: [PATCH 2/2] docs(planner): correct tutorial outlines against the code Cost model 1 only in plan selection; failures via NoValidCandidate and pruned candidates via Selection::pruned_candidates; candidates pruned with a recorded reason; scalar_roots and Option cost in the plan report; a plan covers the groups the queries need. --- .../planner/src/tutorials/_01_background.md | 2 +- .../src/tutorials/_02_planning_a_workload.md | 9 ++++++--- .../src/tutorials/_03_accuracy_targets.md | 3 ++- .../src/tutorials/_04_deployment_and_cost.md | 20 ++++++++++++------- crates/planner/src/tutorials/_06_extending.md | 6 ++++-- 5 files changed, 26 insertions(+), 14 deletions(-) diff --git a/crates/planner/src/tutorials/_01_background.md b/crates/planner/src/tutorials/_01_background.md index 40f6d7f29..dc8fbf83f 100644 --- a/crates/planner/src/tutorials/_01_background.md +++ b/crates/planner/src/tutorials/_01_background.md @@ -19,7 +19,7 @@ PromQL or SQL. query that contains it (`Memo`, `MemoGroup`). - Candidate: one way to compute a memo group, exact or with a sketch, shared or reused (`CandidateForMemoGroup`). -- Plan: one candidate chosen per memo group, joined into the +- Plan: one candidate chosen for each group the queries need, joined into the [`PhysicalASAPDAG`](crate::PhysicalASAPDAG) that Stage 3 selects as the cheapest plan meeting every query's requirements. - The stages from workload to plan, in one picture: the diff --git a/crates/planner/src/tutorials/_02_planning_a_workload.md b/crates/planner/src/tutorials/_02_planning_a_workload.md index 68249cdb0..ea02cf9c7 100644 --- a/crates/planner/src/tutorials/_02_planning_a_workload.md +++ b/crates/planner/src/tutorials/_02_planning_a_workload.md @@ -17,10 +17,13 @@ each query gets. `PlanningModels::builtin()`, then [`plan_installable`](crate::plan_installable). - Reading the result: [`InstallablePlan`](crate::InstallablePlan) holds the - selected [`PhysicalASAPDAG`](crate::PhysicalASAPDAG) (`dag`, whose - `roots[i]` answers query `i`) and the `query_texts`; + selected [`PhysicalASAPDAG`](crate::PhysicalASAPDAG) (`dag`) and the + `query_texts`. The DAG's `roots` answer the queries over data, and + [`scalar_roots`](crate::PhysicalASAPDAG::scalar_roots) the standalone + scalar queries, each with its query index; `roots[i]` answers query `i` + only when the workload has no standalone scalar query. [`SelectedPlanReport`](crate::SelectedPlanReport) holds its - `cost_per_second` and `predicted_usage`. + `cost_per_second` (an `Option`) and `predicted_usage`. - The full selection report: [`run_planning`](crate::run_planning) returns a [`PlanningRun`](crate::PlanningRun) whose `selection` holds the plan and its [`Selection`](crate::Selection): `selected_plan_cost_per_second` and diff --git a/crates/planner/src/tutorials/_03_accuracy_targets.md b/crates/planner/src/tutorials/_03_accuracy_targets.md index 9fcd0a0f3..49465ea32 100644 --- a/crates/planner/src/tutorials/_03_accuracy_targets.md +++ b/crates/planner/src/tutorials/_03_accuracy_targets.md @@ -18,4 +18,5 @@ users who want cheaper plans in exchange for a bounded error. costs side by side. - Reading what was accepted: [`AcceptedAccuracy`](crate::AcceptedAccuracy) in [`Selection`](crate::Selection), and why a target no candidate meets makes - selection fail. + selection fail with + [`ErrorSelectingPlan::NoValidCandidate`](crate::ErrorSelectingPlan::NoValidCandidate). diff --git a/crates/planner/src/tutorials/_04_deployment_and_cost.md b/crates/planner/src/tutorials/_04_deployment_and_cost.md index 155fa29ed..8755cd241 100644 --- a/crates/planner/src/tutorials/_04_deployment_and_cost.md +++ b/crates/planner/src/tutorials/_04_deployment_and_cost.md @@ -11,12 +11,18 @@ the planner chose one plan over another. `supported_summaries` ([`SupportedSummary`](crate::SupportedSummary)), `raw_data_retained` and `query_time_results_retained`, set through `PlanningModels::with_deployment_capabilities`. -- [`CostInputs`](crate::CostInputs): its [`CostModel`](crate::CostModel) - (cost model 1, 2 or 3, with [`ResourceUnitCost`](crate::ResourceUnitCost)), +- [`CostInputs`](crate::CostInputs): its [`CostModel`](crate::CostModel), [`ResourceSpeed`](crate::ResourceSpeed) and measured operation costs, set - through `PlanningModels::with_cost_inputs`. + through `PlanningModels::with_cost_inputs`. Plan selection supports cost + model 1 (`CostModel::UsageOverTime` with its + [`ResourceUnitCost`](crate::ResourceUnitCost)); cost models 2 and 3 return + `ErrorSelectingPlan::UnsupportedCostModel`. - One query, several plans: the same query planned with and without raw - data retained, and under two cost models, with each selected plan and its - cost. -- Why a candidate lost: reading [`Selection`](crate::Selection) and - [`RejectionCause`](crate::RejectionCause). + data retained, and under different `ResourceUnitCost` and `ResourceSpeed` + values, with each selected plan and its cost. +- Candidates Stage 3 ruled out before selection, each with its reason: + [`Selection::pruned_candidates`](crate::Selection::pruned_candidates). +- When no plan is selected: + [`ErrorSelectingPlan::NoValidCandidate`](crate::ErrorSelectingPlan::NoValidCandidate), + with one `Rejection` (`id`, [`RejectionCause`](crate::RejectionCause), + `reason`) per candidate. diff --git a/crates/planner/src/tutorials/_06_extending.md b/crates/planner/src/tutorials/_06_extending.md index e447ff9c0..618c958c9 100644 --- a/crates/planner/src/tutorials/_06_extending.md +++ b/crates/planner/src/tutorials/_06_extending.md @@ -17,8 +17,10 @@ recipes in [extend ASAP-aware mapping](https://github.com/ProjectASAP/ASAPPlanne - Adding a reuse rule: a memo rule under Pass 2's `rules` that adds groups (`Memo::find_or_add_group`) or candidates (`Memo::add_candidate`), called from `generate_logical_asap_memo_candidates`. -- The rules every extension keeps: no stage calls another, every candidate - is kept until Stage 3, and summary families are read only through +- The rules every extension keeps: no stage calls another, a candidate is + pruned only with a recorded reason, never silently dropped (Pass 2's + dead-candidate elimination, Stage 3's `Selection::pruned_candidates`), and + summary families are read only through `SummaryTypeCapability`. - Testing an extension: unit tests beside the change and an end-to-end test in `integration-tests` that the planned workload uses it.