Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions crates/planner/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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,
Expand Down
27 changes: 27 additions & 0 deletions crates/planner/src/tutorials/_01_background.md
Original file line number Diff line number Diff line change
@@ -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 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
[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).
31 changes: 31 additions & 0 deletions crates/planner/src/tutorials/_02_planning_a_workload.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# 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`) 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` (an `Option<f64>`) 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`.
22 changes: 22 additions & 0 deletions crates/planner/src/tutorials/_03_accuracy_targets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# 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 with
[`ErrorSelectingPlan::NoValidCandidate`](crate::ErrorSelectingPlan::NoValidCandidate).
28 changes: 28 additions & 0 deletions crates/planner/src/tutorials/_04_deployment_and_cost.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# 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),
[`ResourceSpeed`](crate::ResourceSpeed) and measured operation costs, set
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 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.
20 changes: 20 additions & 0 deletions crates/planner/src/tutorials/_05_executing_a_plan.md
Original file line number Diff line number Diff line change
@@ -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.
26 changes: 26 additions & 0 deletions crates/planner/src/tutorials/_06_extending.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# 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, 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.
34 changes: 34 additions & 0 deletions crates/planner/src/tutorials/mod.rs
Original file line number Diff line number Diff line change
@@ -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 {}
Loading