diff --git a/Cargo.lock b/Cargo.lock index 933b01efb..6b77c8a73 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -294,8 +294,6 @@ name = "asap-cost" version = "0.1.0" dependencies = [ "asap-executor", - "asap-logical-asap-optimization", - "asap-physical-asap-optimization", "asap-types", "asap_sketchlib", "serde", @@ -312,10 +310,12 @@ dependencies = [ "asap-executor", "asap-frontend-promql", "asap-frontend-sql", - "asap-logical-asap-optimization", - "asap-physical-asap-optimization", - "asap-plan-selection", "asap-planner", + "asap-stage0-memo", + "asap-stage1-pass1-per-computation-candidates", + "asap-stage1-pass2-reuse-candidates", + "asap-stage2-physical-optimization", + "asap-stage3-plan-selection", "asap-types", "serde", "serde_json", @@ -331,8 +331,9 @@ dependencies = [ "arrow", "asap-executor", "asap-frontend-promql", - "asap-logical-asap-optimization", "asap-planner", + "asap-stage0-memo", + "asap-stage1-pass1-per-computation-candidates", "asap-types", "asap_sketchlib", "chrono", @@ -359,8 +360,6 @@ version = "0.1.0" dependencies = [ "asap-frontend-common", "asap-frontend-metricsql", - "asap-frontend-promql", - "asap-logical-asap-optimization", "asap-types", "metricsql_parser", "thiserror 2.0.18", @@ -370,10 +369,7 @@ dependencies = [ name = "asap-frontend-promql" version = "0.1.0" dependencies = [ - "asap-accuracy", "asap-frontend-common", - "asap-logical-asap-optimization", - "asap-planner", "asap-types", "promql-parser", ] @@ -384,8 +380,6 @@ version = "0.1.0" dependencies = [ "asap-frontend-common", "asap-frontend-sql", - "asap-logical-asap-optimization", - "asap-planner", "asap-sql-function-catalog", "asap-types", "datafusion", @@ -405,10 +399,11 @@ dependencies = [ "asap-executor", "asap-frontend-promql", "asap-frontend-sql", - "asap-logical-asap-optimization", - "asap-physical-asap-optimization", - "asap-plan-selection", "asap-planner", + "asap-stage0-memo", + "asap-stage1-pass1-per-computation-candidates", + "asap-stage2-physical-optimization", + "asap-stage3-plan-selection", "asap-types", "asap_sketchlib", "futures", @@ -417,67 +412,80 @@ dependencies = [ ] [[package]] -name = "asap-logical-asap-optimization" +name = "asap-planner" version = "0.1.0" dependencies = [ + "arrow", "asap-accuracy", + "asap-cost", + "asap-executor", + "asap-frontend-metricsql", "asap-frontend-promql", + "asap-frontend-sql", + "asap-stage0-memo", + "asap-stage1-pass1-per-computation-candidates", + "asap-stage1-pass2-reuse-candidates", + "asap-stage2-physical-optimization", + "asap-stage3-plan-selection", "asap-types", - "asap_sketchlib", - "rmp-serde", + "futures", "serde", "serde_json", "thiserror 2.0.18", + "tokio", ] [[package]] -name = "asap-physical-asap-optimization" +name = "asap-sql-function-catalog" +version = "0.1.0" + +[[package]] +name = "asap-stage0-memo" version = "0.1.0" dependencies = [ "asap-types", +] + +[[package]] +name = "asap-stage1-pass1-per-computation-candidates" +version = "0.1.0" +dependencies = [ + "asap-accuracy", + "asap-types", "thiserror 2.0.18", ] [[package]] -name = "asap-plan-selection" +name = "asap-stage1-pass2-reuse-candidates" version = "0.1.0" dependencies = [ "asap-accuracy", - "asap-cost", "asap-types", - "good_lp", - "highs", - "serde", - "serde_json", "thiserror 2.0.18", ] [[package]] -name = "asap-planner" +name = "asap-stage2-physical-optimization" +version = "0.1.0" +dependencies = [ + "asap-types", + "thiserror 2.0.18", +] + +[[package]] +name = "asap-stage3-plan-selection" version = "0.1.0" dependencies = [ - "arrow", "asap-accuracy", "asap-cost", - "asap-executor", - "asap-frontend-metricsql", - "asap-frontend-promql", - "asap-frontend-sql", - "asap-logical-asap-optimization", - "asap-physical-asap-optimization", - "asap-plan-selection", "asap-types", - "futures", + "good_lp", + "highs", "serde", "serde_json", "thiserror 2.0.18", - "tokio", ] -[[package]] -name = "asap-sql-function-catalog" -version = "0.1.0" - [[package]] name = "asap-types" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 4204bb33c..7b29da192 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,11 +4,13 @@ members = [ "crates/types", "crates/frontend-common", "crates/sql-function-catalog", - "crates/logical-asap-optimization", - "crates/physical-asap-optimization", + "crates/stage0-memo", + "crates/stage1-pass1-per-computation-candidates", + "crates/stage1-pass2-reuse-candidates", + "crates/stage2-physical-optimization", "crates/accuracy", "crates/cost", - "crates/plan-selection", + "crates/stage3-plan-selection", "crates/frontend-promql", "crates/frontend-metricsql", "crates/metricsql-common-parser-support", diff --git a/crates/cost/Cargo.toml b/crates/cost/Cargo.toml index 8a8e35fa9..5bbdc691c 100644 --- a/crates/cost/Cargo.toml +++ b/crates/cost/Cargo.toml @@ -18,8 +18,3 @@ serde_json = "1" # The executor's charge for each summary state, checked against the bytes # the state byte models give for it plus the accumulator's own fields (#947). asap-executor = { path = "../executor" } -# Physical plans of PromQL queries for the plan cost tests (tests/), built -# by the stages above this crate; `tests/held_memory.rs` builds them with -# the reference pricer's `optimize_physical_asap`. -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } -asap-physical-asap-optimization = { path = "../physical-asap-optimization" } diff --git a/crates/cost/src/lib.rs b/crates/cost/src/lib.rs index 1acc463c8..a9c2ac922 100644 --- a/crates/cost/src/lib.rs +++ b/crates/cost/src/lib.rs @@ -18,7 +18,7 @@ //! [`NodeUsage`]; [`plan_cost`] the whole plan's [`PlanCost`]. Stage 3 //! computes no cost of its own. //! -//! Plan selection (Stage 3, `asap-plan-selection`) documents how it prices +//! Plan selection (Stage 3, `asap-stage3-plan-selection`) documents how it prices //! a candidate with these. mod measured; mod model; diff --git a/crates/cost/src/plan/cost.rs b/crates/cost/src/plan/cost.rs index c9e56a904..fe385145b 100644 --- a/crates/cost/src/plan/cost.rs +++ b/crates/cost/src/plan/cost.rs @@ -1,7 +1,7 @@ //! Costing a physical plan DAG node by node: each node's resource usage //! ([`node_usage`]), then the plan's usage, latency, retention, retained //! tumbling window chains and cost ([`plan_cost`]). Moved from Stage 3 -//! (`asap-plan-selection`, whose module doc, "Cost model", describes the +//! (`asap-stage3-plan-selection`, whose module doc, "Cost model", describes the //! model), so Stage 3 computes no cost of its own. use std::collections::{BTreeMap, HashMap, HashSet}; diff --git a/crates/devtools/Cargo.toml b/crates/devtools/Cargo.toml index bb24e585b..1e6c69df1 100644 --- a/crates/devtools/Cargo.toml +++ b/crates/devtools/Cargo.toml @@ -12,10 +12,12 @@ edition = "2021" asap-frontend-promql = { path = "../frontend-promql" } asap-frontend-sql = { path = "../frontend-sql" } asap-accuracy = { path = "../accuracy" } -asap-logical-asap-optimization = { path = "../logical-asap-optimization" } -asap-physical-asap-optimization = { path = "../physical-asap-optimization" } +asap-stage0-memo = { path = "../stage0-memo" } +asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates" } +asap-stage1-pass2-reuse-candidates = { path = "../stage1-pass2-reuse-candidates" } +asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } asap-cost = { path = "../cost" } -asap-plan-selection = { path = "../plan-selection" } +asap-stage3-plan-selection = { path = "../stage3-plan-selection" } # The installable plan of the selected candidate (`installable_plan_of`), # whose stored outputs `asap_planner` writes. asap-planner = { path = "../planner" } @@ -34,9 +36,9 @@ tokio = { version = "1", features = ["rt", "macros", "rt-multi-thread"] } [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } -asap-physical-asap-optimization = { path = "../physical-asap-optimization" } +asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } # Pass 1's target list (`per_computation_candidates`) for the tests. -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } +asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates", features = ["test-support"] } [[test]] diff --git a/crates/devtools/src/bin/asap_planner.rs b/crates/devtools/src/bin/asap_planner.rs index 44857bc46..bef383ab9 100644 --- a/crates/devtools/src/bin/asap_planner.rs +++ b/crates/devtools/src/bin/asap_planner.rs @@ -76,9 +76,8 @@ // - memo: `nodes`, one node table for the section (each distinct node // once, children as indices before their parents), and `steps`, the // memo after each step run (`stage0`: the frontends' DAG hash-consed, -// groups without candidates; `pass1`; `pass2_local_window_composition`: -// local window composition's tumbling-window candidates; `pass2`: Pass -// 2's output, the memo Stage 2 implements). Each +// groups without candidates; `pass1`; `pass2`: Pass 2's output, the memo +// Stage 2 implements). Each // step lists its groups (`id`, `label`, `children`, `parents`, // `queries`, `roots_of`, `node`) and their candidates (`index`, // `implements`, `children`, `origin`, `accuracy_budget_parts`, `added` @@ -102,8 +101,8 @@ use asap_devtools::planning_stages::{ use asap_devtools::planning_stages_text::planning_stages_text; use asap_devtools::SqlCatalog; use asap_frontend_promql::{metric_type_warnings, promql_metric_names}; -use asap_plan_selection::{large_peak_memory_warning, AcceptedAccuracy, Selection}; use asap_planner::{installable_plan_of, PlanningModels, SelectionError}; +use asap_stage3_plan_selection::{large_peak_memory_warning, AcceptedAccuracy, Selection}; use asap_types::accuracy::{default_metric_for_root, AccuracyTarget}; use asap_types::deployment_capabilities::DeploymentCapabilities; use asap_types::ir::flat::{flatten, FlatDag, FlatNode}; @@ -380,13 +379,6 @@ fn memo_json(run: &PlanningStagesRun) -> Value { if let Some(pass1) = &run.run.pass1_memo { named.push(("pass1", "Stage 1, Pass 1", pass1)); } - if let Some(pass2) = &run.pass2_local_window_composition { - named.push(( - "pass2_local_window_composition", - "Stage 1, Pass 2: local window composition", - pass2, - )); - } if let Some(logical) = &run.run.logical_asap_candidates { named.push(("pass2", "Stage 1, Pass 2", &logical.memo)); } diff --git a/crates/devtools/src/bin/sketch_coverage.rs b/crates/devtools/src/bin/sketch_coverage.rs index 4af160d1e..4438a9b71 100644 --- a/crates/devtools/src/bin/sketch_coverage.rs +++ b/crates/devtools/src/bin/sketch_coverage.rs @@ -15,8 +15,8 @@ use asap_devtools::corpora::{ }; use asap_devtools::{lower_promql_with_sample_interval, SqlCatalog}; use asap_frontend_sql::lower_sql_dialect; -use asap_logical_asap_optimization::memo_of_queries; -use asap_logical_asap_optimization::pass1_memo; +use asap_stage0_memo::memo_of_queries; +use asap_stage1_pass1_per_computation_candidates::pass1_memo; use asap_types::ir::schema::FieldDataType; use asap_types::ir::{ASAPOp, Operator, OperatorNode, QueryRoot}; use asap_types::workload::SqlDialect; diff --git a/crates/devtools/src/planning_stages.rs b/crates/devtools/src/planning_stages.rs index 56967913c..c31b3d1b4 100644 --- a/crates/devtools/src/planning_stages.rs +++ b/crates/devtools/src/planning_stages.rs @@ -3,15 +3,14 @@ //! [`run_stages_until`] for `asap_planner`. use asap_frontend_sql::SqlCatalog; -use asap_logical_asap_optimization::{ - memo_of_queries, pass1_memo, pass2_after_local_window_composition, - pass2_local_window_composition, Pass1Error, -}; -use asap_physical_asap_optimization::generate_physical_asap_memo_candidates; -use asap_plan_selection::select_plan; use asap_planner::{ run_planning, PlanSearchSettings, PlanningModels, PlanningReport, PlanningRun, SelectionError, }; +use asap_stage0_memo::memo_of_queries; +use asap_stage1_pass1_per_computation_candidates::{pass1_memo, Pass1Error}; +use asap_stage1_pass2_reuse_candidates::generate_logical_asap_memo_candidates; +use asap_stage2_physical_optimization::generate_physical_asap_memo_candidates; +use asap_stage3_plan_selection::select_plan; use asap_types::ir::schema::series_identity::with_promql_series_identity; use asap_types::ir::schema::{DataType, Field, Schema}; use asap_types::ir::QueryRoot; @@ -70,9 +69,6 @@ pub struct PlanningStagesRun { /// Stage 0's memo groups (the roots hash-consed), without candidates; /// built by `run_stages_until` only (`asap_planner` prints them). pub stage0_memo_groups: Option, - /// Stage 1 Pass 2's memo after local window composition (rule 1), before - /// the other rules; `None` before Pass 2. - pub pass2_local_window_composition: Option, /// The stages' outputs: Pass 1, Pass 2, Stage 2 and the selection. pub run: PlanningRun, } @@ -201,7 +197,6 @@ pub fn run_search_over( Ok(PlanningStagesRun { run_until: RunUntil::Stage3, stage0_memo_groups: None, - pass2_local_window_composition: None, stage0_query_language_frontends: roots, run, }) @@ -232,7 +227,6 @@ pub fn run_stages_until( let mut stages = PlanningStagesRun { run_until: until, stage0_memo_groups: Some(stage0_dag.clone()), - pass2_local_window_composition: None, stage0_query_language_frontends: roots.clone(), run: PlanningRun { pass1_memo: None, @@ -273,15 +267,7 @@ pub fn run_stages_until( if until == RunUntil::Pass1 { return Ok(stages); } - let composed = match pass2_local_window_composition(pass1, entries) { - Ok(composed) => composed, - Err(error) => { - run.selection = Err(SelectionError::LogicalASAPCandidates(error.to_string())); - return Ok(stages); - } - }; - stages.pass2_local_window_composition = Some(composed.clone()); - let logical = match pass2_after_local_window_composition(composed, models.evidence) { + let logical = match generate_logical_asap_memo_candidates(pass1, entries, models.evidence) { Ok(logical) => logical, Err(error) => { run.selection = Err(SelectionError::LogicalASAPCandidates(error.to_string())); diff --git a/crates/devtools/src/planning_stages_text.rs b/crates/devtools/src/planning_stages_text.rs index 1f89f597a..d3e422865 100644 --- a/crates/devtools/src/planning_stages_text.rs +++ b/crates/devtools/src/planning_stages_text.rs @@ -68,23 +68,15 @@ pub fn planning_stages_text(stages: &PlanningStagesRun) -> String { return out; } - let (Some(pass2), Some(logical)) = ( - &stages.pass2_local_window_composition, - &run.logical_asap_candidates, - ) else { + let Some(logical) = &run.logical_asap_candidates else { failure(&mut out); return out; }; - section( - &mut out, - "Stage 1 Pass 2, after local window composition (tumbling-window candidates)", - ); - write_memo(&mut out, pass2, Some(pass1), true); section( &mut out, "Stage 1 Pass 2 output = Stage 2 input: LogicalASAPMemoCandidates", ); - write_memo(&mut out, &logical.memo, Some(pass2), true); + write_memo(&mut out, &logical.memo, Some(pass1), true); if until == RunUntil::Pass2 { return out; } diff --git a/crates/devtools/tests/asap_planner.rs b/crates/devtools/tests/asap_planner.rs index c15ff3c03..eb2623b54 100644 --- a/crates/devtools/tests/asap_planner.rs +++ b/crates/devtools/tests/asap_planner.rs @@ -1696,10 +1696,7 @@ fn memo_section_lists_each_step_and_the_selected_choice() { let memo = &document["memo"]; let steps = memo["steps"].as_array().unwrap(); let names: Vec<_> = steps.iter().map(|s| s["step"].as_str().unwrap()).collect(); - assert_eq!( - names, - ["stage0", "pass1", "pass2_local_window_composition", "pass2"] - ); + assert_eq!(names, ["stage0", "pass1", "pass2"]); let candidates = |step: &Value| -> u64 { step["groups"] .as_array() diff --git a/crates/devtools/tests/asap_planner_acceptance.rs b/crates/devtools/tests/asap_planner_acceptance.rs index 7567cbde3..f9c3068dc 100644 --- a/crates/devtools/tests/asap_planner_acceptance.rs +++ b/crates/devtools/tests/asap_planner_acceptance.rs @@ -180,10 +180,7 @@ fn json_sections_of_stages_not_run_are_null() { .iter() .map(|step| step["step"].as_str().unwrap()) .collect(); - assert_eq!( - steps, - ["stage0", "pass1", "pass2_local_window_composition", "pass2"] - ); + assert_eq!(steps, ["stage0", "pass1", "pass2"]); let stage3 = document("stage3"); assert!(stage3["stage2_physical_asap_optimization"].is_object()); diff --git a/crates/devtools/tests/viewer_contract.rs b/crates/devtools/tests/viewer_contract.rs index 316f0905e..4d3862e64 100644 --- a/crates/devtools/tests/viewer_contract.rs +++ b/crates/devtools/tests/viewer_contract.rs @@ -322,8 +322,8 @@ fn wire_name(value: T) -> String { /// `RejectionCause::failed_a_check` does. #[test] fn viewer_knows_every_view_refresh_and_rejection_cause() { - use asap_plan_selection::RejectionCause as C; use asap_planner::MaterializedViewRefresh as R; + use asap_stage3_plan_selection::RejectionCause as C; let refreshes = [R::AtIngestion, R::OnFirstRead]; for refresh in refreshes { // A new variant fails to compile here until it is listed above. diff --git a/crates/executor/Cargo.toml b/crates/executor/Cargo.toml index 231b6ed1d..7661ad112 100644 --- a/crates/executor/Cargo.toml +++ b/crates/executor/Cargo.toml @@ -27,7 +27,8 @@ test-support = ["planner-types/test-support"] [dev-dependencies] asap-executor = { path = ".", features = ["test-support"] } rmp-serde = "1" -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } +asap-stage0-memo = { path = "../stage0-memo" } +asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates", features = ["test-support"] } # The planning stages through the facade (a dev-dependency cycle, for # integration tests only). asap-planner = { path = "../planner" } diff --git a/crates/executor/tests/current_series_heap.rs b/crates/executor/tests/current_series_heap.rs index 9d70317c0..2b18c3592 100644 --- a/crates/executor/tests/current_series_heap.rs +++ b/crates/executor/tests/current_series_heap.rs @@ -336,11 +336,7 @@ fn population_fixture_compiles_with_dynamic_identity() { let topk = planner_types::ir::operator::maintained_population::PopulationStatistic::TopK { k: 1 }; let root = Rc::new(with_series_identity(&original).unwrap()); - let selected = asap_logical_asap_optimization::test_support::population_over_selector( - &root, - topk, - &["job"], - ); + let selected = planner_types::test_support::population_over_selector(&root, topk, &["job"]); let logical = planner_types::test_support::physical_asap_dag_at_query_time(&selected).unwrap(); let (source, raw_schema) = logical .nodes diff --git a/crates/executor/tests/deployment_computation.rs b/crates/executor/tests/deployment_computation.rs index 72fe68ded..9e552a07e 100644 --- a/crates/executor/tests/deployment_computation.rs +++ b/crates/executor/tests/deployment_computation.rs @@ -60,9 +60,8 @@ fn population_dag( grouping: &[&str], ) -> PhysicalASAPDAG { let root = promql_rows::with_series_identity(&lower(query)).unwrap(); - let selected = asap_logical_asap_optimization::test_support::population_over_selector( - &root, statistic, grouping, - ); + let selected = + planner_types::test_support::population_over_selector(&root, statistic, grouping); planner_types::test_support::physical_asap_dag_at_query_time(&selected).unwrap() } diff --git a/crates/executor/tests/physical_semantics.rs b/crates/executor/tests/physical_semantics.rs index da811c8fb..eb395598c 100644 --- a/crates/executor/tests/physical_semantics.rs +++ b/crates/executor/tests/physical_semantics.rs @@ -648,7 +648,7 @@ fn compacted_kll_tumbling_windows_merge_within_the_calibrated_rank_error() { const ROWS_PER_TUMBLING_WINDOW: u64 = 1000; const K: u32 = 200; // The planner's empirical 99% KLL rank error, `2.296 / k^0.9723` - // (`asap_logical_asap_optimization`'s `kll_rank_error_99`). + // (`asap_accuracy`'s `kll_rank_error_99`). let bound = 2.296 / f64::from(K).powf(0.9723); let n = (TUMBLING_WINDOW_COUNT * ROWS_PER_TUMBLING_WINDOW) as f64; let input = schema(&[("v", DataType::Float64, false)]); diff --git a/crates/frontend-common/src/canonicalize.rs b/crates/frontend-common/src/canonicalize.rs index 6123568cb..8701574f3 100644 --- a/crates/frontend-common/src/canonicalize.rs +++ b/crates/frontend-common/src/canonicalize.rs @@ -1,7 +1,7 @@ //! Post-lowering canonicalization of the operator DAG. //! //! Rewrites equivalent spellings of a query into one shape, so that common -//! sub-DAG sharing (hash-consing, `Memo::find_or_add_group`) can match +//! sub-DAG sharing (Stage 0 hash-consing, `cse` in `asap_stage0_memo`) can match //! them by structural equality, whichever front end produced them. //! //! ## Heavy-hitter promotion diff --git a/crates/frontend-metricsql/Cargo.toml b/crates/frontend-metricsql/Cargo.toml index 719d49a5e..912119261 100644 --- a/crates/frontend-metricsql/Cargo.toml +++ b/crates/frontend-metricsql/Cargo.toml @@ -22,6 +22,3 @@ path = "tests/main.rs" [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } asap-frontend-metricsql = { path = ".", features = ["test-support"] } -asap-frontend-promql = { path = "../frontend-promql" } -# `support.rs` (shared with frontend-promql's tests) binds through Pass 1. -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } diff --git a/crates/frontend-metricsql/tests/external_corpus.rs b/crates/frontend-metricsql/tests/external_corpus.rs deleted file mode 100644 index aafe36049..000000000 --- a/crates/frontend-metricsql/tests/external_corpus.rs +++ /dev/null @@ -1,61 +0,0 @@ -//! An out-of-tree MetricsQL corpus: every query lowers and binds without -//! panicking. The queries live outside this repository (e.g. a private -//! corpus); the test reads every `*.txt` in `$ASAP_EXTERNAL_CORPUS_DIR` and -//! passes trivially when it is unset, so CI still compiles it on every PR. -//! -//! Each file holds one query per line (`#` lines are comments) and a -//! `# floor: N` line: the minimum number of its queries that must lower. -//! Raise a floor to the current `lowered` count when coverage improves. -//! -//! `ASAP_EXTERNAL_CORPUS_DIR= cargo test -p asap-frontend-metricsql -//! --test metricsql external_corpus:: -- --nocapture` - -fn queries(corpus: &str) -> impl Iterator { - corpus - .lines() - .map(str::trim) - .filter(|l| !l.is_empty() && !l.starts_with('#')) -} - -/// The `# floor: N` line's `N`. -fn floor(corpus: &str) -> Option { - corpus - .lines() - .find_map(|l| l.trim().strip_prefix("# floor:")) - .and_then(|n| n.trim().parse().ok()) -} - -/// `msg` with sanitized identifiers replaced by `_` and digit runs by `N`, so -/// the same failure in different queries groups under one message. -fn normalize(msg: &str) -> String { - let mut out = String::new(); - let mut word = String::new(); - for c in msg.chars().chain([' ']) { - if c.is_alphanumeric() || c == '_' { - word.push(c); - continue; - } - if word.starts_with("sanitized_") { - out.push('_'); - } else if !word.is_empty() && word.chars().all(|c| c.is_ascii_digit()) { - out.push('N'); - } else { - out.push_str(&word); - } - word.clear(); - out.push(c); - } - out.pop(); - out -} - -#[test] -fn floor_line() { - assert_eq!(floor("# floor: 25\nrate(x[5m])"), Some(25)); - assert_eq!(floor("rate(x[5m])"), None); - assert_eq!( - queries("# floor: 3\n\n up \n# c").collect::>(), - ["up"] - ); - assert_eq!(normalize("sanitized_foo at 123"), "_ at N"); -} diff --git a/crates/frontend-metricsql/tests/lowering_semantics.rs b/crates/frontend-metricsql/tests/lowering_semantics.rs index 37284b71b..c369e4e8e 100644 --- a/crates/frontend-metricsql/tests/lowering_semantics.rs +++ b/crates/frontend-metricsql/tests/lowering_semantics.rs @@ -145,16 +145,3 @@ fn workload_lowering_uses_the_declared_sample_interval() { }); lower_metricsql_query_workload(&at_rest).unwrap(); } - -/// Vector negation lowers to the same IR as PromQL's: a sample-value -/// `Negative` that drops the metric name, not a multiplication by -1. -#[test] -fn vector_negation_lowers_as_in_promql() { - let query = "-rate(up[5m])"; - let metricsql = - lower_metricsql_query_workload(&workload(QueryLanguage::MetricsQL, query)).unwrap(); - let promql = - asap_frontend_promql::lower_promql_query_workload(&workload(QueryLanguage::PromQL, query)) - .unwrap(); - assert_eq!(metricsql, promql); -} diff --git a/crates/frontend-metricsql/tests/main.rs b/crates/frontend-metricsql/tests/main.rs index f3aa9f7c9..0c8315d09 100644 --- a/crates/frontend-metricsql/tests/main.rs +++ b/crates/frontend-metricsql/tests/main.rs @@ -2,12 +2,6 @@ //! its own copy of every dependency, which outgrew CI's disk. //! One file: `cargo test -p asap-frontend-metricsql --test metricsql ::`. -mod external_corpus; mod lowering; mod lowering_semantics; mod victoriametrics_go_golden; - -// The PromQL tests' binding helpers (`logical_plan`), for `external_corpus`. -#[path = "../../frontend-promql/tests/support.rs"] -#[allow(dead_code)] -mod support; diff --git a/crates/frontend-promql/Cargo.toml b/crates/frontend-promql/Cargo.toml index 541f1f97f..c65fb30ff 100644 --- a/crates/frontend-promql/Cargo.toml +++ b/crates/frontend-promql/Cargo.toml @@ -18,12 +18,6 @@ promql-parser = { git = "https://github.com/ProjectASAP/promql-parser", rev = "1 [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } -asap-accuracy = { path = "../accuracy", features = ["test-support"] } -# Pass 1's target list (`per_computation_candidates`) for the tests. -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } -# The planning stages through the facade (a dev-dependency cycle, for -# integration tests only). -asap-planner = { path = "../planner" } # Corpus tests live in domain folders (observability) but must still be declared # as test targets — Cargo only auto-discovers `.rs` files directly in `tests/`. diff --git a/crates/frontend-promql/tests/count_planning.rs b/crates/frontend-promql/tests/count_planning.rs index c53da52ea..c8d87a8c1 100644 --- a/crates/frontend-promql/tests/count_planning.rs +++ b/crates/frontend-promql/tests/count_planning.rs @@ -1,33 +1,8 @@ //! Query text through summary selection: counts use observations, never value weights. -use crate::planner_support::selected_dag; use crate::support; use asap_types::accuracy::AccuracyTarget; -use asap_types::ir::schema::FieldDataType; -use asap_types::ir::{ASAPOp, Operator, OperatorNode}; -use asap_types::summary_type::ExactKind; use support::lower_promql; -// Exact series and temporal counts must select a count accumulator, not distinct or sum. -#[test] -fn exact_counts_select_count_accumulators() { - for query in ["count(up)", "count by(job)(up)", "count_over_time(up[5m])"] { - let root = lower_promql(query, AccuracyTarget::exact()).unwrap(); - let selected = selected_dag(root, AccuracyTarget::exact()); - assert!( - OperatorNode::reachable(&selected).iter().any(|node| { - matches!( - &node.operator, - Operator::ASAP(ASAPOp::SummaryAgg { - summary_type: FieldDataType::ExactAggregate(ExactKind::Count, _), - .. - }) - ) - }), - "{query}: {selected:?}" - ); - } -} - // Fixtures are already selected at one instant or within one five-minute window. // This narrow test oracle interprets the emitted aggregate, not Prometheus ingestion, // staleness, or scrape scheduling. Unsupported plan shapes fail explicitly. @@ -117,14 +92,3 @@ fn count_over_time_counts_scrapes_not_sample_values() { vec![10.0, 10.0] ); } - -// The assertion helper must fail on an injected composition error; its coverage -// must not depend on a real planner bug remaining unfixed. -#[test] -#[should_panic(expected = "does not compose")] -fn logical_candidates_fails_on_a_candidate_that_does_not_compose() { - support::require_composed_operator_candidates(vec![support::LogicalCandidate { - id: "invalid-composition".into(), - roots: Err("invalid choice".into()), - }]); -} diff --git a/crates/frontend-promql/tests/main.rs b/crates/frontend-promql/tests/main.rs index b962cb00b..6055452b4 100644 --- a/crates/frontend-promql/tests/main.rs +++ b/crates/frontend-promql/tests/main.rs @@ -2,7 +2,6 @@ //! its own copy of every dependency, which outgrew CI's disk. //! One file: `cargo test -p asap-frontend-promql --test promql ::`. -mod planner_support; mod support; mod count_planning; diff --git a/crates/frontend-promql/tests/planner_support.rs b/crates/frontend-promql/tests/planner_support.rs deleted file mode 100644 index 9be35e5f8..000000000 --- a/crates/frontend-promql/tests/planner_support.rs +++ /dev/null @@ -1,45 +0,0 @@ -//! Planner-facade helpers for this crate's tests. Kept out of `support.rs`, -//! which the private corpus also compiles without depending on asap-planner. -use std::rc::Rc; - -use asap_types::accuracy::AccuracyTarget; -use asap_types::ir::OperatorNode; - -use crate::support::declared_data; - -/// Every planning stage's output for the single query `root` at `accuracy`, -/// with the built-in models. -pub fn run_all_stages( - root: Rc, - accuracy: AccuracyTarget, -) -> asap_planner::PlanningRun { - let data = declared_data(&root); - asap_planner::run_planning( - vec![asap_types::ir::QueryRoot::Operator(root)], - &[asap_types::workload::QueryWorkloadEntry { - query: Default::default(), - requirements: asap_types::workload::QueryRequirements { - accuracy, - max_latency_ms: None, - }, - predictability: Default::default(), - recurrence: Default::default(), - range_evaluation: None, - }], - &data, - asap_planner::PlanningModels::builtin(), - asap_planner::PlanSearchSettings::default(), - ) - .expect("Pass 1 accepts the query") -} - -/// The logical DAG the planner pipeline selects for the single query `root` -/// at `accuracy`. -pub fn selected_dag(root: Rc, accuracy: AccuracyTarget) -> Rc { - let run = run_all_stages(root, accuracy); - let (plan, _) = run.selection.as_ref().expect("a plan is selected"); - match plan.query_roots().unwrap().as_slice() { - [asap_types::ir::QueryRoot::Operator(node)] => Rc::clone(node), - other => panic!("one operator root: {other:?}"), - } -} diff --git a/crates/frontend-promql/tests/support.rs b/crates/frontend-promql/tests/support.rs index fa6b6db5f..bb5c831af 100644 --- a/crates/frontend-promql/tests/support.rs +++ b/crates/frontend-promql/tests/support.rs @@ -76,16 +76,6 @@ pub fn promql_scalar(node: &ScalarExpr) -> Option { } } -/// Time `root` under the default physical properties assignment (every summary -/// at query time) and export the physical DAG — export needs every node -/// timed first. -#[allow(dead_code)] -pub fn physical_asap_dag( - root: &Rc, -) -> asap_types::plan::physical_asap_dag::PhysicalASAPDAG { - asap_types::test_support::physical_asap_dag_at_query_time(root).expect("post-ASAP DAG export") -} - #[allow(dead_code)] pub fn scalar_root(query: &str) -> ScalarExpr { match lower_promql_query_workload(&workload(query, AccuracyTarget::exact())) @@ -107,59 +97,3 @@ pub fn sample_expression(node: &OperatorNode) -> &ScalarExpr { other => panic!("expected sample expression, got {other:?}"), } } - -/// The data these tests plan over, declared: 1,000 rows arriving per -/// second, and each metric `root` reads holding 1,000 series. -#[allow(dead_code)] -pub fn declared_data(root: &Rc) -> DataWorkload { - let sources = OperatorNode::reachable(root) - .into_iter() - .filter_map(|node| match node.non_asap() { - Some(NonASAPOp::Scan { - source: asap_types::ir::operator::Source::TimeSeries { metric }, - .. - }) => Some(( - metric.clone(), - asap_types::workload::SourceFacts { - series_count: Some(1_000), - ..Default::default() - }, - )), - _ => None, - }) - .collect(); - DataWorkload { - arrival: asap_types::workload::DataArrival::Ingesting { - rows_per_second: 1_000.0, - max_out_of_order_ms: None, - }, - sources, - } -} - -/// A composed logical candidate, or why it does not compose. -#[allow(dead_code)] -pub struct LogicalCandidate { - pub id: String, - pub roots: Result, String>, -} - -/// Fail on a rejected candidate rather than silently dropping it from assertions. -#[allow(dead_code)] -pub fn require_composed_operator_candidates( - candidates: Vec, -) -> Vec> { - candidates - .into_iter() - .filter_map(|candidate| { - match candidate - .roots - .unwrap_or_else(|e| panic!("{} does not compose: {e}", candidate.id)) - .remove(0) - { - asap_types::ir::QueryRoot::Operator(node) => Some(node), - asap_types::ir::QueryRoot::Scalar(_) => None, - } - }) - .collect() -} diff --git a/crates/frontend-sql/Cargo.toml b/crates/frontend-sql/Cargo.toml index d210f0a0e..70b1333eb 100644 --- a/crates/frontend-sql/Cargo.toml +++ b/crates/frontend-sql/Cargo.toml @@ -36,11 +36,6 @@ test-support = [] [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } asap-frontend-sql = { path = ".", features = ["test-support"] } -# Pass 1's target list (`per_computation_candidates`) for the tests. -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } -# The planning stages through the facade (a dev-dependency cycle, for -# integration tests only). -asap-planner = { path = "../planner" } tokio = { version = "1", features = ["rt", "macros", "rt-multi-thread"] } # bgp_jan2024_workload corpus is sourced verbatim as YAML (ASAPQuery PR #561) # rather than transcribed into the flat .sql shape the other corpora use. diff --git a/crates/frontend-sql/tests/frequency_l2.rs b/crates/frontend-sql/tests/frequency_l2.rs index bd8261de3..1a433905c 100644 --- a/crates/frontend-sql/tests/frequency_l2.rs +++ b/crates/frontend-sql/tests/frequency_l2.rs @@ -6,7 +6,6 @@ use asap_frontend_sql::{lower_sql, SqlCatalog}; use asap_types::ir::operator::AggIntent; use asap_types::ir::schema::{DataType, Field, Schema}; use asap_types::ir::{NonASAPOp, OperatorNode}; -use asap_types::stages::HowToComputeAggregateMeasure; use std::rc::Rc; fn catalog(nullable: bool) -> SqlCatalog { @@ -103,43 +102,6 @@ async fn frequency_empty_input_guard_uses_an_exact_count() { assert!(matches!(measures.as_slice(), [AggIntent::Count])); } -/// Stage 1 offers the exact option and summary candidates for the -/// recognized L2 intent. -#[tokio::test] -async fn stage1_offers_exact_and_summary_l2_candidates() { - use asap_logical_asap_optimization::test_support::generate_per_computation_candidates; - use asap_types::ir::QueryRoot; - let root = lower_sql(CAST_COUNT, &catalog(false)).await.unwrap(); - let inventory = generate_per_computation_candidates( - &asap_logical_asap_optimization::memo_of_queries( - &[QueryRoot::Operator(root)], - &[None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap(); - let l2 = inventory - .targets - .iter() - .find(|t| has_l2(inventory.aggregate(t))) - .expect("L2 target"); - let candidates = &l2.ways_to_compute; - assert!( - candidates.iter().any(|c| matches!( - c, - HowToComputeAggregateMeasure::Exact | HowToComputeAggregateMeasure::ExactAccumulator(_) - )), - "{candidates:?}" - ); - assert!( - candidates - .iter() - .any(|c| matches!(c, HowToComputeAggregateMeasure::Summary(_))), - "{candidates:?}" - ); -} - /// #509 Example 2 over `flows(ts, src_ip)` with its one-minute window: Q2 /// lowers to entropy and the Float64 Q3 to L2; the design's literal Int64 /// Q3 stays relational. diff --git a/crates/integration-tests/Cargo.toml b/crates/integration-tests/Cargo.toml index c8ee40b02..dbe28ea89 100644 --- a/crates/integration-tests/Cargo.toml +++ b/crates/integration-tests/Cargo.toml @@ -9,11 +9,12 @@ autotests = false asap-types = { path = "../types", features = ["test-support"] } asap-frontend-promql = { path = "../frontend-promql" } asap-frontend-sql = { path = "../frontend-sql" } -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } -asap-physical-asap-optimization = { path = "../physical-asap-optimization" } +asap-stage0-memo = { path = "../stage0-memo" } +asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates", features = ["test-support"] } +asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } asap-accuracy = { path = "../accuracy" } asap-cost = { path = "../cost" } -asap-plan-selection = { path = "../plan-selection" } +asap-stage3-plan-selection = { path = "../stage3-plan-selection" } # The fixtures plan through the facade and the developer tools' reference # enumeration. asap-planner = { path = "../planner" } @@ -22,7 +23,7 @@ asap-devtools = { path = "../devtools" } [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } asap-accuracy = { path = "../accuracy", features = ["test-support"] } -asap-physical-asap-optimization = { path = "../physical-asap-optimization" } +asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } asap-devtools = { path = "../devtools" } # The tests plan PromQL and SQL workloads through the facade. asap-planner = { path = "../planner" } diff --git a/crates/integration-tests/tests/crate_graph.rs b/crates/integration-tests/tests/crate_graph.rs index 2eca8fe81..1dcb0ec12 100644 --- a/crates/integration-tests/tests/crate_graph.rs +++ b/crates/integration-tests/tests/crate_graph.rs @@ -1,11 +1,15 @@ //! The workspace crate graph follows #1054's target graph (its rule 4). //! //! The test reads `cargo metadata --format-version 1 --no-deps` and checks every -//! `[dependencies]` edge between two workspace crates. Dev- and -//! build-dependencies are not checked. Each crate has a role ([`role_of`]), and -//! [`rule_violated`] says which role may depend on which: +//! `[dependencies]` edge between two workspace crates, and every +//! `[dev-dependencies]` edge from a stage crate to another stage crate or to +//! the facade (a test of one stage never calls another stage, directly or +//! through `asap-planner`). Build-dependencies are not checked. Each crate +//! has a role ([`role_of`]), and [`rule_violated`] says which role may depend +//! on which: //! -//! - **stage crates** (the frontends, logical, physical, plan-selection) never +//! - **stage crates** (the frontends, Stage 0's memo, Stage 1's Pass 1 and +//! Pass 2, Stage 2's physical optimization, Stage 3's plan selection) never //! depend on each other; they may depend on the shared crates; //! - **asap-accuracy** and **asap-cost** depend only on asap-types; //! - **asap-types** depends on no workspace crate; @@ -16,8 +20,9 @@ //! - **devtools** and **integration-tests** may depend on anything, and no //! other crate may depend on them. //! -//! The edges the rules forbid but the workspace has today are listed, each -//! with its reason, in [`EXCEPTIONS`]. A new workspace crate fails the test +//! The `[dependencies]` edges the rules forbid but the workspace has today are +//! listed, each with its reason, in [`EXCEPTIONS`]; no `[dev-dependencies]` +//! edge is excepted. A new workspace crate fails the test //! until it gets a role. use serde_json::Value; @@ -31,8 +36,8 @@ enum Role { SharedModel, /// Helper crates of the frontends that are no stage themselves. FrontendHelper, - /// A stage crate: a frontend (Stage 0), logical (Stage 1), physical - /// (Stage 2) or plan-selection (Stage 3). + /// A stage crate: a frontend, Stage 0 (memo), Stage 1 (Pass 1 or Pass 2), + /// Stage 2 (physical optimization) or Stage 3 (plan selection). Stage, /// `asap-planner`: orchestrates the stages and owns the public API. Facade, @@ -53,9 +58,11 @@ fn role_of(name: &str) -> Option { "asap-frontend-promql" | "asap-frontend-sql" | "asap-frontend-metricsql" - | "asap-logical-asap-optimization" - | "asap-physical-asap-optimization" - | "asap-plan-selection" => Role::Stage, + | "asap-stage0-memo" + | "asap-stage1-pass1-per-computation-candidates" + | "asap-stage1-pass2-reuse-candidates" + | "asap-stage2-physical-optimization" + | "asap-stage3-plan-selection" => Role::Stage, "asap-planner" => Role::Facade, "asap-executor" => Role::Runtime, "asap-devtools" | "asap-integration-tests" => Role::Unrestricted, @@ -87,38 +94,22 @@ fn rule_violated(from: Role, to: Role) -> Option<&'static str> { } } -/// A forbidden edge the workspace keeps on purpose. -struct Exception { - from: &'static str, - to: &'static str, - /// The exception holds only while the dependency is `optional = true`. - only_if_optional: bool, -} +/// A forbidden edge the workspace keeps on purpose: (from, to). +type Exception = (&'static str, &'static str); -/// The forbidden edges the workspace keeps today. +/// The forbidden `[dependencies]` edges the workspace keeps today. const EXCEPTIONS: &[Exception] = &[ - // Logical's `test-support` feature lowers PromQL test queries for other - // crates' tests. The dependency is optional and enabled only by that - // feature, so no production build links Stage 0 into Stage 1. Made - // non-optional, the edge fails the test. - Exception { - from: "asap-logical-asap-optimization", - to: "asap-frontend-promql", - only_if_optional: true, - }, // `plan_installable` offers only the summaries the Planner's own executor // implements. #1016 decides where that kernel list and the executor // belong; this exception goes away with it. - Exception { - from: "asap-planner", - to: "asap-executor", - only_if_optional: false, - }, + ("asap-planner", "asap-executor"), ]; -/// One message per `[dependencies]` edge of `metadata` (the JSON of +/// One message per edge of `metadata` (the JSON of /// `cargo metadata --format-version 1 --no-deps`) that breaks a rule, naming -/// the edge and the rule. +/// the edge and the rule: a `[dependencies]` edge that [`rule_violated`] +/// forbids, or a `[dev-dependencies]` edge from a stage crate to another +/// stage crate or the facade. fn crate_graph_violations(metadata: &Value) -> Vec { let packages = metadata["packages"] .as_array() @@ -138,28 +129,38 @@ fn crate_graph_violations(metadata: &Value) -> Vec { continue; }; for dependency in package["dependencies"].as_array().into_iter().flatten() { - // `kind` is null for `[dependencies]`, "dev" or "build" otherwise. - if !dependency["kind"].is_null() { - continue; - } let to = dependency["name"].as_str().expect("dependency `name`"); - if !names.contains(&to) { + if !names.contains(&to) || to == from { continue; } let Some(to_role) = role_of(to) else { // Reported once, as its own package above. continue; }; - let Some(rule) = rule_violated(from_role, to_role) else { + // `kind` is null for `[dependencies]`, "dev" or "build" otherwise. + let (section, rule, exceptions) = match dependency["kind"].as_str() { + None => ( + "[dependencies]", + rule_violated(from_role, to_role), + EXCEPTIONS, + ), + Some("dev") => ( + "[dev-dependencies]", + (from_role == Role::Stage && matches!(to_role, Role::Stage | Role::Facade)) + .then_some( + "a stage crate's tests never call another stage crate, \ + directly or through the facade", + ), + &[][..], + ), + Some(_) => continue, + }; + let Some(rule) = rule else { continue; }; - let optional = dependency["optional"].as_bool().unwrap_or(false); - let excepted = EXCEPTIONS - .iter() - .any(|e| e.from == from && e.to == to && (optional || !e.only_if_optional)); - if !excepted { + if !exceptions.contains(&(from, to)) { violations.push(format!( - "forbidden [dependencies] edge {from} -> {to}: {rule} (#1054)" + "forbidden {section} edge {from} -> {to}: {rule} (#1054)" )); } } @@ -193,14 +194,14 @@ fn workspace_crate_graph_follows_the_target_graph() { } /// A package of synthetic `cargo metadata` JSON with `[dependencies]` on -/// `deps` (name, optional) and a dev-dependency on `dev_deps`. -fn package(name: &str, deps: &[(&str, bool)], dev_deps: &[&str]) -> Value { +/// `deps` and `[dev-dependencies]` on `dev_deps`. +fn package(name: &str, deps: &[&str], dev_deps: &[&str]) -> Value { let normal = deps .iter() - .map(|(d, optional)| serde_json::json!({"name": d, "kind": null, "optional": optional})); + .map(|d| serde_json::json!({"name": d, "kind": null})); let dev = dev_deps .iter() - .map(|d| serde_json::json!({"name": d, "kind": "dev", "optional": false})); + .map(|d| serde_json::json!({"name": d, "kind": "dev"})); serde_json::json!({"name": name, "dependencies": normal.chain(dev).collect::>()}) } @@ -208,56 +209,72 @@ fn package(name: &str, deps: &[(&str, bool)], dev_deps: &[&str]) -> Value { fn checker_rejects_an_edge_between_stage_crates() { let metadata = serde_json::json!({"packages": [ package("asap-types", &[], &[]), - package("asap-cost", &[("asap-types", false)], &[]), - package("asap-physical-asap-optimization", &[("asap-types", false)], &[]), + package("asap-cost", &["asap-types"], &[]), + package("asap-stage2-physical-optimization", &["asap-types"], &[]), // Forbidden: Stage 3 on Stage 2. package( - "asap-plan-selection", - &[("asap-cost", false), ("asap-physical-asap-optimization", false)], + "asap-stage3-plan-selection", + &["asap-cost", "asap-stage2-physical-optimization"], &[], ), ]}); assert_eq!( crate_graph_violations(&metadata), - vec!["forbidden [dependencies] edge asap-plan-selection -> \ - asap-physical-asap-optimization: stage crates never depend on each other (#1054)" - .to_string()] + vec![ + "forbidden [dependencies] edge asap-stage3-plan-selection -> \ + asap-stage2-physical-optimization: stage crates never depend on each other (#1054)" + .to_string() + ] ); } #[test] -fn checker_ignores_dev_dependencies_and_external_crates() { +fn checker_ignores_external_crates_and_non_stage_dev_dependencies() { let metadata = serde_json::json!({"packages": [ - package("asap-types", &[("serde", false)], &[]), - package("asap-logical-asap-optimization", &[("asap-types", false)], &[]), + package("asap-types", &["serde"], &[]), + package("asap-stage1-pass1-per-computation-candidates", &["asap-types"], &[]), + package("asap-executor", &["asap-types"], &["asap-stage1-pass1-per-computation-candidates"]), + ]}); + assert!(crate_graph_violations(&metadata).is_empty()); +} + +#[test] +fn checker_rejects_a_dev_dependency_between_stage_crates() { + let metadata = serde_json::json!({"packages": [ + package("asap-types", &[], &[]), + package("asap-stage0-memo", &["asap-types"], &[]), + // Forbidden: Pass 1's tests call Stage 0. package( - "asap-plan-selection", - &[("asap-types", false)], - &["asap-logical-asap-optimization"], + "asap-stage1-pass1-per-computation-candidates", + &["asap-types"], + &["asap-stage0-memo"], ), ]}); - assert!(crate_graph_violations(&metadata).is_empty()); + assert_eq!( + crate_graph_violations(&metadata), + vec![ + "forbidden [dev-dependencies] edge asap-stage1-pass1-per-computation-candidates -> \ + asap-stage0-memo: a stage crate's tests never call another stage crate, \ + directly or through the facade (#1054)" + .to_string() + ] + ); } #[test] -fn optional_only_exception_rejects_the_edge_made_non_optional() { - let metadata = |optional| { - serde_json::json!({"packages": [ - package("asap-types", &[], &[]), - package("asap-frontend-promql", &[("asap-types", false)], &[]), - package( - "asap-logical-asap-optimization", - &[("asap-types", false), ("asap-frontend-promql", optional)], - &[], - ), - ]}) - }; - assert!(crate_graph_violations(&metadata(true)).is_empty()); +fn checker_rejects_a_frontend_dev_dependency_on_the_facade() { + let metadata = serde_json::json!({"packages": [ + package("asap-types", &[], &[]), + package("asap-planner", &["asap-types"], &[]), + // Forbidden: the PromQL frontend's tests plan through the facade. + package("asap-frontend-promql", &["asap-types"], &["asap-planner"]), + ]}); assert_eq!( - crate_graph_violations(&metadata(false)), + crate_graph_violations(&metadata), vec![ - "forbidden [dependencies] edge asap-logical-asap-optimization -> \ - asap-frontend-promql: stage crates never depend on each other (#1054)" + "forbidden [dev-dependencies] edge asap-frontend-promql -> asap-planner: \ + a stage crate's tests never call another stage crate, directly or through \ + the facade (#1054)" .to_string() ] ); @@ -267,14 +284,14 @@ fn optional_only_exception_rejects_the_edge_made_non_optional() { fn checker_rejects_an_unclassified_crate_and_shared_model_edges() { let metadata = serde_json::json!({"packages": [ package("asap-types", &[], &[]), - package("asap-logical-asap-optimization", &[("asap-types", false)], &[]), - package("asap-accuracy", &[("asap-logical-asap-optimization", false)], &[]), + package("asap-stage1-pass1-per-computation-candidates", &["asap-types"], &[]), + package("asap-accuracy", &["asap-stage1-pass1-per-computation-candidates"], &[]), package("asap-new-crate", &[], &[]), ]}); assert_eq!( crate_graph_violations(&metadata), vec![ - "forbidden [dependencies] edge asap-accuracy -> asap-logical-asap-optimization: \ + "forbidden [dependencies] edge asap-accuracy -> asap-stage1-pass1-per-computation-candidates: \ asap-accuracy and asap-cost depend only on asap-types (#1054)" .to_string(), "workspace crate `asap-new-crate` has no role: add it to `role_of` in \ diff --git a/crates/integration-tests/tests/per_computation_candidates_sql.rs b/crates/integration-tests/tests/per_computation_candidates_sql.rs index b62e18c8e..abaf44691 100644 --- a/crates/integration-tests/tests/per_computation_candidates_sql.rs +++ b/crates/integration-tests/tests/per_computation_candidates_sql.rs @@ -3,7 +3,7 @@ //! ranks. use asap_frontend_sql::{lower_sql, SqlCatalog}; -use asap_logical_asap_optimization::test_support::generate_per_computation_candidates; +use asap_stage1_pass1_per_computation_candidates::test_support::generate_per_computation_candidates; use asap_types::accuracy::AccuracyTarget; use asap_types::ir::schema::{DataType, Field, Schema}; use asap_types::ir::QueryRoot; @@ -21,7 +21,7 @@ async fn targets(sql: &str) -> Vec { .await .unwrap_or_else(|e| panic!("lower failed for {sql:?}: {e}")); generate_per_computation_candidates( - &asap_logical_asap_optimization::memo_of_queries( + &asap_stage0_memo::memo_of_queries( &[QueryRoot::Operator(root)], &[None], &Default::default(), diff --git a/crates/logical-asap-optimization/Cargo.toml b/crates/logical-asap-optimization/Cargo.toml deleted file mode 100644 index 3154d7233..000000000 --- a/crates/logical-asap-optimization/Cargo.toml +++ /dev/null @@ -1,29 +0,0 @@ -[package] -name = "asap-logical-asap-optimization" -version = "0.1.0" -edition = "2021" - -# #509 Stage 1, logical ASAP-aware optimization: Pass 1 per-computation -# candidates and Pass 2 ASAP-aware CSE over asap-types' operator DAG, with -# the shared analytical accuracy model (`asap-accuracy`). Depends on no -# later stage, and on no query-language frontend except through the -# `test-support` feature. -[dependencies] -asap_sketchlib = { workspace = true } -asap-types = { path = "../types" } -asap-accuracy = { path = "../accuracy" } -thiserror = "2" -serde = { version = "1", features = ["derive"] } -serde_json = "1" -rmp-serde = "1" -# Only for `test-support`: lowering PromQL test queries. -asap-frontend-promql = { path = "../frontend-promql", optional = true } - -[features] -# The test helpers (`test_support`) the later stage crates' tests share. -test-support = ["dep:asap-frontend-promql", "asap-types/test-support"] - -[dev-dependencies] -asap-types = { path = "../types", features = ["test-support"] } -asap-accuracy = { path = "../accuracy", features = ["test-support"] } -asap-frontend-promql = { path = "../frontend-promql" } diff --git a/crates/logical-asap-optimization/src/lib.rs b/crates/logical-asap-optimization/src/lib.rs deleted file mode 100644 index 49b0a8791..000000000 --- a/crates/logical-asap-optimization/src/lib.rs +++ /dev/null @@ -1,82 +0,0 @@ -//! `asap-logical-asap-optimization` — #509 Stage 0 hash-consing and -//! Stage 1, logical ASAP-aware optimization: from the query-language -//! frontends' logical DAGs to the memo of logical candidates -//! (`asap_types::stages::LogicalASAPMemoCandidates`) that Stage 2 implements. -//! -//! Identical-sub-DAG sharing over the logical DAG (Stage 0, the `stage0` -//! module, behind [`memo_of_queries`]) runs before the -//! stages; Stage 1 adds the ASAP-aware sharing that is invisible at the -//! logical level (Pass 2, the `asap_aware_cse` module), e.g. -//! `Quantile(x, 0.99)` and `Quantile(x, 0.95)` reading one built sketch. -//! -//! It depends only on `asap-types` and the shared accuracy model -//! (`asap-accuracy`). It depends on no other stage crate, and no other -//! stage crate depends on it except in their tests (CI checks the crate -//! graph): the stage-boundary types (its input -//! `Memo`, Pass 1's `Memo` and Pass 2's `LogicalASAPMemoCandidates`) are in `asap_types::stages`, and -//! the planner facade calls each stage in turn. It depends on no -//! query-language frontend either, except with the `test-support` feature, -//! whose test helpers (`test_support`) lower PromQL test queries through -//! `asap-frontend-promql`; other crates enable that feature only for their -//! tests. -//! -//! Post-lowering **canonicalization** is *not* here: it lives in -//! `asap_frontend_common::canonicalize`, run inside that crate's shared -//! `resolve_root` so every front end normalizes before the IR leaves resolution -//! (issue #34, closed). -//! -//! ## Components -//! -//! The modules are crate-private; the crate root re-exports the items other -//! crates use, one path each, and `test_support` (feature `test-support`) -//! re-exports the internals other crates' tests call. -//! -//! - `stage0` — Stage 0: hash-consing the workload's logical DAG into memo -//! groups through `Memo::find_or_add_group`, behind [`memo_of_queries`]. -//! - `pass1::computation_targets` — Pass 1: per-computation candidate -//! generation and composition, behind -//! [`pass1_memo`]. -//! - `pass2::memo` — Pass 2: the rules over groups, behind -//! [`generate_logical_asap_memo_candidates`]. -//! - `pass1::realization` — the summary families that can serve an aggregate -//! intent, the intent's accuracy target and `(ε, δ)` budget, and default -//! sketch sizing, shared by Pass 1 and Pass 2. -//! -//! Accuracy guarantees come from the built-in analytical accuracy rules in -//! `asap-accuracy` (per-family estimators, composition and budget -//! allocation). They derive a machine-readable -//! [`AccuracyGuarantee`](asap_types::accuracy::AccuracyGuarantee) -//! for every finalized value and propagate it through -//! approximate-over-approximate compositions under conservative rules (no -//! independence assumptions, unknown statistics stay unknown). A -//! composition with no rule leaves the guarantee `None` and keeps the -//! candidate. Pass 1 prunes nothing for accuracy; Pass 2 gives each readout -//! its required accuracy and eliminates the candidates no query can use, -//! with the deployment's measured accuracy (`AccuracyEvidence`) read before -//! each summary's theoretical guarantee. - -mod pass1; -mod pass2; -/// Stage 0: the memo groups of the workload's query roots. -mod stage0; -/// Test helpers shared by the stage crates' tests, and the Stage 1 -/// internals those tests call (feature `test-support`). -#[cfg(any(test, feature = "test-support"))] -pub mod test_support; - -// Stage 1's public API: one path per item, for the planner facade and the -// developer tools. Every other item is crate-private; the ones other crates' -// tests call are re-exported by `test_support`. - -// Stage 0: the memo groups of the workload's query roots, without -// candidates (`asap_types::stages::Memo`). -pub use stage0::memo_of_queries; -// Pass 1: its entry and its errors. Its output and the types the output -// holds are in `asap_types::stages`. -pub use pass1::{pass1_memo, Pass1Error, PerComputationCandidateError}; -// Pass 2: its entry and its error. -pub use pass2::memo::rules::Pass2RuleError; -pub use pass2::{ - generate_logical_asap_memo_candidates, pass2_after_local_window_composition, - pass2_local_window_composition, -}; diff --git a/crates/logical-asap-optimization/src/pass1.rs b/crates/logical-asap-optimization/src/pass1.rs deleted file mode 100644 index 8bbd209c1..000000000 --- a/crates/logical-asap-optimization/src/pass1.rs +++ /dev/null @@ -1,49 +0,0 @@ -//! Stage 1, Pass 1: per-computation candidate generation and the summary -//! realizations it offers. Its one entry is -//! [`pass1_memo`], which fills each group with its initial candidates (exact, -//! exact accumulator, one summary build per listed parameter configuration, -//! fused builds), with every intermediate result its own group (a [`Memo`]), -//! which Pass 2 extends. - -/// Stage 1, Pass 1's computation targets. No execution timing is assigned: that is a Stage 2 -/// materialization decision. Its target list -/// (`PerComputationCandidates`) is Pass 1's working form, public only to -/// tests (`crate::test_support`, feature `test-support`). -pub(crate) mod computation_targets; -/// Frontend-to-Pass-1 acceptance tests over Pass 1's working form. -#[cfg(test)] -mod computation_targets_tests; -pub(crate) mod realization; - -use asap_types::deployment_capabilities::SupportedSummary; -use asap_types::stages::Memo; -use computation_targets::generate_per_computation_candidates; -pub use computation_targets::PerComputationCandidateError; - -/// Why [`pass1_memo`] failed. -#[derive(Debug, thiserror::Error)] -pub enum Pass1Error { - /// A query's DAG cannot be planned: it already holds ASAP or physical - /// annotations, or a measure's accuracy target is invalid. - #[error(transparent)] - PerComputation(#[from] PerComputationCandidateError), -} - -/// Stage 1, Pass 1: the initial candidates of the memo groups of `memo` -/// (Stage 0's, without candidates). It finds one computation target per -/// measure of each aggregate group with a realization besides exact -/// execution, drops the summaries the deployment does not support -/// (`supported_summaries`, the deployment's -/// `DeploymentCapabilities::supported_summaries`; `None` supports every -/// one), and adds each way to compute a group as candidates, through -/// `Memo::find_or_add_group` and `Memo::add_candidate`. Accuracy prunes -/// nothing here: Pass 2's dead-candidate elimination does. -pub fn pass1_memo( - memo: Memo, - supported_summaries: Option<&[SupportedSummary]>, -) -> Result { - let per_computation = generate_per_computation_candidates(&memo)? - .without_unsupported_summaries(supported_summaries); - let _ = (memo, per_computation); - todo!("#1207 PR 3: add each way to compute as candidates, one per listed θ") -} diff --git a/crates/logical-asap-optimization/src/pass1/computation_targets_tests.rs b/crates/logical-asap-optimization/src/pass1/computation_targets_tests.rs deleted file mode 100644 index f5ef38117..000000000 --- a/crates/logical-asap-optimization/src/pass1/computation_targets_tests.rs +++ /dev/null @@ -1,748 +0,0 @@ -//! Frontend-to-Pass-1 acceptance: candidate discovery precedes empirical selection. -use crate::pass1::computation_targets::{ - computation_candidates_for_intent, generate_per_computation_candidates, - PerComputationCandidateError, -}; -use crate::stage0::memo_of_queries; -use asap_types::accuracy::AccuracyTarget; -use asap_types::ir::operator::arguments::{Reduction, Source}; -use asap_types::ir::operator::AggIntent; -use asap_types::ir::scalar::{ColumnRef, CompareOpKind, ScalarValue}; -use asap_types::ir::schema::{DataType, Field, FieldDataType, Schema}; -use asap_types::ir::{ - ASAPOp, ExprSemantics, NonASAPOp, Operator, OperatorNode, Predicate, QueryRoot, ScalarExpr, -}; -use asap_types::summary_type::{ExactKind, SketchAlgorithm, SummaryUpdate}; - -use asap_types::stages::{HavingEntry, HavingPlacement, HowToComputeAggregateMeasure}; -use std::rc::Rc; - -fn candidates_for(intent: AggIntent) -> Vec { - computation_candidates_for_intent(&intent).candidates -} -fn algorithms(choices: &[HowToComputeAggregateMeasure]) -> Vec { - choices - .iter() - .filter_map(|choice| match choice { - HowToComputeAggregateMeasure::Summary(algorithm) => Some(*algorithm), - _ => None, - }) - .collect() -} -fn scan(nullable_value: bool) -> Rc { - OperatorNode::new_shared(Operator::NonASAP(NonASAPOp::Scan { - source: Source::Table { - table_ref: "flows".into(), - }, - predicates: vec![], - schema: Schema::lifted( - vec![ - Field::plain("src_ip", DataType::Utf8, false), - Field::plain("value", DataType::Float64, nullable_value), - ], - None, - ), - })) - .unwrap() -} -fn aggregate_over( - child: Rc, - measures: Vec, - filters: Vec>, - having: Option, -) -> Rc { - OperatorNode::new_shared(Operator::NonASAP(NonASAPOp::Aggregate { - child, - reduction: Reduction::by(vec![]), - measures, - output_names: vec![], - filters, - having, - })) - .unwrap() -} -fn aggregate(intent: AggIntent) -> Rc { - aggregate_over(scan(false), vec![intent], vec![], None) -} -fn always() -> Predicate { - Predicate(ScalarExpr::Literal(ScalarValue::Boolean(true))) -} - -/// Example 2 preserves specialized distinct summaries and the universal alternative. -#[test] -fn cardinality_keeps_exact_specialized_and_universal_candidates() { - let choices = candidates_for(AggIntent::Cardinality { cols: vec![0] }); - assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); - assert_eq!( - algorithms(&choices), - vec![ - SketchAlgorithm::Hll, - SketchAlgorithm::Kmv, - SketchAlgorithm::UnivMon - ] - ); - let tuple = candidates_for(AggIntent::Cardinality { cols: vec![0, 1] }); - assert!(!algorithms(&tuple).contains(&SketchAlgorithm::UnivMon)); -} - -/// Frequency moments retain exact execution and a universal sketch without certification. -#[test] -fn frequency_statistics_keep_universal_choices() { - for intent in [ - AggIntent::FrequencyL2 { col: Some(0) }, - AggIntent::FrequencyEntropy { col: Some(0) }, - ] { - let choices = candidates_for(intent); - assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); - assert_eq!(algorithms(&choices), vec![SketchAlgorithm::UnivMon]); - } -} - -/// Scalar roots expose their producer targets; repeated references retain one target identity. -#[test] -fn scalar_root_producers_are_discovered_once() { - let producer = aggregate(AggIntent::Cardinality { cols: vec![0] }); - let roots = vec![ - QueryRoot::Scalar(ScalarExpr::ScalarSubquery(producer.clone())), - QueryRoot::Operator(producer.clone()), - ]; - let candidates = generate_per_computation_candidates( - &memo_of_queries(&roots, &vec![None; roots.len()], &Default::default()).unwrap(), - ) - .unwrap(); - assert_eq!(candidates.roots.len(), 2); - for root in &candidates.roots { - root.validate_structure().unwrap(); - } - assert_eq!(candidates.targets.len(), 1); - assert_eq!(**candidates.aggregate(&candidates.targets[0]), *producer); - - assert!(producer.guarantee.is_none()); - producer.validate_structure().unwrap(); -} - -/// #509 Example 1 Q1 is exact: each target's one exact option is its exact -/// accumulator state (grouped sum, rate); no plain exact form and no summary. -/// One PromQL query with the default exact target, lowered through the -/// workload frontend. -fn exact_promql(query: &str) -> Vec { - use asap_types::workload::{ - BatchEntry, PlanningWorkload, Query, QueryLanguage, QueryRequirements, QueryWorkload, - }; - let workload = PlanningWorkload { - query_workload: QueryWorkload { - language: QueryLanguage::PromQL, - query_batch: Some(vec![BatchEntry { - query: Query(query.into()), - requirements: QueryRequirements { - accuracy: AccuracyTarget::exact(), - ..Default::default() - }, - predictability: Default::default(), - invocations: 1, - execute_at: None, - range_evaluation: None, - }]), - repeating_queries: None, - }, - data_workload: Some(asap_types::workload::DataWorkload::sampled_every( - asap_frontend_promql::promql_metric_names(query).unwrap_or_default(), - asap_types::workload::DurationMs(1000), - )), - }; - asap_frontend_promql::lower_promql_query_workload(&workload).unwrap() -} - -#[test] -fn example_1_exact_q1_keeps_exact_accumulators_only() { - let roots = exact_promql("sum by (job) (rate(http_requests_total[1m]))"); - let candidates = generate_per_computation_candidates( - &memo_of_queries(&roots, &vec![None; roots.len()], &Default::default()).unwrap(), - ) - .unwrap(); - let found: Vec<_> = candidates - .targets - .iter() - .map(|target| target.ways_to_compute.clone()) - .collect(); - assert_eq!( - found, - vec![ - vec![HowToComputeAggregateMeasure::ExactAccumulator(vec![ - ExactKind::Sum - ])], - vec![HowToComputeAggregateMeasure::ExactAccumulator(vec![ - ExactKind::Rate - ])], - ] - ); -} - -/// ASAP operators fail at the stage -/// boundary. -#[test] -fn asap_input_is_rejected() { - let summary = OperatorNode::new_shared(Operator::ASAP(ASAPOp::SummaryAgg { - child: scan(false), - summary_type: FieldDataType::Sketch(SketchAlgorithm::Kll), - input: SummaryUpdate::column(ColumnRef::SampleValue), - reduction: Reduction::by(vec![]), - filter: None, - })) - .unwrap(); - assert!(matches!( - generate_per_computation_candidates( - &memo_of_queries( - &[QueryRoot::Operator(summary)], - &[None], - &Default::default() - ) - .unwrap() - ), - Err(PerComputationCandidateError::ContainsAsap) - )); -} - -/// TopK keeps both declared heap substrates without choosing an implementation. -#[test] -fn topk_keeps_both_specialized_heap_choices() { - let choices = candidates_for(AggIntent::TopK { k: 10 }); - assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); - assert_eq!( - algorithms(&choices), - vec![ - SketchAlgorithm::CmsWithHeap, - SketchAlgorithm::CountSketchWithHeap - ] - ); -} - -/// Summary candidates are unsized, so they do not depend on the requested error. -#[test] -fn summary_candidates_are_unsized() { - let loose = candidates_for(AggIntent::Count); - let tight = candidates_for(AggIntent::Count); - assert_eq!(loose, tight); -} - -/// Each measure of a multi-measure aggregate is its own target; a measure whose -/// only realization is its exact accumulator is still a target. -#[test] -fn multi_measure_aggregate_has_one_target_per_measure() { - let node = aggregate_over( - scan(false), - vec![AggIntent::Sum { col: Some(1) }, AggIntent::Count], - vec![], - None, - ); - let inventory = generate_per_computation_candidates( - &memo_of_queries(&[QueryRoot::Operator(node)], &[None], &Default::default()).unwrap(), - ) - .unwrap(); - let candidates = &inventory.targets; - assert_eq!( - candidates - .iter() - .map(|target| target.measure_index) - .collect::>(), - vec![0, 1] - ); - assert_eq!( - candidates[0].ways_to_compute, - vec![HowToComputeAggregateMeasure::ExactAccumulator(vec![ - ExactKind::Sum - ])] - ); - assert_sql_count_choices(&choices_of(&inventory, 1)); -} - -/// An aggregate with no realization besides exact execution is not a target. -#[test] -fn aggregate_without_realization_is_not_a_target() { - let node = aggregate(AggIntent::StdDev { - col: Some(1), - population: true, - }); - assert!(generate_per_computation_candidates( - &memo_of_queries(&[QueryRoot::Operator(node)], &[None], &Default::default()).unwrap() - ) - .unwrap() - .targets - .is_empty()); -} - -/// A filtered SQL count keeps its executable accumulator and records its -/// filter, which composition applies to the state. -#[test] -fn filtered_measure_keeps_candidates_and_records_its_filter() { - let count = || AggIntent::Count; - let filtered = aggregate_over( - scan(false), - vec![count(), count()], - vec![Some(always()), None], - None, - ); - let inventory = generate_per_computation_candidates( - &memo_of_queries( - &[QueryRoot::Operator(filtered)], - &[None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap(); - let targets = &inventory.targets; - assert_eq!(targets.len(), 2); - for (index, target) in targets.iter().enumerate() { - assert_sql_count_choices(&choices_of(&inventory, index)); - assert!(target.having_filters.is_empty()); - } - assert_eq!(targets[0].measure_filter, Some(always())); - assert_eq!(targets[1].measure_filter, None); -} - -/// Target `target`'s own ways to compute. -fn choices_of( - inventory: &crate::pass1::computation_targets::PerComputationCandidates, - target: usize, -) -> Vec { - inventory.targets[target].ways_to_compute.clone() -} - -fn assert_sql_count_choices(choices: &[HowToComputeAggregateMeasure]) { - assert_eq!( - choices, - vec![HowToComputeAggregateMeasure::ExactAccumulator(vec![ - ExactKind::Count - ])] - ); -} - -/// `count(*) by (src_ip)`, the form the SQL frontend gives `GROUP BY src_ip`. -fn grouped_count(having: Option) -> Rc { - OperatorNode::new_shared(Operator::NonASAP(NonASAPOp::Aggregate { - child: scan(false), - reduction: Reduction::by(vec![0]), - measures: vec![AggIntent::Count], - output_names: vec![], - filters: vec![], - having, - })) - .unwrap() -} -/// `HAVING` as the SQL frontend lowers it: a `Filter` above the aggregate. -fn having_filter(child: Rc, pred: Predicate) -> Rc { - OperatorNode::new_shared(Operator::NonASAP(NonASAPOp::Filter { pred, child })).unwrap() -} -/// `column = 'a'` over the aggregate output (0: `src_ip`, 1: the count). -fn equals(column: usize, value: ScalarValue) -> Predicate { - Predicate(ScalarExpr::Compare { - left: Box::new(ScalarExpr::Column(column)), - op: CompareOpKind::Eq, - right: Box::new(ScalarExpr::Literal(value)), - semantics: ExprSemantics::Sql, - }) -} - -/// A `HAVING` over group keys only is pushed below the aggregate and keeps -/// every executable candidate. -#[test] -fn key_only_having_is_pushed_below_and_keeps_candidates() { - let node = grouped_count(None); - let root = having_filter(node.clone(), equals(0, ScalarValue::Utf8("a".into()))); - let inventory = generate_per_computation_candidates( - &memo_of_queries( - &[QueryRoot::Operator(root.clone())], - &[None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap(); - let targets = &inventory.targets; - assert_eq!(targets.len(), 1); - assert_eq!(**inventory.aggregate(&targets[0]), *node); - assert_eq!( - targets[0].having_filters, - vec![HavingEntry { - filter: Some(root.clone()), - predicate: equals(0, ScalarValue::Utf8("a".into())), - placement: HavingPlacement::BelowAggregate, - }] - ); - assert_sql_count_choices(&choices_of(&inventory, 0)); -} - -/// A `HAVING` over an aggregate value, as a `Filter` above or as the -/// aggregate's own `having`, stays above the output and keeps executable candidates. -#[test] -fn value_having_stays_above_output_and_keeps_candidates() { - let value = || equals(1, ScalarValue::Int64(10)); - let inventory = generate_per_computation_candidates( - &memo_of_queries( - &[ - QueryRoot::Operator(having_filter(grouped_count(None), value())), - QueryRoot::Operator(grouped_count(Some(value()))), - ], - &vec![None; 2], - &Default::default(), - ) - .unwrap(), - ) - .unwrap(); - let targets = &inventory.targets; - assert_eq!(targets.len(), 2); - for (index, target) in targets.iter().enumerate() { - let placements: Vec<_> = target - .having_filters - .iter() - .map(|entry| entry.placement) - .collect(); - assert_eq!(placements, vec![HavingPlacement::AboveOutput]); - assert_sql_count_choices(&choices_of(&inventory, index)); - } -} - -/// A key-only `HAVING` above a shared aggregate stays above the output when -/// another consumer reads the aggregate without it. -#[test] -fn having_on_one_consumer_of_a_shared_aggregate_stays_above() { - let node = grouped_count(None); - let key = equals(0, ScalarValue::Utf8("a".into())); - let filtered = having_filter(node.clone(), key.clone()); - let targets = generate_per_computation_candidates( - &memo_of_queries( - &[ - QueryRoot::Operator(filtered.clone()), - QueryRoot::Operator(node.clone()), - ], - &vec![None; 2], - &Default::default(), - ) - .unwrap(), - ) - .unwrap() - .targets; - assert_eq!(targets.len(), 1); - assert_eq!( - targets[0].having_filters, - vec![HavingEntry { - filter: Some(filtered), - predicate: key.clone(), - placement: HavingPlacement::AboveOutput, - }] - ); - - // Two consumers applying the same key-only predicate push it below. - let first = having_filter(node.clone(), key.clone()); - let second = having_filter(node, key); - let targets = generate_per_computation_candidates( - &memo_of_queries( - &[QueryRoot::Operator(first), QueryRoot::Operator(second)], - &[None, None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap() - .targets; - assert!(targets[0] - .having_filters - .iter() - .all(|entry| entry.placement == HavingPlacement::BelowAggregate)); - // The two equal `Filter`s are one memo group, so one HAVING entry. - assert_eq!(targets[0].having_filters.len(), 1); -} - -/// A scalar reference to a grouped aggregate (`Filter(scan, EXISTS G)` as a -/// second root) is a consumer that reads it without the `HAVING`, so the -/// first root's key-only `HAVING` stays above the output. -#[test] -fn a_scalar_reference_consumer_keeps_a_key_only_having_above() { - let node = grouped_count(None); - let key = equals(0, ScalarValue::Utf8("a".into())); - let filtered = having_filter(node.clone(), key.clone()); - let exists = having_filter( - scan(false), - Predicate(ScalarExpr::Exists { - subquery: node.clone(), - negated: false, - }), - ); - let inventory = generate_per_computation_candidates( - &memo_of_queries( - &[ - QueryRoot::Operator(filtered.clone()), - QueryRoot::Operator(exists), - ], - &vec![None; 2], - &Default::default(), - ) - .unwrap(), - ) - .unwrap(); - let targets = &inventory.targets; - let target = targets - .iter() - .find(|target| **inventory.aggregate(target) == *node) - .expect("the grouped count's target"); - assert_eq!( - target.having_filters, - vec![HavingEntry { - filter: Some(filtered), - predicate: key, - placement: HavingPlacement::AboveOutput, - }] - ); -} - -/// Of two stacked `Filter`s above an aggregate, only the adjacent one is -/// its `HAVING`; the outer one filters the inner `Filter`'s output. -#[test] -fn only_the_adjacent_of_stacked_filters_is_having() { - let node = grouped_count(None); - let inner_key = equals(0, ScalarValue::Utf8("a".into())); - let inner = having_filter(node.clone(), inner_key.clone()); - let outer = having_filter(inner.clone(), equals(0, ScalarValue::Utf8("b".into()))); - let targets = generate_per_computation_candidates( - &memo_of_queries(&[QueryRoot::Operator(outer)], &[None], &Default::default()).unwrap(), - ) - .unwrap() - .targets; - assert_eq!(targets.len(), 1); - assert_eq!( - targets[0].having_filters, - vec![HavingEntry { - filter: Some(inner), - predicate: inner_key, - placement: HavingPlacement::BelowAggregate, - }] - ); -} - -/// A global aggregate's `HAVING` always stays above the output, even a -/// constant one: the one output row exists with no input rows. -#[test] -fn global_aggregate_having_stays_above() { - let count = || vec![AggIntent::Count]; - let never = Predicate(ScalarExpr::Literal(ScalarValue::Boolean(false))); - let targets = generate_per_computation_candidates( - &memo_of_queries( - &[ - QueryRoot::Operator(having_filter( - aggregate_over(scan(false), count(), vec![], None), - never.clone(), - )), - QueryRoot::Operator(aggregate_over(scan(false), count(), vec![], Some(never))), - ], - &vec![None; 2], - &Default::default(), - ) - .unwrap(), - ) - .unwrap() - .targets; - assert_eq!(targets.len(), 2); - for target in &targets { - let placements: Vec<_> = target - .having_filters - .iter() - .map(|entry| entry.placement) - .collect(); - assert_eq!(placements, vec![HavingPlacement::AboveOutput]); - } -} - -/// The `HAVING` entries of the target whose measure satisfies `is`. -fn having_of( - inventory: &crate::pass1::computation_targets::PerComputationCandidates, - is: impl Fn(&AggIntent) -> bool, -) -> Vec { - let target = inventory - .targets - .iter() - .find(|target| match inventory.aggregate(target).non_asap() { - Some(NonASAPOp::Aggregate { measures, .. }) => is(&measures[target.measure_index]), - _ => false, - }) - .expect("target"); - target.having_filters.clone() -} - -/// `Column(column) > ScalarSubquery(subquery)`. -fn above_scalar(column: usize, subquery: Rc) -> Predicate { - Predicate(ScalarExpr::Compare { - left: Box::new(ScalarExpr::Column(column)), - op: CompareOpKind::Gt, - right: Box::new(ScalarExpr::ScalarSubquery(subquery)), - semantics: ExprSemantics::Sql, - }) -} - -/// A `Filter` that reads an aggregate only from its predicate is not that -/// aggregate's `HAVING`; one that also filters the aggregate gives one entry. -#[test] -fn scalar_reference_filter_is_not_having() { - let count = || vec![AggIntent::Count]; - let agg = aggregate_over(scan(false), count(), vec![], None); - let root = having_filter(scan(false), above_scalar(1, agg.clone())); - let inventory = generate_per_computation_candidates( - &memo_of_queries(&[QueryRoot::Operator(root)], &[None], &Default::default()).unwrap(), - ) - .unwrap(); - let targets = &inventory.targets; - assert_eq!(targets.len(), 1); - assert_eq!(**inventory.aggregate(&targets[0]), *agg); - assert!( - targets[0].having_filters.is_empty(), - "{:?}", - targets[0].having_filters - ); - - let agg = aggregate_over(scan(false), count(), vec![], None); - let root = having_filter(agg.clone(), above_scalar(0, agg.clone())); - let targets = generate_per_computation_candidates( - &memo_of_queries( - &[QueryRoot::Operator(root.clone())], - &[None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap() - .targets; - assert_eq!(targets.len(), 1); - assert_eq!( - targets[0].having_filters, - vec![HavingEntry { - filter: Some(root), - predicate: above_scalar(0, agg), - placement: HavingPlacement::AboveOutput, - }] - ); -} - -/// PromQL `scalar(...)` operands are scalar references, not `HAVING`. -#[test] -fn promql_scalar_operand_is_not_having() { - let roots = exact_promql("http_requests_total > scalar(sum(http_requests_total))"); - let targets = generate_per_computation_candidates( - &memo_of_queries(&roots, &vec![None; roots.len()], &Default::default()).unwrap(), - ) - .unwrap() - .targets; - assert!(!targets.is_empty()); - for target in &targets { - assert!( - target.having_filters.is_empty(), - "{:?}", - target.having_filters - ); - } - - let roots = exact_promql("sum by (job) (x) > scalar(count(x))"); - let inventory = generate_per_computation_candidates( - &memo_of_queries(&roots, &vec![None; roots.len()], &Default::default()).unwrap(), - ) - .unwrap(); - assert!(having_of(&inventory, |intent| matches!(intent, AggIntent::Count)).is_empty()); - let sum = having_of(&inventory, |intent| matches!(intent, AggIntent::Sum { .. })); - assert_eq!(sum.len(), 1, "{sum:?}"); - assert_eq!(sum[0].placement, HavingPlacement::AboveOutput); -} - -/// A non-root, non-`Filter` consumer keeps a key-only `HAVING` above. -#[test] -fn having_shared_with_a_project_consumer_stays_above() { - let node = grouped_count(None); - let key = equals(0, ScalarValue::Utf8("a".into())); - let filtered = having_filter(node.clone(), key); - let project = OperatorNode::new_shared(Operator::NonASAP(NonASAPOp::Project { - cols: vec![asap_types::ir::ProjectItem { - alias: None, - expr: ScalarExpr::Column(0), - }], - qualifier: None, - child: node, - })) - .unwrap(); - let targets = generate_per_computation_candidates( - &memo_of_queries( - &[QueryRoot::Operator(filtered), QueryRoot::Operator(project)], - &[None, None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap() - .targets; - assert_eq!(targets.len(), 1); - let placements: Vec<_> = targets[0] - .having_filters - .iter() - .map(|entry| entry.placement) - .collect(); - assert_eq!(placements, vec![HavingPlacement::AboveOutput]); -} - -/// `without(...)` and per-entity aggregates have no fixed key prefix, so a -/// `HAVING` over column 0 stays above. -#[test] -fn without_and_per_entity_having_stays_above() { - for reduction in [ - Reduction::Reduce(asap_types::ir::operator::arguments::GroupKeys::without( - vec![1], - )), - Reduction::PerEntity, - ] { - let node = OperatorNode::new_shared(Operator::NonASAP(NonASAPOp::Aggregate { - child: scan(false), - reduction: reduction.clone(), - measures: vec![AggIntent::Count], - output_names: vec![], - filters: vec![], - having: None, - })) - .unwrap(); - let root = having_filter(node, equals(0, ScalarValue::Utf8("a".into()))); - let targets = generate_per_computation_candidates( - &memo_of_queries(&[QueryRoot::Operator(root)], &[None], &Default::default()).unwrap(), - ) - .unwrap() - .targets; - assert_eq!(targets.len(), 1, "{reduction:?}"); - let placements: Vec<_> = targets[0] - .having_filters - .iter() - .map(|entry| entry.placement) - .collect(); - assert_eq!( - placements, - vec![HavingPlacement::AboveOutput], - "{reduction:?}" - ); - } -} - -// Structurally equal aggregates are one memo group with one target, and its -// HAVING placement is decided over every consumer of the group: an unfiltered -// consumer keeps the key-only HAVING above the output for the filtered ones. -#[test] -fn memo_cached_rules_preserve_occurrence_specific_having() { - let shared = grouped_count(None); - let other = grouped_count(None); - let key = equals(0, ScalarValue::Utf8("a".into())); - let roots = vec![ - QueryRoot::Operator(having_filter(shared.clone(), key.clone())), - QueryRoot::Operator(shared), - QueryRoot::Operator(having_filter(other, key)), - ]; - let memo = memo_of_queries(&roots, &vec![None; roots.len()], &Default::default()).unwrap(); - let cached = generate_per_computation_candidates(&memo).unwrap(); - assert_eq!(cached.targets.len(), 1); - // Roots 0 and 2 apply the same `Filter`, one memo group: one entry. - let [entry] = &cached.targets[0].having_filters[..] else { - panic!("one HAVING entry: {:?}", cached.targets[0].having_filters); - }; - assert_eq!(entry.placement, HavingPlacement::AboveOutput); -} diff --git a/crates/logical-asap-optimization/src/pass2.rs b/crates/logical-asap-optimization/src/pass2.rs deleted file mode 100644 index a51c6e902..000000000 --- a/crates/logical-asap-optimization/src/pass2.rs +++ /dev/null @@ -1,62 +0,0 @@ -//! Stage 1, Pass 2: the rules over groups and the logical edges. Its entry, -//! [`generate_logical_asap_memo_candidates`], extends the Pass 1 memo by the -//! rules over groups and adds the logical edges -//! ([`asap_types::stages::LogicalASAPMemoCandidates`]), which Stage 2 expands. - -/// The rules over groups. -pub(crate) mod memo; - -use asap_accuracy::AccuracyEvidence; -use asap_types::stages::{LogicalASAPMemoCandidates, Memo}; -use asap_types::workload::QueryWorkloadEntry; -use memo::rules::{finer_aggregate, rollup, scan_labels, summary_inputs, topk, Pass2RuleError}; -use memo::window_candidates::add_local_window_composition; - -/// Stage 1, Pass 2: rule 1 ([`pass2_local_window_composition`]), then rules -/// 2–7 and the logical edges ([`pass2_after_local_window_composition`]). -/// `entries[i]` is query `i`'s workload entry; `evidence` is the -/// deployment's measured accuracy, which each edge's $\alpha^{\log}$ reads -/// before the theoretical guarantee. -pub fn generate_logical_asap_memo_candidates( - pass1: Memo, - entries: &[QueryWorkloadEntry], - evidence: &dyn AccuracyEvidence, -) -> Result { - pass2_after_local_window_composition(pass2_local_window_composition(pass1, entries)?, evidence) -} - -/// Pass 2's rule 1 alone: Pass 1's memo with the tumbling-window layouts -/// of each summary state group (`asap_planner` prints this step). -pub fn pass2_local_window_composition( - pass1: Memo, - entries: &[QueryWorkloadEntry], -) -> Result { - let mut memo = pass1; - // 1. Local window composition. - add_local_window_composition(&mut memo, entries)?; - Ok(memo) -} - -/// The rest of Pass 2 on [`pass2_local_window_composition`]'s memo: rules -/// 2–7, then the readouts' required accuracy and the logical edges, with -/// $\alpha^{\log}$ from `evidence` or the theoretical guarantee -/// (`asap_accuracy::producer_satisfies_logical_requirements`). -pub fn pass2_after_local_window_composition( - mut memo: Memo, - evidence: &dyn AccuracyEvidence, -) -> Result { - // 2. Scan widening. - scan_labels::add_scan_label_candidates(&mut memo)?; - // 3. Summary inputs. - summary_inputs::factor_summary_inputs(&mut memo)?; - // 4. Top-k reuse. - topk::add_topk_candidates(&mut memo)?; - // 5. Finer aggregate. - finer_aggregate::add_finer_aggregate_candidates(&mut memo)?; - // 6. Rollup. - rollup::add_rollup_candidates(&mut memo)?; - // 7. Window rollup. - rollup::add_window_rollup_candidates(&mut memo)?; - let _ = (memo, evidence); - todo!("#1207 PR 4: readout requirements, dead-candidate elimination and the logical edges") -} diff --git a/crates/logical-asap-optimization/src/pass2/memo.rs b/crates/logical-asap-optimization/src/pass2/memo.rs deleted file mode 100644 index 754a06a5c..000000000 --- a/crates/logical-asap-optimization/src/pass2/memo.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! The logical memo's rules over the memo groups Stage 0 builds -//! (`crate::stage0`). - -pub(crate) mod rules; -/// Rule 1: tumbling-window layouts of a summary state group. -pub(crate) mod window_candidates; diff --git a/crates/logical-asap-optimization/src/pass2/memo/rules/finer_aggregate.rs b/crates/logical-asap-optimization/src/pass2/memo/rules/finer_aggregate.rs deleted file mode 100644 index 95c8c7c0a..000000000 --- a/crates/logical-asap-optimization/src/pass2/memo/rules/finer_aggregate.rs +++ /dev/null @@ -1,12 +0,0 @@ -//! Read a SQL aggregate from a finer aggregate's result -//! ([`match_finer`](crate::pass2::finer_aggregate::match_finer)): filter the finer -//! rows, then merge them into the query's groups with each measure's rollup. - -use crate::pass2::memo::rules::Pass2RuleError; -use asap_types::stages::Memo; - -/// Rule 5, finer aggregate: a candidate of a coarse group that filters and rolls up a finer group. -pub(crate) fn add_finer_aggregate_candidates(memo: &mut Memo) -> Result<(), Pass2RuleError> { - let _ = memo; - todo!("#1207 PR 4: rule 5 over groups") -} diff --git a/crates/logical-asap-optimization/src/pass2/memo/rules/rollup.rs b/crates/logical-asap-optimization/src/pass2/memo/rules/rollup.rs deleted file mode 100644 index de56a825b..000000000 --- a/crates/logical-asap-optimization/src/pass2/memo/rules/rollup.rs +++ /dev/null @@ -1,18 +0,0 @@ -//! Producer-level exact and sketch rollups, using the existing capability rules. - -use crate::pass2::memo::rules::Pass2RuleError; -use asap_types::stages::Memo; - -/// Rule 6, rollup: a candidate of a coarse aggregate or summary group reading -/// a finer group whose state rolls up (exact or sketch merge). -pub(crate) fn add_rollup_candidates(memo: &mut Memo) -> Result<(), Pass2RuleError> { - let _ = memo; - todo!("#1207 PR 4: rule 6 over groups") -} - -/// Rule 7, window rollup: a candidate of a longer-range group merging a -/// shorter-range group's windows. -pub(crate) fn add_window_rollup_candidates(memo: &mut Memo) -> Result<(), Pass2RuleError> { - let _ = memo; - todo!("#1207 PR 4: rule 7 over groups") -} diff --git a/crates/logical-asap-optimization/src/pass2/memo/rules/scan_labels.rs b/crates/logical-asap-optimization/src/pass2/memo/rules/scan_labels.rs deleted file mode 100644 index a808eb48f..000000000 --- a/crates/logical-asap-optimization/src/pass2/memo/rules/scan_labels.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Scan-label widening for explicit memo state sharing. Reuses the existing -//! Pass 2 widening rule; only its source-chain boundaries are interned here. - -use crate::pass2::memo::rules::Pass2RuleError; -use asap_types::stages::Memo; - -/// Rule 2, scan widening: a group for the widened scan, and in each original scan group a candidate `Project(widened)`. -pub(crate) fn add_scan_label_candidates(memo: &mut Memo) -> Result<(), Pass2RuleError> { - let _ = memo; - todo!("#1207 PR 4: rule 2 over groups") -} diff --git a/crates/logical-asap-optimization/src/pass2/memo/rules/summary_inputs.rs b/crates/logical-asap-optimization/src/pass2/memo/rules/summary_inputs.rs deleted file mode 100644 index 956141fbf..000000000 --- a/crates/logical-asap-optimization/src/pass2/memo/rules/summary_inputs.rs +++ /dev/null @@ -1,12 +0,0 @@ -//! Expose private value projections and filters below summary builds as canonical inputs. -//! This preserves their full expressions and schema, including opaque series -//! identity, rather than assuming that a projection is an identity operation. - -use crate::pass2::memo::rules::Pass2RuleError; -use asap_types::stages::Memo; - -/// Rule 3, summary inputs: a value projection or filter below a summary build as its own input group. -pub(crate) fn factor_summary_inputs(memo: &mut Memo) -> Result<(), Pass2RuleError> { - let _ = memo; - todo!("#1207 PR 4: rule 3 over groups") -} diff --git a/crates/logical-asap-optimization/src/pass2/memo/rules/topk.rs b/crates/logical-asap-optimization/src/pass2/memo/rules/topk.rs deleted file mode 100644 index e3b1b22dc..000000000 --- a/crates/logical-asap-optimization/src/pass2/memo/rules/topk.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Exact ranking reuse with explicit exact-input groups. No global selection -//! flags are required: only exact implementations can supply these inputs. - -use crate::pass2::memo::rules::Pass2RuleError; -use asap_types::stages::Memo; - -/// Rule 4, top-k reuse: a candidate of each top-k group reading a larger-`k` group, with an exact-input requirement. -pub(crate) fn add_topk_candidates(memo: &mut Memo) -> Result<(), Pass2RuleError> { - let _ = memo; - todo!("#1207 PR 4: rule 4 over groups") -} diff --git a/crates/logical-asap-optimization/src/pass2/memo/window_candidates.rs b/crates/logical-asap-optimization/src/pass2/memo/window_candidates.rs deleted file mode 100644 index a3b660450..000000000 --- a/crates/logical-asap-optimization/src/pass2/memo/window_candidates.rs +++ /dev/null @@ -1,21 +0,0 @@ -//! Rule 1, chain groups (concepts doc, section 3, "Chain groups"): a -//! `SummaryTumblingWindowChain[w](X)` group per width, and a `SummaryMerge` -//! over the `TimeRange` (and `TimeShift`s) over it as a candidate of the -//! summary state group. - -use crate::pass2::memo::rules::Pass2RuleError; -use asap_types::stages::Memo; -use asap_types::workload::QueryWorkloadEntry; - -/// Rule 1: for each summary state group that survived dead-candidate -/// elimination, a chain group and a merge candidate per tumbling width $w$ -/// from the gcd closure of the evaluation grids, ranges and offsets of the -/// queries that reach it and repeat on a known grid. `entries[i]` is query -/// `i`'s workload entry. -pub(crate) fn add_local_window_composition( - memo: &mut Memo, - entries: &[QueryWorkloadEntry], -) -> Result<(), Pass2RuleError> { - let _ = (memo, entries); - todo!("#1207 PR 4: rule 1, chain groups and the merges over them") -} diff --git a/crates/logical-asap-optimization/src/test_support.rs b/crates/logical-asap-optimization/src/test_support.rs deleted file mode 100644 index 1ecaa3654..000000000 --- a/crates/logical-asap-optimization/src/test_support.rs +++ /dev/null @@ -1,271 +0,0 @@ -// Shared fixture helpers for the stage crates' tests (feature -// `test-support`); not every test module uses every helper. -#![allow(dead_code)] - -use std::rc::Rc; - -// Stage 1 internals other crates' tests call: Pass 1's working form. -pub use crate::pass1::computation_targets::{ - generate_per_computation_candidates, PerComputationCandidates, -}; - -use asap_types::accuracy::AccuracyTarget; -use asap_types::ir::OperatorNode; -use asap_types::workload::{ - BatchEntry, DataWorkload, DurationMs, PlanningWorkload, Predictability, Query, QueryLanguage, - QueryRequirements, QueryWorkload, -}; - -/// The statistic classic HLL's failure probability at `precision` and -/// `relative_error` over `source` is left as, for Stage 3 tests that bind -/// it. The estimator keeps the format crate-private. -pub fn hll_classic_failure_statistic(precision: u8, relative_error: f64, source: &str) -> String { - asap_accuracy::guarantee::hll::classic_failure_statistic(precision, relative_error, source) -} - -pub fn lower_promql(query: &str, accuracy: AccuracyTarget) -> Rc { - let workload = PlanningWorkload { - query_workload: QueryWorkload { - language: QueryLanguage::PromQL, - query_batch: Some(vec![BatchEntry { - query: Query(query.into()), - requirements: QueryRequirements { - accuracy, - ..Default::default() - }, - predictability: Predictability::Unknown, - invocations: 1, - execute_at: None, - range_evaluation: None, - }]), - repeating_queries: None, - }, - data_workload: Some(DataWorkload::sampled_every( - asap_frontend_promql::promql_metric_names(query).unwrap_or_default(), - DurationMs(1_000), - )), - }; - asap_frontend_promql::lower_promql_query_workload(&workload) - .unwrap() - .remove(0) - .as_operator() - .cloned() - .expect("operator root") -} - -// ── Shared pre-ASAP fixture builders ───────────────────────────────────── -// -// Every builder returns an `Rc` whose schema is derived by -// `OperatorNode::new_shared`, so a fixture is exactly what a front end -// would hand the planner. Added by the test migration; only add here, never -// rename or remove (several test modules share these). - -use std::time::Duration; - -use asap_types::ir::operator::agg_intent::AggIntent; -use asap_types::ir::operator::arguments::{GroupKeys, Reduction, Source}; -use asap_types::ir::schema::{ColumnId, DataType, Field, Schema}; -use asap_types::ir::{NonASAPOp, Predicate, ScalarExpr, TimeRangeKind}; - -/// A `TimeSeries("m")` scan over `[ts(0), value(1), labels...]`, time index 0, -/// no unique key. -pub fn metric_scan(labels: &[&str]) -> Rc { - metric_scan_with_keys(labels, vec![]) -} - -/// [`metric_scan`] with explicit `unique_keys` (a `[[0]]` key makes CSE -/// willing to hoist the scan). -pub fn metric_scan_with_keys(labels: &[&str], unique_keys: Vec>) -> Rc { - let mut columns = vec![ - Field::plain("ts", DataType::Timestamp, false), - Field::plain("value", DataType::Float64, false), - ]; - columns.extend( - labels - .iter() - .map(|n| Field::plain(*n, DataType::Utf8, true)), - ); - scan("m", Schema::with_time_index(columns, 0, unique_keys)) -} - -/// A predicate-free `TimeSeries(metric)` scan with the given schema. -pub fn scan(metric: &str, schema: Schema) -> Rc { - scan_from( - Source::TimeSeries { - metric: metric.into(), - }, - schema, - ) -} - -pub fn scan_from(source: Source, schema: Schema) -> Rc { - OperatorNode::new_shared(asap_types::ir::Operator::NonASAP(NonASAPOp::Scan { - source, - predicates: vec![], - schema, - })) - .unwrap() -} - -/// A general aggregate node. -pub fn aggregate( - reduction: Reduction, - measures: Vec, - output_names: Vec, - having: Option, - child: Rc, -) -> Rc { - OperatorNode::new_shared(asap_types::ir::Operator::NonASAP(NonASAPOp::Aggregate { - reduction, - measures, - output_names, - filters: vec![], - having, - child, - })) - .unwrap() -} - -/// `intent by (by)` — a single-measure, `HAVING`-free grouped aggregate. -pub fn agg(by: Vec, intent: AggIntent, child: Rc) -> Rc { - aggregate(Reduction::by(by), vec![intent], vec![], None, child) -} - -/// `intent without (excluded)`. -pub fn without_agg( - excluded: Vec, - intent: AggIntent, - child: Rc, -) -> Rc { - aggregate( - Reduction::Reduce(GroupKeys::without(excluded)), - vec![intent], - vec![], - None, - child, - ) -} - -pub fn filter(pred: ScalarExpr, child: Rc) -> Rc { - OperatorNode::new_shared(asap_types::ir::Operator::NonASAP(NonASAPOp::Filter { - pred: Predicate(pred), - child, - })) - .unwrap() -} - -pub fn dedup(cols: Vec, child: Rc) -> Rc { - OperatorNode::new_shared(asap_types::ir::Operator::NonASAP(NonASAPOp::Dedup { - cols, - child, - })) - .unwrap() -} - -/// An explicit range selector `child[range]`. -pub fn time_range(range: Duration, child: Rc) -> Rc { - OperatorNode::new_shared(asap_types::ir::Operator::NonASAP(NonASAPOp::TimeRange { - range, - kind: TimeRangeKind::Range, - child, - })) - .unwrap() -} - -/// The workload entry of a query evaluated as `recurrence` says, exact and -/// with no latency bound. -pub fn entry( - recurrence: asap_types::workload::QueryRecurrence, -) -> asap_types::workload::QueryWorkloadEntry { - entry_with(AccuracyTarget::exact(), recurrence) -} - -/// The workload entry of a query with accuracy target `accuracy`, evaluated -/// as `recurrence` says, with no latency bound. -pub fn entry_with( - accuracy: AccuracyTarget, - recurrence: asap_types::workload::QueryRecurrence, -) -> asap_types::workload::QueryWorkloadEntry { - asap_types::workload::QueryWorkloadEntry { - query: Default::default(), - requirements: QueryRequirements { - accuracy, - max_latency_ms: None, - }, - predictability: Default::default(), - recurrence, - range_evaluation: None, - } -} - -/// The maintained-population sub-DAG for executor tests: `root` (below its -/// projections, which are kept) replaced by `EvaluatePopulation(statistic)` -/// over a current-series population of the single selector under it, -/// grouped by `grouping`, with no matchers. The caller states the statistic -/// and grouping; nothing is recognized. No planner pass offers this sub-DAG -/// yet (#681). -pub fn population_over_selector( - root: &Rc, - statistic: asap_types::ir::operator::maintained_population::PopulationStatistic, - grouping: &[&str], -) -> Rc { - use asap_types::ir::operator::maintained_population::*; - use asap_types::ir::{ASAPOp, Operator}; - if let Some(NonASAPOp::Project { - cols, - qualifier, - child, - }) = root.non_asap() - { - let child = population_over_selector(child, statistic.clone(), grouping); - let project = Operator::NonASAP(NonASAPOp::Project { - cols: cols.clone(), - qualifier: qualifier.clone(), - child, - }); - return Rc::new(OperatorNode::with_schema(project, root.schema.clone())); - } - let selectors: Vec<_> = OperatorNode::reachable(root) - .into_iter() - .filter(|node| matches!(node.non_asap(), Some(NonASAPOp::TimeRange { .. }))) - .collect(); - let [selector] = selectors.as_slice() else { - panic!("one selector under {root:?}"); - }; - let Some(NonASAPOp::TimeRange { range, child, .. }) = selector.non_asap() else { - unreachable!() - }; - let Some(NonASAPOp::Scan { - source: Source::TimeSeries { metric }, - .. - }) = child.non_asap() - else { - panic!("a time-series selector, got {child:?}"); - }; - let population = MaintainedPopulation { - input: PopulationInput::CurrentSeries(CurrentSeriesInput { - metric: metric.clone(), - matchers: Vec::new(), - grouping: grouping.iter().map(|label| label.to_string()).collect(), - without: false, - lookback_ms: range.as_millis() as u64, - }), - max_k: match statistic { - PopulationStatistic::TopK { k } => k, - _ => 0, - }, - quantiles: matches!(statistic, PopulationStatistic::Quantile { .. }), - }; - let maintained = OperatorNode::with_schema( - Operator::ASAP(ASAPOp::MaintainPopulation { - child: selector.clone(), - population, - }), - selector.schema.clone(), - ); - let evaluation = Operator::ASAP(ASAPOp::EvaluatePopulation { - child: Rc::new(maintained), - evaluation: statistic, - }); - Rc::new(OperatorNode::with_schema(evaluation, root.schema.clone())) -} diff --git a/crates/logical-asap-optimization/tests/pass_layering.rs b/crates/logical-asap-optimization/tests/pass_layering.rs deleted file mode 100644 index daf0595a7..000000000 --- a/crates/logical-asap-optimization/tests/pass_layering.rs +++ /dev/null @@ -1,59 +0,0 @@ -//! Stage 1's passes are independent modules (#1096, #1191): neither pass's -//! production code imports the other. Test modules may use the other pass to -//! build fixtures. IR helpers both passes need live in `asap-types`. - -use std::path::{Path, PathBuf}; - -/// Production lines under `src/.rs` and `src//` that name a path -/// through `needle`'s module. -fn production_lines_mentioning(pass: &str, needle: &str) -> Vec { - fn walk(dir: &Path, files: &mut Vec) { - for entry in std::fs::read_dir(dir).unwrap() { - let path = entry.unwrap().path(); - if path.is_dir() { - walk(&path, files); - // `*_tests.rs` files are `#[cfg(test)]` modules. - } else if !path.to_string_lossy().ends_with("_tests.rs") { - files.push(path); - } - } - } - let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src"); - let mut files = vec![src.join(format!("{pass}.rs"))]; - walk(&src.join(pass), &mut files); - let mut offending = Vec::new(); - for file in files { - let text = std::fs::read_to_string(&file).unwrap(); - // ponytail: a file's production code ends at its `#[cfg(test)] mod tests`; - // parse with `syn` if inline `#[cfg(test)]` items ever need excluding. - let production = text.split("#[cfg(test)]\nmod tests").next().unwrap(); - for (n, line) in production.lines().enumerate() { - if line.contains(needle) { - offending.push(format!("{}:{}: {}", file.display(), n + 1, line.trim())); - } - } - } - offending -} - -/// Pass 1's production source does not reference `pass2`. -#[test] -fn pass1_does_not_import_pass2() { - let offending = production_lines_mentioning("pass1", "pass2::"); - assert!( - offending.is_empty(), - "Pass 1 imports Pass 2:\n{}", - offending.join("\n") - ); -} - -/// Pass 2's production source does not reference `pass1`. -#[test] -fn pass2_does_not_import_pass1() { - let offending = production_lines_mentioning("pass2", "pass1::"); - assert!( - offending.is_empty(), - "Pass 2 imports Pass 1:\n{}", - offending.join("\n") - ); -} diff --git a/crates/physical-asap-optimization/src/lib.rs b/crates/physical-asap-optimization/src/lib.rs deleted file mode 100644 index 5ef0d90d1..000000000 --- a/crates/physical-asap-optimization/src/lib.rs +++ /dev/null @@ -1,15 +0,0 @@ -//! #509 Stage 2, physical ASAP-aware optimization (concepts doc, -//! section 3, "Stage 2: physical alternatives"). -//! -//! The planner facade calls [`generate_physical_asap_memo_candidates`] on -//! Pass 2's output (`asap_types::stages::LogicalASAPMemoCandidates`): each -//! logical candidate expanded into one physical candidate per valid -//! $(\tau, \ell)$, each logical edge into its physical edges with -//! $\alpha^{\log}$ and $\alpha^{\mathrm{phys}}$, and the pruned alternatives -//! (`asap_types::stages::PhysicalASAPMemoCandidates`). Stage 3 selects from -//! that output and builds the plan. The crate depends on no other stage -//! crate. - -mod catalog; - -pub use catalog::generate_physical_asap_memo_candidates; diff --git a/crates/plan-selection/src/lib.rs b/crates/plan-selection/src/lib.rs deleted file mode 100644 index d6c5fef6f..000000000 --- a/crates/plan-selection/src/lib.rs +++ /dev/null @@ -1,23 +0,0 @@ -//! #509 Stage 3, plan selection (concepts doc -//! `memo-groups-properties-requirements.md`, section 3, "Stage 3: baseline -//! selection and realization", and sections 4 and 5). -//! -//! [`select_plan`] reads Stage 2's physical candidates $\mathcal C$ and the -//! admissible part of the physical edges $\mathcal E$, selects with a MILP -//! over $x_v$, $y_{u,c,i}$, $z_{q,v}$ and $t_v$ (constraints (A)–(I); -//! (G) and (H) hold because $y$ exists only on admissible edges), and -//! builds the plan (`PhysicalASAPDAG`) from $\{x = 1\}$ and $\{y = 1\}$ -//! as its last step. The extensions add execution contexts $\kappa$ with $x^{\mathrm{mat}}_v$, -//! $x_{\kappa,v}$, $y_{\kappa,u,c,i}$ and the retention amount $h_v$ -//! (section 5), and accuracy at each query root, constraint (K), with -//! per-candidate error bounds $E_c$ and $D_c$ (section 4). Costs come from -//! `asap-cost`. - -mod milp; -mod report; -mod select; - -pub use report::{ - large_peak_memory_warning, AcceptedAccuracy, ErrorSelectingPlan, RejectionCause, Selection, -}; -pub use select::select_plan; diff --git a/crates/planner/Cargo.toml b/crates/planner/Cargo.toml index 6cf31bc74..8a79dbcb9 100644 --- a/crates/planner/Cargo.toml +++ b/crates/planner/Cargo.toml @@ -8,21 +8,24 @@ edition = "2021" # returns the selected DAG. It is the only crate that depends on every # frontend — before it, the sole facade re-exporting more than one was `asap-devtools`, # a developer-tools crate. Everything below the frontend boundary lives in the -# stage crates (`asap-logical-asap-optimization`, `asap-physical-asap-optimization`, -# `asap-plan-selection`), so a third party writing an optimization pass (issue -# #430) depends on `asap-plan-selection` (plus `asap-accuracy` to supply its own +# stage crates (`asap-stage0-memo`, `asap-stage1-pass1-per-computation-candidates`, +# `asap-stage1-pass2-reuse-candidates`, `asap-stage2-physical-optimization`, +# `asap-stage3-plan-selection`), so a third party writing an optimization pass (issue +# #430) depends on `asap-stage3-plan-selection` (plus `asap-accuracy` to supply its own # accuracy model or evidence) and never pulls in DataFusion. [dependencies] asap-types = { path = "../types" } asap-cost = { path = "../cost" } -asap-plan-selection = { path = "../plan-selection" } +asap-stage3-plan-selection = { path = "../stage3-plan-selection" } asap-frontend-sql = { path = "../frontend-sql" } asap-frontend-promql = { path = "../frontend-promql" } asap-frontend-metricsql = { path = "../frontend-metricsql" } -asap-logical-asap-optimization = { path = "../logical-asap-optimization" } +asap-stage0-memo = { path = "../stage0-memo" } +asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates" } +asap-stage1-pass2-reuse-candidates = { path = "../stage1-pass2-reuse-candidates" } # The facade runs every stage: Stage 2's catalog and realizer, Stage 3's # `select_plan`, with the deployment's accuracy model. -asap-physical-asap-optimization = { path = "../physical-asap-optimization" } +asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } asap-accuracy = { path = "../accuracy" } # The Planner's own executor: `plan_installable` offers only the summary # families it runs when the caller leaves them unrestricted. @@ -32,10 +35,8 @@ serde_json = "1" thiserror = "2" [dev-dependencies] -asap-plan-selection = { path = "../plan-selection" } -asap-physical-asap-optimization = { path = "../physical-asap-optimization" } -# Pass 1's target list (`per_computation_candidates`) for the tests. -asap-logical-asap-optimization = { path = "../logical-asap-optimization", features = ["test-support"] } +asap-stage3-plan-selection = { path = "../stage3-plan-selection" } +asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } asap-accuracy = { path = "../accuracy", features = ["test-support"] } # Tests read a plan's roots as IR (`PhysicalASAPDAG::query_roots`). asap-types = { path = "../types", features = ["test-support"] } diff --git a/crates/planner/src/lib.rs b/crates/planner/src/lib.rs index 194147021..dc6fb1350 100644 --- a/crates/planner/src/lib.rs +++ b/crates/planner/src/lib.rs @@ -8,7 +8,7 @@ //! The default pass, [`Stage1ToStage3Pass`], orchestrates the stages //! ([`run_planning`]): Stage 0, Pass 1, Pass 2, Stage 2 //! (`generate_physical_asap_memo_candidates`) and Stage 3 -//! (`asap_plan_selection::select_plan`), which builds the selected plan. +//! (`asap_stage3_plan_selection::select_plan`), which builds the selected plan. //! The stages never call each other. //! //! [`e2e_plan`] runs both steps. [`plan_installable`] runs them for a @@ -25,11 +25,13 @@ use asap_frontend_metricsql::{lower_metricsql_query_workload, MetricsqlError}; use asap_frontend_promql::{lower_promql_query_workload, PromqlError}; use asap_frontend_sql::{lower_sql_dialect, SqlError}; +mod models; mod pass; mod run; +pub use models::PlanningModels; pub use pass::{ optimize, OptimizationInput, OptimizationInputError, OptimizationPass, OptimizeError, - PassNameConflict, PassRegistry, PlanOutput, PlanningModels, + PassNameConflict, PassRegistry, PlanOutput, }; pub use run::{ run_planning, PlanSearchSettings, PlanningReport, PlanningRun, SelectionError, @@ -51,7 +53,9 @@ pub use asap_cost::{ ResourceSpeed, ResourceUnitCost, SummaryOperation, }; pub use asap_frontend_sql::SqlCatalog; -pub use asap_plan_selection::{AcceptedAccuracy, ErrorSelectingPlan, RejectionCause, Selection}; +pub use asap_stage3_plan_selection::{ + AcceptedAccuracy, ErrorSelectingPlan, RejectionCause, Selection, +}; pub use asap_types::deployment_capabilities::{DeploymentCapabilities, SupportedSummary}; pub use asap_types::ir::properties::summary_coverage::{ ColumnIdentity, Constraint, IntervalConstraintLimit, SelectionBox, diff --git a/crates/planner/src/models.rs b/crates/planner/src/models.rs new file mode 100644 index 000000000..e4a443dff --- /dev/null +++ b/crates/planner/src/models.rs @@ -0,0 +1,88 @@ +//! The planning models the facade splits by stage: the deployment's +//! measured accuracy, cost inputs and capabilities ([`PlanningModels`]). + +use asap_accuracy::{AccuracyEvidence, NoMeasuredGuarantees}; +use asap_cost::CostInputs; +use asap_types::deployment_capabilities::DeploymentCapabilities; + +static DEFAULT_COST_INPUTS: std::sync::LazyLock = + std::sync::LazyLock::new(CostInputs::default); + +static DEFAULT_DEPLOYMENT: std::sync::LazyLock = + std::sync::LazyLock::new(DeploymentCapabilities::default); + +/// Planning logic, as opposed to the scoped facts it consumes: a model can have +/// a built-in default, evidence about a particular deployment cannot. +/// +/// The facade splits them by stage: Stage 1 reads the supported summaries +/// of `deployment_capabilities`, Pass 2 the accuracy `evidence`, Stage 2 the +/// deployment's retention, and Stage 3 (plan selection) compares candidates +/// under `cost_inputs` ([`CostInputs`]). +#[derive(Clone, Copy)] +#[non_exhaustive] +pub struct PlanningModels<'a> { + /// The deployment's measured accuracy, which Pass 2 reads before each + /// summary's theoretical guarantee; none by default. + pub evidence: &'a dyn AccuracyEvidence, + /// The deployment's cost inputs: the cost model (default + /// cost model 1 with illustrative unit costs), the resource speed and + /// the non-repeating query horizon. + pub cost_inputs: &'a CostInputs, + /// What the deployment's executor can run and keep: the summaries it + /// supports (Stage 1), whether it retains raw data (Stage 3) and + /// whether it keeps query-time results across evaluations (Stage 2); + /// default [`DeploymentCapabilities::default`]. + pub deployment_capabilities: &'a DeploymentCapabilities, + /// Do not enforce accuracy: the facade gives every query "no accuracy + /// target" before Pass 2, so no readout gets a required accuracy and + /// every θ connects (a top-k's heap still holds k). For comparing + /// candidates on cost alone, e.g. a benchmark of sketch plans with no + /// analytical guarantee. Default `false`. + pub ignore_accuracy_guarantees: bool, +} + +impl<'a> PlanningModels<'a> { + /// This evidence with the default plan selection settings. + pub fn new(evidence: &'a dyn AccuracyEvidence) -> Self { + Self { + evidence, + cost_inputs: &DEFAULT_COST_INPUTS, + deployment_capabilities: &DEFAULT_DEPLOYMENT, + ignore_accuracy_guarantees: false, + } + } + + /// The built-in models: no accuracy evidence. + pub fn builtin() -> PlanningModels<'static> { + PlanningModels::new(&NoMeasuredGuarantees) + } + + /// These models, enforcing no accuracy target when `ignore` + /// (`ignore_accuracy_guarantees`). + pub fn with_ignore_accuracy_guarantees(mut self, ignore: bool) -> Self { + self.ignore_accuracy_guarantees = ignore; + self + } + + pub fn with_evidence(mut self, evidence: &'a dyn AccuracyEvidence) -> Self { + self.evidence = evidence; + self + } + + /// These models with the deployment's cost inputs (cost + /// model, resource speed, non-repeating query horizon). + pub fn with_cost_inputs(mut self, cost_inputs: &'a CostInputs) -> Self { + self.cost_inputs = cost_inputs; + self + } + + /// These models with the deployment's capabilities (supported + /// summaries, raw-data and query-time retention). + pub fn with_deployment_capabilities( + mut self, + deployment_capabilities: &'a DeploymentCapabilities, + ) -> Self { + self.deployment_capabilities = deployment_capabilities; + self + } +} diff --git a/crates/planner/src/pass.rs b/crates/planner/src/pass.rs index 8b4d2528d..2bc70b697 100644 --- a/crates/planner/src/pass.rs +++ b/crates/planner/src/pass.rs @@ -1,5 +1,4 @@ -//! The pluggable optimization pass (issue #430), and the planning models -//! the facade splits by stage. +//! The pluggable optimization pass (issue #430). //! //! An [`OptimizationPass`] is the whole optimization stage behind one //! signature: pre-ASAP IR in, post-ASAP DAG out. The trait deliberately names @@ -18,96 +17,13 @@ use std::collections::BTreeMap; use asap_types::workload::parsed_workload::ParsedWorkload; use asap_types::workload::WorkloadError; +use crate::models::PlanningModels; use crate::run::{SelectionError, Stage1ToStage3Pass}; -use asap_accuracy::{AccuracyEvidence, NoMeasuredGuarantees}; -use asap_cost::CostInputs; -use asap_logical_asap_optimization::PerComputationCandidateError; -use asap_types::deployment_capabilities::DeploymentCapabilities; +use asap_stage1_pass1_per_computation_candidates::PerComputationCandidateError; use asap_types::plan::physical_asap_dag::{PhysicalASAPDAG, PhysicalASAPDAGValidationError}; -static DEFAULT_COST_INPUTS: std::sync::LazyLock = - std::sync::LazyLock::new(CostInputs::default); -static DEFAULT_DEPLOYMENT: std::sync::LazyLock = - std::sync::LazyLock::new(DeploymentCapabilities::default); - // ── Input ──────────────────────────────────────────────────────────────── -/// Planning logic, as opposed to the scoped facts it consumes: a model can have -/// a built-in default, evidence about a particular deployment cannot. -/// -/// The facade splits them by stage: Stage 1 reads the supported summaries -/// of `deployment_capabilities`, Pass 2 the accuracy `evidence`, Stage 2 the -/// deployment's retention, and Stage 3 (plan selection) compares candidates -/// under `cost_inputs` ([`CostInputs`]). -#[derive(Clone, Copy)] -#[non_exhaustive] -pub struct PlanningModels<'a> { - /// The deployment's measured accuracy, which Pass 2 reads before each - /// summary's theoretical guarantee; none by default. - pub evidence: &'a dyn AccuracyEvidence, - /// The deployment's cost inputs: the cost model (default - /// cost model 1 with illustrative unit costs), the resource speed and - /// the non-repeating query horizon. - pub cost_inputs: &'a CostInputs, - /// What the deployment's executor can run and keep: the summaries it - /// supports (Stage 1), whether it retains raw data (Stage 3) and - /// whether it keeps query-time results across evaluations (Stage 2); - /// default [`DeploymentCapabilities::default`]. - pub deployment_capabilities: &'a DeploymentCapabilities, - /// Do not enforce accuracy: the facade gives every query "no accuracy - /// target" before Pass 2, so no readout gets a required accuracy and - /// every θ connects (a top-k's heap still holds k). For comparing - /// candidates on cost alone, e.g. a benchmark of sketch plans with no - /// analytical guarantee. Default `false`. - pub ignore_accuracy_guarantees: bool, -} - -impl<'a> PlanningModels<'a> { - /// This evidence with the default plan selection settings. - pub fn new(evidence: &'a dyn AccuracyEvidence) -> Self { - Self { - evidence, - cost_inputs: &DEFAULT_COST_INPUTS, - deployment_capabilities: &DEFAULT_DEPLOYMENT, - ignore_accuracy_guarantees: false, - } - } - - /// The built-in models: no accuracy evidence. - pub fn builtin() -> PlanningModels<'static> { - PlanningModels::new(&NoMeasuredGuarantees) - } - - /// These models, enforcing no accuracy target when `ignore` - /// (`ignore_accuracy_guarantees`). - pub fn with_ignore_accuracy_guarantees(mut self, ignore: bool) -> Self { - self.ignore_accuracy_guarantees = ignore; - self - } - - pub fn with_evidence(mut self, evidence: &'a dyn AccuracyEvidence) -> Self { - self.evidence = evidence; - self - } - - /// These models with the deployment's cost inputs (cost - /// model, resource speed, non-repeating query horizon). - pub fn with_cost_inputs(mut self, cost_inputs: &'a CostInputs) -> Self { - self.cost_inputs = cost_inputs; - self - } - - /// These models with the deployment's capabilities (supported - /// summaries, raw-data and query-time retention). - pub fn with_deployment_capabilities( - mut self, - deployment_capabilities: &'a DeploymentCapabilities, - ) -> Self { - self.deployment_capabilities = deployment_capabilities; - self - } -} - #[derive(Clone, Copy)] #[non_exhaustive] pub struct OptimizationInput<'a> { diff --git a/crates/planner/src/run.rs b/crates/planner/src/run.rs index 34d3f1f73..7022ef25d 100644 --- a/crates/planner/src/run.rs +++ b/crates/planner/src/run.rs @@ -3,15 +3,17 @@ //! builds the selected plan. No stage calls another, and none has a //! deadline: each runs to completion. -use asap_logical_asap_optimization::memo_of_queries; +use asap_stage0_memo::memo_of_queries; use std::rc::Rc; use std::time::Instant; -use asap_logical_asap_optimization::generate_logical_asap_memo_candidates; -use asap_logical_asap_optimization::{pass1_memo, Pass1Error, PerComputationCandidateError}; -use asap_physical_asap_optimization::generate_physical_asap_memo_candidates; -use asap_plan_selection::{select_plan, ErrorSelectingPlan, Selection}; +use asap_stage1_pass1_per_computation_candidates::{ + pass1_memo, Pass1Error, PerComputationCandidateError, +}; +use asap_stage1_pass2_reuse_candidates::generate_logical_asap_memo_candidates; +use asap_stage2_physical_optimization::generate_physical_asap_memo_candidates; +use asap_stage3_plan_selection::{select_plan, ErrorSelectingPlan, Selection}; use asap_types::deployment_capabilities::DeploymentCapabilitiesError; use asap_types::ir::schema::series_identity::with_promql_series_identity; use asap_types::ir::QueryRoot; @@ -19,7 +21,8 @@ use asap_types::plan::physical_asap_dag::PhysicalASAPDAG; use asap_types::stages::{LogicalASAPMemoCandidates, Memo, PhysicalASAPMemoCandidates}; use asap_types::workload::{DataWorkload, QueryLanguage, QueryWorkloadEntry}; -use crate::pass::{OptimizationInput, OptimizationPass, OptimizeError, PlanOutput, PlanningModels}; +use crate::models::PlanningModels; +use crate::pass::{OptimizationInput, OptimizationPass, OptimizeError, PlanOutput}; /// How the facade searches. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] diff --git a/crates/stage0-memo/Cargo.toml b/crates/stage0-memo/Cargo.toml new file mode 100644 index 000000000..5fda801d9 --- /dev/null +++ b/crates/stage0-memo/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "asap-stage0-memo" +version = "0.1.0" +edition = "2021" + +# #509 Stage 0: hash-consing the workload's logical DAGs into the memo groups +# (`asap_types::stages::Memo`, without candidates) that Stage 1 fills. Depends +# only on asap-types; no other stage crate depends on it. +[dependencies] +asap-types = { path = "../types" } diff --git a/crates/logical-asap-optimization/src/stage0.rs b/crates/stage0-memo/src/lib.rs similarity index 63% rename from crates/logical-asap-optimization/src/stage0.rs rename to crates/stage0-memo/src/lib.rs index fefb25c6c..5227ca379 100644 --- a/crates/logical-asap-optimization/src/stage0.rs +++ b/crates/stage0-memo/src/lib.rs @@ -1,7 +1,12 @@ -//! Stage 0: the memo groups of the workload's query roots (a [`Memo`] -//! without candidates). Each node of the queries' DAGs becomes the group of -//! its expression, found or added by [`Memo::find_or_add_group`], so -//! identical sub-expressions are one group. Stage 1 starts from these groups. +//! `asap-stage0-memo` — #509 Stage 0: the memo groups of the workload's +//! query roots (a [`Memo`] without candidates). Each node of the queries' +//! DAGs becomes the group of its expression, found or added by +//! [`Memo::find_or_add_group`], so identical sub-expressions are one group. +//! Stage 1 starts from these groups. +//! +//! It depends only on `asap-types`, where its output (`Memo`) lives; no +//! other stage crate depends on it (the frontends' tests aside, listed in +//! `crate_graph.rs`), and the planner facade calls it first. use asap_types::accuracy::AccuracyTarget; use asap_types::ir::{QueryRoot, SchemaDerivationError}; diff --git a/crates/stage1-pass1-per-computation-candidates/Cargo.toml b/crates/stage1-pass1-per-computation-candidates/Cargo.toml new file mode 100644 index 000000000..0a4df4c1a --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/Cargo.toml @@ -0,0 +1,22 @@ +[package] +name = "asap-stage1-pass1-per-computation-candidates" +version = "0.1.0" +edition = "2021" + +# #509 Stage 1, Pass 1: the initial candidates of each memo group (exact, +# exact accumulator, summaries, fused builds), with the shared analytical +# accuracy model (`asap-accuracy`). Reads Stage 0's memo through +# `asap_types::stages`; depends on no other stage crate and on no +# query-language frontend. +[dependencies] +asap-types = { path = "../types" } +asap-accuracy = { path = "../accuracy" } +thiserror = "2" + +[features] +# The test helpers (`test_support`) other crates' tests share. +test-support = [] + +[dev-dependencies] +asap-types = { path = "../types", features = ["test-support"] } +asap-accuracy = { path = "../accuracy", features = ["test-support"] } diff --git a/crates/logical-asap-optimization/src/pass1/computation_targets.rs b/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs similarity index 52% rename from crates/logical-asap-optimization/src/pass1/computation_targets.rs rename to crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs index 3aac87266..d66060f30 100644 --- a/crates/logical-asap-optimization/src/pass1/computation_targets.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs @@ -56,7 +56,7 @@ use thiserror::Error; use asap_accuracy::sizing::sketch_statistic; -use crate::pass1::realization::summary_candidates; +use crate::summary_realization::summary_candidates; use asap_types::deployment_capabilities::{summary_supported, SupportedSummary}; use asap_types::stages::{ ComputationTarget, FusedComputation, HavingEntry, HavingPlacement, @@ -102,7 +102,7 @@ fn prune_own( /// Compact Pass 1 inventory over the memo groups it walked: one target per /// measure of each aggregate group, however many queries read the group. /// Pass 1's working form, not its output: -/// [`pass1_memo`](crate::pass1::pass1_memo) +/// [`pass1_memo`](crate::pass1_memo) /// builds, prunes and attaches it to the memo groups. Public only to tests /// (feature `test-support`). #[derive(Debug, Clone)] @@ -762,7 +762,7 @@ fn reads_only_time_series(node: &OperatorNode) -> bool { pub(super) fn whole_expression_input( target: &OperatorNode, ) -> Option<(Rc, SummaryUpdate, Reduction)> { - use crate::pass1::realization::realize_keyed_additive_summary_input; + use crate::summary_realization::realize_keyed_additive_summary_input; let Some(NonASAPOp::Aggregate { child, reduction, @@ -816,22 +816,10 @@ pub(super) fn whole_expression_input( mod tests { use super::*; - use asap_types::accuracy::{AccuracyGuarantee, AccuracyTarget}; - use asap_types::ir::operator::arguments::{BinaryOpKind, JoinKind}; - use asap_types::ir::scalar::expr_ir::ArithmeticOpKind; - use asap_types::ir::scalar::{CompareOpKind, ScalarValue}; - use asap_types::ir::{BinaryOperator, ExprSemantics, Operator, ProjectItem, ScalarExpr}; - use asap_types::summary_type::{NonNegativeWeightProof, WeightDomain}; - use asap_accuracy::propagation::raw_data_samples_of_metric; + use asap_types::summary_type::{NonNegativeWeightProof, WeightDomain}; - use asap_accuracy::composition::PRODUCT_OPERAND_DOMAINS; - - use asap_accuracy::test_support::{ - composed_guarantee, estimate_has_bound, scalar_guarantee, source_distinct_guarantee, - QUOTIENT_OPERAND_DOMAINS, - }; - use asap_types::accuracy::{AccuracyMetric, BoundExpr, ProbabilityExpr}; + use asap_accuracy::test_support::estimate_has_bound; use asap_types::summary_type::SketchStatistic; /// Approximate count keeps one exact option, its accumulator, beside the @@ -872,757 +860,6 @@ mod tests { } } - /// Guarantee composition through scalar and vector arithmetic (#669). - mod guarantee_composition { - use super::*; - use crate::test_support::lower_promql; - use asap_types::accuracy::AccuracyTarget; - - fn with_bound(metric: AccuracyMetric, bound: f64, delta: f64) -> AccuracyGuarantee { - AccuracyGuarantee::new( - metric, - BoundExpr::Constant { value: bound }, - ProbabilityExpr::Constant { value: delta }, - vec![], - ) - } - fn abs(bound: f64, delta: f64) -> AccuracyGuarantee { - with_bound(AccuracyMetric::ABSOLUTE, bound, delta) - } - fn rel(bound: f64) -> AccuracyGuarantee { - with_bound(AccuracyMetric::Relative, bound, 0.0) - } - /// `sum(m)` carrying `guarantee`. - fn node(guarantee: AccuracyGuarantee) -> Rc { - node_over("sum(m)", guarantee) - } - /// `query` carrying `guarantee`. - fn node_over(query: &str, guarantee: AccuracyGuarantee) -> Rc { - let node = lower_promql(query, AccuracyTarget::exact()); - Rc::new((*node).clone().with_guarantee(Some(guarantee))) - } - fn scalar(guarantee: AccuracyGuarantee) -> ScalarExpr { - ScalarExpr::PromqlScalarFromVector(node(guarantee)) - } - fn lit(value: f64) -> ScalarExpr { - ScalarExpr::literal_f64(value) - } - fn arith(op: ArithmeticOpKind, left: ScalarExpr, right: ScalarExpr) -> ScalarExpr { - ScalarExpr::Arithmetic { - op, - left: Box::new(left), - right: Box::new(right), - semantics: ExprSemantics::Promql, - } - } - fn call(name: &str, args: Vec) -> ScalarExpr { - ScalarExpr::FunctionCall { - name: name.into(), - args, - } - } - fn of(expr: &ScalarExpr) -> Option { - scalar_guarantee(expr, &|_| None) - } - fn bound(g: &AccuracyGuarantee) -> f64 { - g.spec.error.evaluate().expect("a resolved bound") - } - fn delta(g: &AccuracyGuarantee) -> f64 { - g.spec - .failure_probability - .evaluate() - .expect("a resolved probability") - } - fn close(a: f64, b: f64) -> bool { - (a - b).abs() < 1e-12 - } - - /// Absolute errors add through `x ± y`, with the union bound on the - /// failure probability; `−x` and `x ± c` keep the error, `c · x` and - /// `x / c` scale it by `|c|` and `1/|c|`, division by a literal zero - /// has none. - #[test] - fn absolute_errors_compose_through_arithmetic() { - use ArithmeticOpKind::*; - let (x, y) = (scalar(abs(0.01, 0.001)), scalar(abs(0.02, 0.002))); - for op in [Add, Sub] { - let g = of(&arith(op.clone(), x.clone(), y.clone())).unwrap(); - assert_eq!(g.spec.accuracy_metric, AccuracyMetric::ABSOLUTE, "{op:?}"); - assert!(close(bound(&g), 0.03) && close(delta(&g), 0.003), "{op:?}"); - for shifted in [ - arith(op.clone(), x.clone(), lit(5.0)), - arith(op.clone(), lit(5.0), x.clone()), - arith(op.clone(), x.clone(), ScalarExpr::EvalTimestamp), - ] { - let g = of(&shifted).unwrap(); - assert!(close(bound(&g), 0.01) && close(delta(&g), 0.001), "{op:?}"); - } - } - let negated = ScalarExpr::Negative { - expr: Box::new(x.clone()), - semantics: ExprSemantics::Promql, - }; - assert!(close(bound(&of(&negated).unwrap()), 0.01)); - for (expr, expected) in [ - (arith(Mul, lit(-3.0), x.clone()), 0.03), - (arith(Mul, x.clone(), lit(3.0)), 0.03), - (arith(Div, x.clone(), lit(-4.0)), 0.0025), - ] { - let g = of(&expr).unwrap(); - assert!( - close(bound(&g), expected) && close(delta(&g), 0.001), - "{expr:?}" - ); - } - for none in [ - arith(Div, x.clone(), lit(0.0)), - arith(Mul, x.clone(), ScalarExpr::EvalTimestamp), - arith(Pow, x.clone(), lit(2.0)), - ] { - assert_eq!(of(&none), None, "{none:?}"); - } - } - - /// A product of two estimates has an absolute bound - /// `|x|·e_y + |y|·e_x + e_x·e_y`, and a quotient with an approximate - /// denominator one that needs the denominator bounded away from - /// zero: both need operand domains, so Stage 1 leaves them symbolic - /// for plan selection to bind. Relative errors need no domain: a - /// product has the closed form `(1 + a)(1 + b) − 1`, a quotient - /// `(a + b) / (1 − b)` (`a = 0` for an exact numerator). The failure - /// probability is the union bound. A rank error composes to none. - #[test] - fn products_and_quotients_of_estimates_have_closed_or_symbolic_bounds() { - use ArithmeticOpKind::*; - let unknown = |statistic: &str| BoundExpr::Unknown { - statistic: statistic.into(), - }; - let (x, y) = (scalar(abs(0.01, 0.001)), scalar(abs(0.02, 0.002))); - let product = of(&arith(Mul, x.clone(), y.clone())).unwrap(); - assert_eq!(product.spec.accuracy_metric, AccuracyMetric::ABSOLUTE); - assert_eq!(product.spec.error, unknown(PRODUCT_OPERAND_DOMAINS)); - assert!(close(delta(&product), 0.003)); - for quotient in [ - arith(Div, x.clone(), y.clone()), - arith(Div, lit(1.0), x.clone()), - arith(Div, x.clone(), scalar(rel(0.01))), - ] { - let g = of("ient).unwrap(); - assert_eq!( - g.spec.accuracy_metric, - AccuracyMetric::ABSOLUTE, - "{quotient:?}" - ); - assert_eq!( - g.spec.error, - unknown(QUOTIENT_OPERAND_DOMAINS), - "{quotient:?}" - ); - } - let ratio = of(&arith( - Div, - scalar(with_bound(AccuracyMetric::Relative, 0.01, 0.001)), - scalar(with_bound(AccuracyMetric::Relative, 0.02, 0.002)), - )) - .unwrap(); - assert_eq!(ratio.spec.accuracy_metric, AccuracyMetric::Relative); - assert!(close(bound(&ratio), (0.01 + 0.02) / (1.0 - 0.02))); - assert!(close(delta(&ratio), 0.003)); - let reciprocal = of(&arith(Div, lit(2.0), scalar(rel(0.02)))).unwrap(); - assert_eq!(reciprocal.spec.accuracy_metric, AccuracyMetric::Relative); - assert!(close(bound(&reciprocal), 0.02 / (1.0 - 0.02))); - // A denominator bound of 1 or more leaves the ratio unbounded. - assert_eq!(of(&arith(Div, scalar(rel(0.01)), scalar(rel(1.0)))), None); - // A relative bound still symbolic in Stage 1 has no ratio rule. - let symbolic = AccuracyGuarantee::new( - AccuracyMetric::Relative, - unknown("values_sign"), - ProbabilityExpr::Zero, - vec![], - ); - assert_eq!(of(&arith(Div, scalar(symbolic), scalar(rel(0.01)))), None); - let relative = of(&arith(Mul, scalar(rel(0.01)), scalar(rel(0.02)))).unwrap(); - assert_eq!(relative.spec.accuracy_metric, AccuracyMetric::Relative); - assert!(close(bound(&relative), 0.01 + 0.02 + 0.0002)); - let rank = scalar(with_bound(AccuracyMetric::Rank, 0.01, 0.001)); - assert_eq!(of(&arith(Mul, rank.clone(), x.clone())), None); - assert_eq!(of(&arith(Div, x, rank)), None); - } - - /// A relative error survives negation and scaling by an exact value, - /// but not a shift (`x + c`) or a sum or difference of estimates - /// (cancellation); a rank error composes to no guarantee (a rank - /// interval counts as none in the MVP). - #[test] - fn relative_and_rank_errors_compose_only_where_sound() { - use ArithmeticOpKind::*; - let x = scalar(rel(0.01)); - for kept in [ - ScalarExpr::Negative { - expr: Box::new(x.clone()), - semantics: ExprSemantics::Promql, - }, - arith(Mul, x.clone(), lit(-2.0)), - arith(Div, x.clone(), ScalarExpr::EvalTimestamp), - ] { - let g = of(&kept).unwrap(); - assert_eq!(g.spec.accuracy_metric, AccuracyMetric::Relative, "{kept:?}"); - assert!(close(bound(&g), 0.01), "{kept:?}"); - } - for none in [ - arith(Add, x.clone(), lit(1.0)), - arith(Sub, x.clone(), scalar(rel(0.01))), - ] { - assert_eq!(of(&none), None, "{none:?}"); - } - let rank = scalar(with_bound(AccuracyMetric::Rank, 0.01, 0.001)); - for none in [ - arith(Sub, rank.clone(), rank.clone()), - arith(Mul, rank.clone(), lit(2.0)), - call("promql_clamp_max", vec![rank, lit(1.0)]), - ] { - assert_eq!(of(&none), None, "{none:?}"); - } - } - - /// `clamp`, `clamp_min`, `clamp_max` and `abs` are 1-Lipschitz and - /// monotone in each argument: the result keeps the largest absolute - /// (or relative) error of its arguments, with the union bound on the - /// failure probability. - #[test] - fn clamp_and_abs_keep_the_largest_argument_error() { - let x = scalar(abs(0.01, 0.001)); - for expr in [ - call("promql_clamp", vec![x.clone(), lit(0.0), lit(10.0)]), - call("promql_clamp_min", vec![x.clone(), lit(0.0)]), - call("promql_clamp_max", vec![x.clone(), lit(10.0)]), - call("promql_abs", vec![x.clone()]), - call("abs", vec![x.clone()]), - ] { - let g = of(&expr).unwrap(); - assert_eq!(g.spec.accuracy_metric, AccuracyMetric::ABSOLUTE, "{expr:?}"); - assert!( - close(bound(&g), 0.01) && close(delta(&g), 0.001), - "{expr:?}" - ); - } - let bounded = of(&call( - "promql_clamp", - vec![x.clone(), scalar(abs(0.03, 0.002)), lit(10.0)], - )) - .unwrap(); - assert!(close(bound(&bounded), 0.03) && close(delta(&bounded), 0.003)); - let relative = of(&call( - "promql_clamp", - vec![scalar(rel(0.01)), scalar(rel(0.02)), lit(10.0)], - )) - .unwrap(); - assert_eq!(relative.spec.accuracy_metric, AccuracyMetric::Relative); - assert!(close(bound(&relative), 0.02)); - let mixed = call("promql_clamp_min", vec![x, scalar(rel(0.02))]); - assert_eq!(of(&mixed), None); - assert_eq!(of(&call("promql_floor", vec![scalar(rel(0.01))])), None); - } - - /// A comparison over an estimate has no guarantee on its output (a - /// band guarantee is later work); over exact operands it is exact. - #[test] - fn comparisons_over_estimates_have_no_guarantee() { - let compare = |left: ScalarExpr| ScalarExpr::Compare { - left: Box::new(left), - op: CompareOpKind::Gt, - right: Box::new(lit(5.0)), - semantics: ExprSemantics::Promql, - }; - assert_eq!(of(&compare(scalar(abs(0.01, 0.001)))), None); - assert!(of(&compare(scalar(AccuracyGuarantee::exact("exact")))) - .is_some_and(|g| g.is_exact())); - } - - /// A SQL scalar subquery inherits its relation's guarantee, as - /// PromQL `scalar(v)` does. - #[test] - fn a_scalar_subquery_inherits_its_guarantee() { - let g = abs(0.01, 0.001); - let expr = arith( - ArithmeticOpKind::Add, - ScalarExpr::ScalarSubquery(node(g.clone())), - lit(1.0), - ); - assert!(close(bound(&of(&expr).unwrap()), 0.01)); - } - - /// Two estimates count their failure probabilities once each (union - /// bound), even when they read one shared summary: the built-in - /// guarantees hold per estimate, not simultaneously. The same - /// planned estimate read twice fails or holds as one event, so its - /// failure probability counts once. - #[test] - fn failure_probability_counts_once_per_distinct_estimate() { - let shared = node(abs(0.01, 0.001)); - // Equal to `shared`, but planned separately. - let other = node(abs(0.01, 0.001)); - let same = ScalarExpr::PromqlScalarFromVector(shared.clone()); - let twice = of(&arith(ArithmeticOpKind::Add, same.clone(), same.clone())).unwrap(); - assert!(close(bound(&twice), 0.02) && close(delta(&twice), 0.001)); - let distinct = of(&arith( - ArithmeticOpKind::Add, - same, - ScalarExpr::PromqlScalarFromVector(other.clone()), - )) - .unwrap(); - assert!(close(bound(&distinct), 0.02) && close(delta(&distinct), 0.002)); - let vector = |lhs: &Rc, rhs: &Rc| { - let node = OperatorNode::new(Operator::NonASAP(NonASAPOp::BinaryOp { - operator: BinaryOperator { - checked_relative_division: false, - checked_finite_division: false, - kind: BinaryOpKind::Arithmetic(ArithmeticOpKind::Sub), - vector_match: None, - }, - return_bool: false, - lhs: lhs.clone(), - rhs: rhs.clone(), - })) - .unwrap(); - composed_guarantee(&node).unwrap() - }; - assert!(close(delta(&vector(&shared, &shared)), 0.001)); - assert!(close(delta(&vector(&shared, &other)), 0.002)); - } - - /// `left JOIN right ON pred`, composed. - fn join( - kind: JoinKind, - left: &Rc, - right: &Rc, - pred: ScalarExpr, - ) -> OperatorNode { - let mut node = OperatorNode::new(Operator::NonASAP(NonASAPOp::Join { - kind, - pred: Predicate(pred), - left: left.clone(), - right: right.clone(), - })) - .unwrap(); - node.guarantee = composed_guarantee(&node); - node - } - fn column(id: usize) -> ScalarExpr { - ScalarExpr::Column(id) - } - fn equals(left: ScalarExpr, right: ScalarExpr) -> ScalarExpr { - ScalarExpr::Compare { - left: Box::new(left), - op: CompareOpKind::Eq, - right: Box::new(right), - semantics: ExprSemantics::Sql, - } - } - /// `CASE WHEN condition THEN NULL ELSE otherwise END` over `child`, - /// composed. - fn case_over( - child: &OperatorNode, - condition: ScalarExpr, - otherwise: ScalarExpr, - ) -> Option { - let node = OperatorNode::new(Operator::NonASAP(NonASAPOp::Project { - cols: vec![ProjectItem { - alias: Some("v".into()), - expr: ScalarExpr::Case { - operand: None, - branches: vec![(condition, ScalarExpr::Literal(ScalarValue::Null))], - else_expr: Some(Box::new(otherwise)), - }, - }], - qualifier: None, - child: Rc::new(child.clone()), - })) - .unwrap(); - composed_guarantee(&node) - } - /// An approximate node and an exact one, and the approximate one's - /// column count (its columns come first in a join). - fn approximate_and_exact() -> (Rc, Rc, usize) { - let approximate = node(rel(0.01)); - let exact = node_over("count(m)", AccuracyGuarantee::exact("test")); - let width = approximate.schema.fields.len(); - (approximate, exact, width) - } - - /// A join whose other input is exact and whose predicate reads only - /// exact columns keeps the approximate input's guarantee: a cross - /// join, or a key equality on the exact input's columns. - #[test] - fn join_beside_an_exact_input_on_exact_columns_keeps_the_guarantee() { - let (approximate, exact, width) = approximate_and_exact(); - for (kind, pred) in [ - ( - JoinKind::Cross, - ScalarExpr::Literal(ScalarValue::Boolean(true)), - ), - (JoinKind::Inner, equals(column(width), lit(0.0))), - (JoinKind::Left, equals(column(width), lit(0.0))), - ] { - assert_eq!( - join(kind.clone(), &approximate, &exact, pred).guarantee, - Some(rel(0.01)), - "{kind:?}" - ); - } - // Either side. - assert_eq!( - join( - JoinKind::Cross, - &exact, - &approximate, - ScalarExpr::Literal(ScalarValue::Boolean(true)) - ) - .guarantee, - Some(rel(0.01)) - ); - } - - /// A join keyed on an approximate input's column, a semi-join, or - /// two approximate inputs have no guarantee (column-level tracking - /// is #689). - #[test] - fn join_on_an_approximate_key_has_no_guarantee() { - let (approximate, exact, width) = approximate_and_exact(); - assert_eq!( - join( - JoinKind::Inner, - &approximate, - &exact, - equals(column(0), column(width)) - ) - .guarantee, - None - ); - assert_eq!( - join( - JoinKind::Semi, - &exact, - &approximate, - ScalarExpr::Literal(ScalarValue::Boolean(true)) - ) - .guarantee, - None - ); - assert_eq!( - join( - JoinKind::Cross, - &approximate, - &approximate, - ScalarExpr::Literal(ScalarValue::Boolean(true)) - ) - .guarantee, - None - ); - } - - /// A `CASE` whose condition reads only exact columns keeps each - /// branch's guarantee (a NULL branch is exact); one testing an - /// approximate column has none. - #[test] - fn case_on_exact_columns_keeps_the_branch_guarantee() { - let (approximate, exact, width) = approximate_and_exact(); - let joined = join( - JoinKind::Cross, - &approximate, - &exact, - ScalarExpr::Literal(ScalarValue::Boolean(true)), - ); - let value = approximate.schema.fields.len() - 1; - assert_eq!( - case_over(&joined, equals(column(width), lit(0.0)), column(value)), - Some(rel(0.01)) - ); - assert_eq!( - case_over(&joined, equals(column(value), lit(0.0)), column(value)), - None - ); - } - - /// `node` projecting `cols` over `child`, composed. - fn project(child: &OperatorNode, cols: Vec) -> OperatorNode { - let mut node = OperatorNode::new(Operator::NonASAP(NonASAPOp::Project { - cols: cols - .into_iter() - .enumerate() - .map(|(i, expr)| ProjectItem { - alias: Some(format!("c{i}")), - expr, - }) - .collect(), - qualifier: None, - child: Rc::new(child.clone()), - })) - .unwrap(); - node.guarantee = composed_guarantee(&node); - node - } - - /// Over a join, a projection reads each column's own guarantee, - /// not the child's sample value (which may be an exact input's - /// column): `sum(m) * 1000` beside the exact side's `value` has - /// the scaled error 1000, not the approximate side's 1. A - /// projection over that computed projection has no per-column - /// guarantees, so it has none (#689). - #[test] - fn projection_over_a_join_reads_each_columns_guarantee() { - let approximate = node(abs(1.0, 0.01)); - let exact = node_over("m", AccuracyGuarantee::exact("test")); - let joined = join( - JoinKind::Cross, - &approximate, - &exact, - ScalarExpr::Literal(ScalarValue::Boolean(true)), - ); - assert_eq!(joined.guarantee, Some(abs(1.0, 0.01))); - let sum = approximate.schema.fields.len() - 1; - let value = approximate.schema.fields.len() + exact.schema.fields.len() - 1; - let scaled = project( - &joined, - vec![ - arith(ArithmeticOpKind::Mul, column(sum), lit(1000.0)), - column(value), - ], - ); - assert_eq!(scaled.guarantee.as_ref().map(bound), Some(1000.0)); - let stacked = project( - &scaled, - vec![arith(ArithmeticOpKind::Add, column(1), lit(1.0)), column(0)], - ); - assert_eq!(stacked.guarantee, None); - } - } - - fn inventory(query: &str) -> PerComputationCandidates { - let root = crate::test_support::lower_promql( - query, - AccuracyTarget::max_error(0.01).failure_probability(0.001), - ); - // Per-series state ranks each series' identity, which the rows carry - // as a column; a query over aggregated rows is planned over labels. - let root = asap_types::ir::schema::series_identity::with_promql_series_identity(&root) - .unwrap_or(root); - generate_per_computation_candidates( - &crate::stage0::memo_of_queries( - &[QueryRoot::Operator(root)], - &[None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap() - } - - fn topk_target(inventory: &PerComputationCandidates) -> usize { - inventory - .targets - .iter() - .position(|t| { - matches!( - inventory.aggregate(t).non_asap(), - Some(NonASAPOp::Aggregate { measures, .. }) - if matches!(measures.as_slice(), [AggIntent::TopK { .. }]) - ) - }) - .expect("a top-k target") - } - - /// How many whole-workload choices enumeration keeps: every digit over - /// its target's `choice_count`, less those [`absorbed_choice_varies`] - /// skips. - /// - /// [`absorbed_choice_varies`]: PerComputationCandidates::absorbed_choice_varies - fn enumerated_choices(inventory: &PerComputationCandidates) -> usize { - let mut enumerated = 0; - let mut choice = vec![0; inventory.targets.len()]; - loop { - if !inventory.absorbed_choice_varies(&choice) { - enumerated += 1; - } - let mut carry = true; - for (digit, target) in choice.iter_mut().zip(&inventory.targets).rev() { - *digit += 1; - if *digit < target.choice_count() { - carry = false; - break; - } - *digit = 0; - } - if carry { - return enumerated; - } - } - } - - /// Only raw data samples and plain sums of them: arithmetic, `rate` and other - /// functions end the requirement. - #[test] - fn raw_data_samples_of_metric_ends_at_any_other_operator() { - for (query, metric) in [ - ("sum_over_time(m[1m])", Some("m")), - ("sum by (job) (sum_over_time(m[1m]))", Some("m")), - ("sum_over_time(m[1m]) - 100", None), - ("-sum_over_time(m[1m])", None), - ("rate(m[1m])", None), - ("max_over_time(m[1m])", None), - ] { - let root = crate::test_support::lower_promql(query, AccuracyTarget::exact()); - assert_eq!( - raw_data_samples_of_metric(&root).as_deref(), - metric, - "{query}" - ); - } - } - - /// The target whose fused computation is a nested-sum merge. - fn nested_sum_target(inventory: &PerComputationCandidates) -> Option { - let merge = HowToComputeAggregateMeasure::ExactAccumulator(vec![ExactKind::Sum]); - inventory.targets.iter().position(|t| { - t.fused_computation - .as_ref() - .is_some_and(|fused| fused.ways_to_compute == [merge.clone()]) - }) - } - - /// The merge needs a sum over a sum's value: an outer sum over a rate, - /// an outer count, or an outer sum over an inner `max` gets none. - #[test] - fn nested_sum_merge_needs_a_sum_of_sums() { - for query in [ - "sum by (job) (rate(m[5m]))", - "count by (job) (sum_over_time(m[5m]))", - "sum by (job) (max_over_time(m[5m]))", - ] { - assert_eq!(nested_sum_target(&inventory(query)), None, "{query}"); - } - } - - /// A per-series sum drops the metric name, but the raw data samples keep it: - /// grouping the merge by `__name__` would answer the metric's name where - /// the nested sums answer none, so no merge is offered. - #[test] - fn nested_sum_merge_never_groups_by_the_dropped_metric_name() { - let query = "sum by (__name__) (sum_over_time(m[5m]))"; - assert_eq!(nested_sum_target(&inventory(query)), None); - } - - /// Merges do not stack: in `sum(sum by (job) (sum_over_time(m[5m])))` - /// a target with a fused computation is never absorbed, and `combinations` - /// counts exactly the choices enumeration keeps. - #[test] - fn nested_sum_merges_do_not_stack() { - let inventory = inventory("sum(sum by (job) (sum_over_time(m[5m])))"); - let absorbed: Vec = absorbed_targets(&inventory.targets).collect(); - assert_eq!(absorbed.len(), 1, "one merge"); - for &a in &absorbed { - assert!( - inventory.targets[a].fused_computation.is_none(), - "an absorbed target has a fused computation" - ); - } - let enumerated = enumerated_choices(&inventory); - assert_eq!(inventory.combinations(), enumerated); - } - - /// The shapes a heap over the raw data samples cannot answer do not get one: - /// `bottomk` stays a sort and limit (no top-k target), and a grouped sum - /// `without` labels or by the metric name (which the per-series sum drops) - /// gets no heap that absorbs the per-series sum and reads the samples. - #[test] - fn grouped_range_sums_a_raw_data_samples_heap_cannot_rank_get_no_fused_heap() { - let is_topk = |inventory: &PerComputationCandidates, t: &ComputationTarget| { - matches!( - inventory.aggregate(t).non_asap(), - Some(NonASAPOp::Aggregate { measures, .. }) - if matches!(measures.as_slice(), [AggIntent::TopK { .. }]) - ) - }; - let bottom = inventory("bottomk(3, sum by (region) (sum_over_time(m[1m])))"); - assert!( - !bottom.targets.iter().any(|t| is_topk(&bottom, t)), - "bottomk has no top-k target" - ); - for query in [ - "topk(3, sum without (instance) (sum_over_time(m[1m])))", - "topk(3, sum by (__name__) (sum_over_time(m[1m])))", - ] { - let inventory = inventory(query); - for target in inventory.targets.iter().filter(|t| is_topk(&inventory, t)) { - assert!( - target - .fused_computation - .as_ref() - .is_none_or(|f| f.absorbed_targets.len() == 1), - "{query}: {:?}", - target.fused_computation - ); - } - } - } - - /// A fused computation picked leaves every target beneath it uncomputed, - /// also one that an absorbed target's own merge absorbs: Pass 1 closes - /// `absorbed_targets` over those, so enumeration keeps only their first choice and - /// `combinations` still counts exactly the choices kept. Here the top-k - /// heap is made to absorb the grouped sum only, whose merge absorbs the - /// per-series sum. - #[test] - fn a_fused_computation_absorbs_what_its_absorbed_targets_merges_absorb() { - let mut inventory = inventory("topk(10, sum by (job) (sum_over_time(m[1m])))"); - let topk = topk_target(&inventory); - let fused = inventory.targets[topk] - .fused_computation - .as_mut() - .expect("a fused heap"); - let grouped = fused.absorbed_targets[0]; - fused.absorbed_targets.truncate(1); - let per_series = inventory.targets[grouped] - .fused_computation - .as_ref() - .expect("the grouped sum's merge") - .absorbed_targets[0]; - close_absorptions(&mut inventory.targets); - assert_eq!( - inventory.targets[topk] - .fused_computation - .as_ref() - .unwrap() - .absorbed_targets, - vec![grouped, per_series] - ); - assert_eq!(inventory.combinations(), enumerated_choices(&inventory)); - } - - /// `combinations` counts each choice once: picking a fused - /// whole-expression candidate with any but the first candidate of the - /// target it absorbs is the same candidate. An absorbed target with three - /// candidates (an approximate inner count: its accumulator, Count-Min and - /// UnivMon) gives 1 exact · 3 + 2 whole-expression = 5, not 3 · 3. - #[test] - fn combinations_skip_choices_a_whole_expression_candidate_absorbs() { - let inventory = inventory("topk by (job) (10, count_over_time(m[1m]))"); - let topk = topk_target(&inventory); - let target = &inventory.targets[topk]; - let Some(fused) = &target.fused_computation else { - panic!("a fused computation: {:?}", target.ways_to_compute) - }; - let inner = fused.absorbed_targets[0]; - let n = target.ways_to_compute.len(); - let whole = fused.ways_to_compute.len(); - let m = inventory.targets[inner].ways_to_compute.len(); - let enumerated = enumerated_choices(&inventory); - assert!(whole > 0 && m > 1, "{n} {whole} {m}"); - assert_eq!(inventory.combinations(), n * m + whole); - assert_eq!(inventory.combinations(), 5); - assert_eq!(inventory.combinations(), enumerated); - } - /// A Count-Min estimate has a bound only over weights proven /// non-negative: an open requirement (`RawDataSamplesOfMetric`) is not a proof. #[test] @@ -1655,31 +892,4 @@ mod tests { &query )); } - - /// Classic HLL's failure probability is left symbolic in a source's - /// distinct bound only for one instance per group over that source's - /// own rows (#693's scope condition): not over a join of two sources, - /// not over computed rows, and not for one Hydra structure shared by - /// every group, whose distinct items the source's bound does not bound. - #[test] - fn classic_hll_confidence_needs_one_instance_over_a_sources_own_rows() { - let hll = FieldDataType::Sketch; - let input = |query| crate::test_support::lower_promql(query, AccuracyTarget::exact()); - let guarantee = |family: &FieldDataType, query| { - source_distinct_guarantee(family, &SketchStatistic::Cardinality, &input(query)) - }; - let own = hll(SketchAlgorithm::Hll); - let symbolic = guarantee(&own, "a").expect("a source's own rows"); - assert_eq!( - symbolic.spec.failure_probability, - ProbabilityExpr::Unknown { - statistic: asap_accuracy::guarantee::hll::classic_failure_statistic(15, 0.05, "a") - } - ); - for (query, over) in [("a * on() b", "a join"), ("a * 2", "computed rows")] { - assert!(guarantee(&own, query).is_none(), "{over}: {query}"); - } - let hydra = hll(SketchAlgorithm::HydraHll); - assert!(guarantee(&hydra, "a").is_none()); - } } diff --git a/crates/stage1-pass1-per-computation-candidates/src/lib.rs b/crates/stage1-pass1-per-computation-candidates/src/lib.rs new file mode 100644 index 000000000..3cb11c46a --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/src/lib.rs @@ -0,0 +1,77 @@ +//! `asap-stage1-pass1-per-computation-candidates` — #509 Stage 1, Pass 1: +//! per-computation candidate generation and the summary realizations it +//! offers. Its one entry is [`pass1_memo`], which fills the +//! memo groups of Stage 0's [`Memo`](asap_types::stages::Memo) with their +//! initial candidates; Pass 2 extends that memo. +//! +//! It depends only on `asap-types` (its input and output memo are in +//! `asap_types::stages`) and the shared accuracy model (`asap-accuracy`). +//! It depends on no other stage crate, and the planner facade calls it +//! after Stage 0. It depends on no query-language frontend either; its own +//! tests lower PromQL through `asap-frontend-promql` (a dev-dependency). +//! The `test-support` feature exports the Pass 1 internals other crates' +//! tests call (`test_support`). +//! +//! Accuracy guarantees come from the built-in analytical accuracy rules in +//! `asap-accuracy` (per-family estimators, composition and budget +//! allocation). They derive a machine-readable +//! [`AccuracyGuarantee`](asap_types::accuracy::AccuracyGuarantee) +//! for every finalized value and propagate it through +//! approximate-over-approximate compositions under conservative rules (no +//! independence assumptions, unknown statistics stay unknown). A +//! composition with no rule leaves the guarantee `None` and keeps the +//! candidate. Pass 1 prunes nothing for accuracy; Pass 2 gives each readout +//! its required accuracy and eliminates the candidates no query can use, +//! with the deployment's measured accuracy (`AccuracyEvidence`) read before +//! each summary's theoretical guarantee. + +/// Stage 1, Pass 1's computation targets. No execution timing is assigned: that is a Stage 2 +/// materialization decision. Its target list +/// (`PerComputationCandidates`) is Pass 1's working form, public only to +/// tests (`crate::test_support`, feature `test-support`). +mod computation_targets; +/// The summary families that can serve an aggregate intent, the input a +/// summary consumes and the column a top-k ranks. +mod summary_realization; +/// Fixtures this crate's own tests share. +#[cfg(test)] +mod test_fixtures; +/// Test helpers other crates' tests call (feature `test-support`). +#[cfg(any(test, feature = "test-support"))] +pub mod test_support; +/// Frontend-to-Pass-1 acceptance tests over Pass 1's working form. +#[cfg(test)] +mod tests; + +use asap_types::deployment_capabilities::SupportedSummary; +use asap_types::stages::Memo; +use computation_targets::generate_per_computation_candidates; +pub use computation_targets::PerComputationCandidateError; + +/// Why [`pass1_memo`] failed. +#[derive(Debug, thiserror::Error)] +pub enum Pass1Error { + /// A query's DAG cannot be planned: it already holds ASAP or physical + /// annotations, or a measure's accuracy target is invalid. + #[error(transparent)] + PerComputation(#[from] PerComputationCandidateError), +} + +/// Stage 1, Pass 1: the initial candidates of the memo groups of `memo` +/// (Stage 0's, without candidates). It finds one computation target per +/// measure of each aggregate group with a realization besides exact +/// execution, drops the summaries the deployment does not support +/// (`supported_summaries`, the deployment's +/// `DeploymentCapabilities::supported_summaries`; `None` supports every +/// one), and adds each way to compute a group as candidates, through +/// `Memo::find_or_add_group` and `Memo::add_candidate`. Accuracy prunes +/// nothing here: Pass 2's dead-candidate elimination does. +pub fn pass1_memo( + memo: Memo, + supported_summaries: Option<&[SupportedSummary]>, +) -> Result { + let per_computation = generate_per_computation_candidates(&memo)? + .without_unsupported_summaries(supported_summaries); + let _ = (memo, per_computation); + todo!("#1207 PR 3: add each way to compute as candidates, one per listed θ") +} diff --git a/crates/logical-asap-optimization/src/pass1/realization.rs b/crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs similarity index 98% rename from crates/logical-asap-optimization/src/pass1/realization.rs rename to crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs index 5628f709f..9736265d2 100644 --- a/crates/logical-asap-optimization/src/pass1/realization.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs @@ -1,5 +1,5 @@ -//! Summary realization helpers shared by Pass 1 (`computation_targets`) -//! and Pass 2 (`asap_aware_cse`): which sketch kinds can serve an intent, +//! Summary realization helpers of Pass 1 (`computation_targets`): +//! which sketch kinds can serve an intent, //! the column/tuple a summary consumes, the column a top-k ranks, and the //! keyed-additive rule for a heap sketch that reads a larger sub-DAG. @@ -296,7 +296,7 @@ fn summed_per_series_samples(grouped: &OperatorNode) -> Option<(Rc #[cfg(test)] mod tests { use super::*; - use crate::test_support::metric_scan; + use crate::test_fixtures::metric_scan; use asap_types::ir::scalar::{CompareOpKind, ScalarValue}; use asap_types::ir::{ExprSemantics, Predicate}; diff --git a/crates/stage1-pass1-per-computation-candidates/src/test_fixtures.rs b/crates/stage1-pass1-per-computation-candidates/src/test_fixtures.rs new file mode 100644 index 000000000..2199f7894 --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/src/test_fixtures.rs @@ -0,0 +1,49 @@ +//! Fixtures this crate's own tests share. Every builder returns an +//! `Rc` whose schema is derived by `OperatorNode::new_shared`, +//! so a fixture is exactly what a front end would hand the planner. + +use std::rc::Rc; + +use asap_types::ir::operator::arguments::Source; +use asap_types::ir::schema::{ColumnId, DataType, Field, Schema}; +use asap_types::ir::{NonASAPOp, OperatorNode}; + +/// A `TimeSeries("m")` scan over `[ts(0), value(1), labels...]`, time index 0, +/// no unique key. +pub fn metric_scan(labels: &[&str]) -> Rc { + metric_scan_with_keys(labels, vec![]) +} + +/// [`metric_scan`] with explicit `unique_keys` (a `[[0]]` key makes CSE +/// willing to hoist the scan). +pub fn metric_scan_with_keys(labels: &[&str], unique_keys: Vec>) -> Rc { + let mut columns = vec![ + Field::plain("ts", DataType::Timestamp, false), + Field::plain("value", DataType::Float64, false), + ]; + columns.extend( + labels + .iter() + .map(|n| Field::plain(*n, DataType::Utf8, true)), + ); + scan("m", Schema::with_time_index(columns, 0, unique_keys)) +} + +/// A predicate-free `TimeSeries(metric)` scan with the given schema. +pub fn scan(metric: &str, schema: Schema) -> Rc { + scan_from( + Source::TimeSeries { + metric: metric.into(), + }, + schema, + ) +} + +pub fn scan_from(source: Source, schema: Schema) -> Rc { + OperatorNode::new_shared(asap_types::ir::Operator::NonASAP(NonASAPOp::Scan { + source, + predicates: vec![], + schema, + })) + .unwrap() +} diff --git a/crates/stage1-pass1-per-computation-candidates/src/test_support.rs b/crates/stage1-pass1-per-computation-candidates/src/test_support.rs new file mode 100644 index 000000000..0e3b166a7 --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/src/test_support.rs @@ -0,0 +1,4 @@ +//! The Pass 1 internals other crates' tests call (feature `test-support`): +//! Pass 1's working form and single-candidate composition. + +pub use crate::computation_targets::generate_per_computation_candidates; diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests.rs b/crates/stage1-pass1-per-computation-candidates/src/tests.rs new file mode 100644 index 000000000..0d20b156e --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/src/tests.rs @@ -0,0 +1,71 @@ +//! Frontend-to-Pass-1 acceptance: candidate discovery precedes empirical selection. +use crate::computation_targets::computation_candidates_for_intent; +use asap_types::ir::operator::AggIntent; +use asap_types::summary_type::SketchAlgorithm; + +use asap_types::stages::HowToComputeAggregateMeasure; + +fn candidates_for(intent: AggIntent) -> Vec { + computation_candidates_for_intent(&intent).candidates +} +fn algorithms(choices: &[HowToComputeAggregateMeasure]) -> Vec { + choices + .iter() + .filter_map(|choice| match choice { + HowToComputeAggregateMeasure::Summary(algorithm) => Some(*algorithm), + _ => None, + }) + .collect() +} + +/// Example 2 preserves specialized distinct summaries and the universal alternative. +#[test] +fn cardinality_keeps_exact_specialized_and_universal_candidates() { + let choices = candidates_for(AggIntent::Cardinality { cols: vec![0] }); + assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); + assert_eq!( + algorithms(&choices), + vec![ + SketchAlgorithm::Hll, + SketchAlgorithm::Kmv, + SketchAlgorithm::UnivMon + ] + ); + let tuple = candidates_for(AggIntent::Cardinality { cols: vec![0, 1] }); + assert!(!algorithms(&tuple).contains(&SketchAlgorithm::UnivMon)); +} + +/// Frequency moments retain exact execution and a universal sketch without certification. +#[test] +fn frequency_statistics_keep_universal_choices() { + for intent in [ + AggIntent::FrequencyL2 { col: Some(0) }, + AggIntent::FrequencyEntropy { col: Some(0) }, + ] { + let choices = candidates_for(intent); + assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); + assert_eq!(algorithms(&choices), vec![SketchAlgorithm::UnivMon]); + } +} + +/// TopK keeps both declared heap substrates without choosing an implementation. +#[test] +fn topk_keeps_both_specialized_heap_choices() { + let choices = candidates_for(AggIntent::TopK { k: 10 }); + assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); + assert_eq!( + algorithms(&choices), + vec![ + SketchAlgorithm::CmsWithHeap, + SketchAlgorithm::CountSketchWithHeap + ] + ); +} + +/// Summary candidates are unsized, so they do not depend on the requested error. +#[test] +fn summary_candidates_are_unsized() { + let loose = candidates_for(AggIntent::Count); + let tight = candidates_for(AggIntent::Count); + assert_eq!(loose, tight); +} diff --git a/crates/stage1-pass2-reuse-candidates/Cargo.toml b/crates/stage1-pass2-reuse-candidates/Cargo.toml new file mode 100644 index 000000000..430c48f0f --- /dev/null +++ b/crates/stage1-pass2-reuse-candidates/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "asap-stage1-pass2-reuse-candidates" +version = "0.1.0" +edition = "2021" + +# #509 Stage 1, Pass 2: the reuse rules over memo groups and the logical +# edges (`asap_types::stages::LogicalASAPMemoCandidates`) Stage 2 expands. +# Reads Pass 1's memo through `asap_types::stages`; depends on no other +# stage crate. +[dependencies] +asap-types = { path = "../types" } +# The deployment's measured accuracy (`AccuracyEvidence`) Pass 2 reads. +asap-accuracy = { path = "../accuracy" } +thiserror = "2" diff --git a/crates/stage1-pass2-reuse-candidates/src/lib.rs b/crates/stage1-pass2-reuse-candidates/src/lib.rs new file mode 100644 index 000000000..db7860446 --- /dev/null +++ b/crates/stage1-pass2-reuse-candidates/src/lib.rs @@ -0,0 +1,46 @@ +//! `asap-stage1-pass2-reuse-candidates` — #509 Stage 1, Pass 2: the reuse +//! rules over memo groups, the readouts' required accuracy, dead-candidate +//! elimination and the logical edges. Its entry, +//! [`generate_logical_asap_memo_candidates`], extends Pass 1's memo into +//! the [`LogicalASAPMemoCandidates`](asap_types::stages::LogicalASAPMemoCandidates) +//! Stage 2 expands, e.g. `sum by (job)` and `sum by (job, instance)` of one +//! count reading one state. +//! +//! It depends on `asap-types`, where its input and output are, and on +//! `asap-accuracy` for $\alpha^{\log}$. It depends on no other stage crate, +//! and the planner facade calls it after Pass 1. + +/// Steps 1, 2 and 5: the rules that add groups and candidates. +mod rules; + +use asap_accuracy::AccuracyEvidence; +use asap_types::stages::{LogicalASAPMemoCandidates, Memo}; +use asap_types::workload::QueryWorkloadEntry; +pub use rules::Pass2RuleError; +use rules::{rollup, topk}; + +/// Stage 1, Pass 2 (concepts doc, section 3, "Stage 1, Pass 2"), in order: +/// 1. rollup from the finest common group; +/// 2. top-k reuse; +/// 3. reach, caps and readout requirements; +/// 4. dead-candidate elimination; +/// 5. chain groups for the surviving state groups, then dead-candidate +/// elimination again over the memo with them; +/// 6. the logical edges between the surviving candidates, with +/// $\alpha^{\log}$ from `evidence` or the theoretical guarantee. +/// +/// `entries[i]` is query `i`'s workload entry (its evaluation grid). +pub fn generate_logical_asap_memo_candidates( + pass1: Memo, + entries: &[QueryWorkloadEntry], + evidence: &dyn AccuracyEvidence, +) -> Result { + let mut memo = pass1; + rollup::add_rollup_candidates(&mut memo)?; + topk::add_topk_candidates(&mut memo)?; + let _ = (memo, entries, evidence); + todo!( + "#1207 PR 4: steps 3-6: readout requirements, dead-candidate elimination, \ + chain groups (`rules::chains::add_chain_groups`) and the logical edges" + ) +} diff --git a/crates/logical-asap-optimization/src/pass2/memo/rules.rs b/crates/stage1-pass2-reuse-candidates/src/rules.rs similarity index 58% rename from crates/logical-asap-optimization/src/pass2/memo/rules.rs rename to crates/stage1-pass2-reuse-candidates/src/rules.rs index c9b38ed85..039b01b89 100644 --- a/crates/logical-asap-optimization/src/pass2/memo/rules.rs +++ b/crates/stage1-pass2-reuse-candidates/src/rules.rs @@ -1,10 +1,8 @@ -//! Pass 2's rules over groups (concepts doc, section 3): each reads the -//! memo and adds groups (`Memo::find_or_add_group`) or candidates -//! (`Memo::add_candidate`); none copies a consumer. -pub(crate) mod finer_aggregate; +//! Pass 2's rules over groups (concepts doc, section 3, "Stage 1, Pass 2"): +//! each reads the memo and adds groups (`Memo::find_or_add_group`) or +//! candidates (`Memo::add_candidate`); none copies a consumer. +pub(crate) mod chains; pub(crate) mod rollup; -pub(crate) mod scan_labels; -pub(crate) mod summary_inputs; pub(crate) mod topk; /// Why a Pass 2 rule failed on a memo. diff --git a/crates/stage1-pass2-reuse-candidates/src/rules/chains.rs b/crates/stage1-pass2-reuse-candidates/src/rules/chains.rs new file mode 100644 index 000000000..3b64862f2 --- /dev/null +++ b/crates/stage1-pass2-reuse-candidates/src/rules/chains.rs @@ -0,0 +1,26 @@ +//! Step 5, chain groups (concepts doc, section 3, "Chain groups"): a +//! `SummaryTumblingWindowChain[w](X)` group per width, and a `SummaryMerge` +//! over the `TimeRange` (and `TimeShift`s) over it as a candidate of the +//! summary state group. + +use std::collections::BTreeSet; + +use crate::rules::Pass2RuleError; +use asap_types::stages::{CandidateForMemoGroupId, Memo}; +use asap_types::workload::QueryWorkloadEntry; + +/// For each summary state group with a build that survived dead-candidate +/// elimination (not in `pruned`), a chain group and a merge candidate per +/// tumbling width $w$ from the gcd closure of the evaluation grids, ranges +/// and offsets of the queries that reach it and repeat on a known grid. +/// `entries[q]` is query `q`'s workload entry. +// Step 5 runs after dead-candidate elimination, which #1207 PR 4 adds. +#[allow(dead_code)] +pub(crate) fn add_chain_groups( + memo: &mut Memo, + entries: &[QueryWorkloadEntry], + pruned: &BTreeSet, +) -> Result<(), Pass2RuleError> { + let _ = (memo, entries, pruned); + todo!("#1207 PR 4: step 5, chain groups and the merges over them") +} diff --git a/crates/stage1-pass2-reuse-candidates/src/rules/rollup.rs b/crates/stage1-pass2-reuse-candidates/src/rules/rollup.rs new file mode 100644 index 000000000..b7676185a --- /dev/null +++ b/crates/stage1-pass2-reuse-candidates/src/rules/rollup.rs @@ -0,0 +1,18 @@ +//! Step 1, rollup from the finest common group (concepts doc, section 3): +//! a coarse aggregate group $G_c$ computed from a finer group $G_f$ of the +//! same definition, and per cluster of equal definitions one finest common +//! group $G^*$ every member can roll up from. + +use crate::rules::Pass2RuleError; +use asap_types::stages::Memo; + +/// Adds, to each aggregate group $G_c$, a candidate computing it from each +/// finer group $G_f$ of its cluster, after synthesizing each cluster's +/// finest common group. A cluster is the summary state groups (`SummaryAgg` +/// of a summary type whose states merge across groups) or exact `Aggregate` +/// groups (of sums, counts, minima and maxima) with equal definitions apart +/// from their keys and equal interval constraints (the time window). +pub(crate) fn add_rollup_candidates(memo: &mut Memo) -> Result<(), Pass2RuleError> { + let _ = memo; + todo!("#1207 PR 4: step 1, rollup from the finest common group") +} diff --git a/crates/stage1-pass2-reuse-candidates/src/rules/topk.rs b/crates/stage1-pass2-reuse-candidates/src/rules/topk.rs new file mode 100644 index 000000000..f90858eff --- /dev/null +++ b/crates/stage1-pass2-reuse-candidates/src/rules/topk.rs @@ -0,0 +1,14 @@ +//! Step 2, top-k reuse: an exact top-k reads a larger top-k of the same +//! input and partition, whose ranked rows hold its own. + +use crate::rules::Pass2RuleError; +use asap_types::stages::Memo; + +/// To each top-k group another top-k group over the same input group and +/// partition with the largest `k` serves, the candidate `TopK(k)` over that +/// group's ranked rows: the `k` highest of the `k_max` highest rows are the +/// `k` highest. Only exact ranked rows give the reuse its answer. +pub(crate) fn add_topk_candidates(memo: &mut Memo) -> Result<(), Pass2RuleError> { + let _ = memo; + todo!("#1207 PR 4: step 2, top-k reuse") +} diff --git a/crates/physical-asap-optimization/Cargo.toml b/crates/stage2-physical-optimization/Cargo.toml similarity index 90% rename from crates/physical-asap-optimization/Cargo.toml rename to crates/stage2-physical-optimization/Cargo.toml index dc4220f5e..db1f94888 100644 --- a/crates/physical-asap-optimization/Cargo.toml +++ b/crates/stage2-physical-optimization/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "asap-physical-asap-optimization" +name = "asap-stage2-physical-optimization" version = "0.1.0" edition = "2021" diff --git a/crates/physical-asap-optimization/src/catalog/mod.rs b/crates/stage2-physical-optimization/src/lib.rs similarity index 63% rename from crates/physical-asap-optimization/src/catalog/mod.rs rename to crates/stage2-physical-optimization/src/lib.rs index 391775557..5a504fc47 100644 --- a/crates/physical-asap-optimization/src/catalog/mod.rs +++ b/crates/stage2-physical-optimization/src/lib.rs @@ -1,9 +1,14 @@ -//! Stage 2's physical candidates: expand each logical candidate into one -//! physical candidate per valid $(\tau, \ell)$, and each logical edge -//! into the physical edges between the two candidates' alternatives -//! ([`generate_physical_asap_memo_candidates`]). The output type, -//! `PhysicalASAPMemoCandidates`, lives in `asap_types::stages`; Stage 3 -//! selects from it. +//! #509 Stage 2, physical ASAP-aware optimization (concepts doc, +//! section 3, "Stage 2: physical alternatives"). +//! +//! The planner facade calls [`generate_physical_asap_memo_candidates`] on +//! Pass 2's output (`asap_types::stages::LogicalASAPMemoCandidates`): each +//! logical candidate expanded into one physical candidate per valid +//! $(\tau, \ell)$, each logical edge into its physical edges with +//! $\alpha^{\log}$ and $\alpha^{\mathrm{phys}}$, and the pruned alternatives +//! (`asap_types::stages::PhysicalASAPMemoCandidates`). Stage 3 selects from +//! that output and builds the plan. The crate depends on no other stage +//! crate. use asap_types::deployment_capabilities::DeploymentCapabilities; use asap_types::stages::{LogicalASAPMemoCandidates, PhysicalASAPMemoCandidates}; diff --git a/crates/plan-selection/Cargo.toml b/crates/stage3-plan-selection/Cargo.toml similarity index 95% rename from crates/plan-selection/Cargo.toml rename to crates/stage3-plan-selection/Cargo.toml index ab85b889e..22f140ef0 100644 --- a/crates/plan-selection/Cargo.toml +++ b/crates/stage3-plan-selection/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "asap-plan-selection" +name = "asap-stage3-plan-selection" version = "0.1.0" edition = "2021" diff --git a/crates/plan-selection/src/select.rs b/crates/stage3-plan-selection/src/lib.rs similarity index 52% rename from crates/plan-selection/src/select.rs rename to crates/stage3-plan-selection/src/lib.rs index 8eff2f98e..2410b88a5 100644 --- a/crates/plan-selection/src/select.rs +++ b/crates/stage3-plan-selection/src/lib.rs @@ -1,14 +1,29 @@ -//! Stage 3, plan selection: [`select_plan`] builds the selection MILP over -//! Stage 2's physical candidates and admissible edges -//! ([`crate::milp::model`]), solves it, and builds the plan from the -//! selected executions as its last step. +//! #509 Stage 3, plan selection (concepts doc +//! `memo-groups-properties-requirements.md`, section 3, "Stage 3: baseline +//! selection and realization", and sections 4 and 5). +//! +//! [`select_plan`] reads Stage 2's physical candidates $\mathcal C$ and the +//! admissible part of the physical edges $\mathcal E$, selects with a MILP +//! over $x_v$, $y_{u,c,i}$, $z_{q,v}$ and $t_v$ (constraints (A)–(I); +//! (G) and (H) hold because $y$ exists only on admissible edges), and +//! builds the plan (`PhysicalASAPDAG`) from $\{x = 1\}$ and $\{y = 1\}$ +//! as its last step. The extensions add execution contexts $\kappa$ with $x^{\mathrm{mat}}_v$, +//! $x_{\kappa,v}$, $y_{\kappa,u,c,i}$ and the retention amount $h_v$ +//! (section 5), and accuracy at each query root, constraint (K), with +//! per-candidate error bounds $E_c$ and $D_c$ (section 4). Costs come from +//! `asap-cost`. + +mod milp; +mod report; use asap_cost::CostInputs; use asap_types::plan::physical_asap_dag::PhysicalASAPDAG; use asap_types::stages::PhysicalASAPMemoCandidates; use asap_types::workload::{DataWorkload, QueryWorkloadEntry}; -use crate::report::{ErrorSelectingPlan, Selection}; +pub use report::{ + large_peak_memory_warning, AcceptedAccuracy, ErrorSelectingPlan, RejectionCause, Selection, +}; /// Stage 3, plan selection: select one plan among `physical`'s candidates /// (module documentation) under `cost_inputs`, and build it: one diff --git a/crates/plan-selection/src/milp/mod.rs b/crates/stage3-plan-selection/src/milp/mod.rs similarity index 100% rename from crates/plan-selection/src/milp/mod.rs rename to crates/stage3-plan-selection/src/milp/mod.rs diff --git a/crates/plan-selection/src/milp/model.rs b/crates/stage3-plan-selection/src/milp/model.rs similarity index 100% rename from crates/plan-selection/src/milp/model.rs rename to crates/stage3-plan-selection/src/milp/model.rs diff --git a/crates/plan-selection/src/report.rs b/crates/stage3-plan-selection/src/report.rs similarity index 100% rename from crates/plan-selection/src/report.rs rename to crates/stage3-plan-selection/src/report.rs diff --git a/crates/plan-selection/tests/cost_inputs_json.rs b/crates/stage3-plan-selection/tests/cost_inputs_json.rs similarity index 100% rename from crates/plan-selection/tests/cost_inputs_json.rs rename to crates/stage3-plan-selection/tests/cost_inputs_json.rs diff --git a/crates/types/src/ir/schema/series_identity.rs b/crates/types/src/ir/schema/series_identity.rs index 61bc53e69..94e997390 100644 --- a/crates/types/src/ir/schema/series_identity.rs +++ b/crates/types/src/ir/schema/series_identity.rs @@ -64,7 +64,7 @@ pub fn with_promql_series_identity( // A series has at most one sample per timestamp, so the full // identity and the timestamp key each row. Pass 2's // identical-expression rule reads this key: only a keyed - // node is legal to share (hash-consing, `Memo::find_or_add_group`). + // node is legal to share (Stage 0 hash-consing, `cse` in `asap_stage0_memo`). if let Some(time) = schema.time_index { schema.add_unique_key(vec![schema.fields.len() - 1, time]); } diff --git a/crates/types/src/test_support.rs b/crates/types/src/test_support.rs index 202323407..3b3a314ae 100644 --- a/crates/types/src/test_support.rs +++ b/crates/types/src/test_support.rs @@ -1,7 +1,8 @@ //! Helpers that only tests call (this crate's integration tests and other //! crates' tests), exposed under the `test-support` feature so the normal //! public API stays as narrow as its production users need. Each forwards -//! to the crate-private function of the same name. +//! to the crate-private function of the same name, except the fixture +//! [`population_over_selector`], which the executor's tests build. use crate::ir::operator::maintained_population::CurrentSeriesInput; use crate::ir::operator::node::Operator; @@ -73,3 +74,75 @@ pub fn physical_asap_dag_at_query_time( .0, ) } + +/// The maintained-population sub-DAG for executor tests: `root` (below its +/// projections, which are kept) replaced by `EvaluatePopulation(statistic)` +/// over a current-series population of the single selector under it, +/// grouped by `grouping`, with no matchers. The caller states the statistic +/// and grouping; nothing is recognized. No planner pass offers this sub-DAG +/// yet (#681). +pub fn population_over_selector( + root: &Rc, + statistic: crate::ir::operator::maintained_population::PopulationStatistic, + grouping: &[&str], +) -> Rc { + use crate::ir::operator::arguments::Source; + use crate::ir::operator::maintained_population::*; + if let Some(NonASAPOp::Project { + cols, + qualifier, + child, + }) = root.non_asap() + { + let child = population_over_selector(child, statistic.clone(), grouping); + let project = Operator::NonASAP(NonASAPOp::Project { + cols: cols.clone(), + qualifier: qualifier.clone(), + child, + }); + return Rc::new(OperatorNode::with_schema(project, root.schema.clone())); + } + let selectors: Vec<_> = OperatorNode::reachable(root) + .into_iter() + .filter(|node| matches!(node.non_asap(), Some(NonASAPOp::TimeRange { .. }))) + .collect(); + let [selector] = selectors.as_slice() else { + panic!("one selector under {root:?}"); + }; + let Some(NonASAPOp::TimeRange { range, child, .. }) = selector.non_asap() else { + unreachable!() + }; + let Some(NonASAPOp::Scan { + source: Source::TimeSeries { metric }, + .. + }) = child.non_asap() + else { + panic!("a time-series selector, got {child:?}"); + }; + let population = MaintainedPopulation { + input: PopulationInput::CurrentSeries(CurrentSeriesInput { + metric: metric.clone(), + matchers: Vec::new(), + grouping: grouping.iter().map(|label| label.to_string()).collect(), + without: false, + lookback_ms: range.as_millis() as u64, + }), + max_k: match statistic { + PopulationStatistic::TopK { k } => k, + _ => 0, + }, + quantiles: matches!(statistic, PopulationStatistic::Quantile { .. }), + }; + let maintained = OperatorNode::with_schema( + Operator::ASAP(ASAPOp::MaintainPopulation { + child: selector.clone(), + population, + }), + selector.schema.clone(), + ); + let evaluation = Operator::ASAP(ASAPOp::EvaluatePopulation { + child: Rc::new(maintained), + evaluation: statistic, + }); + Rc::new(OperatorNode::with_schema(evaluation, root.schema.clone())) +} diff --git a/crates/types/tests/planner_vocabulary.rs b/crates/types/tests/planner_vocabulary.rs index 8a0c14a38..11f37f648 100644 --- a/crates/types/tests/planner_vocabulary.rs +++ b/crates/types/tests/planner_vocabulary.rs @@ -1,7 +1,7 @@ use asap_types::plan::physical_asap_dag::WindowEdgeCompatibility; // The renamed window-edge compatibility still reads and emits the deployed -// wire value. (Tumbling-window coverage names are checked in physical-asap-optimization.) +// wire value. (Tumbling-window coverage names are checked in asap-stage2-physical-optimization.) #[test] fn window_edge_compatibility_names_preserve_wire_values() { let compatibility = diff --git a/docs/design_docs/architecture/README.md b/docs/design_docs/architecture/README.md index f714afc1f..a521d7e3f 100644 --- a/docs/design_docs/architecture/README.md +++ b/docs/design_docs/architecture/README.md @@ -45,9 +45,10 @@ target. | Shared IR | `asap-types` | The unified operator IR (`ir`: one `OperatorNode` before and after ASAP optimization), schemas, workloads, guarantees, and exported plan data | | Front-end common | `frontend-common` | Name-based `UnresolvedOp` tree shared by the front ends, and `resolve_root` into the operator IR | | Query frontends | `frontend-sql`, `frontend-promql`, `frontend-metricsql` | Stage 0: parse source languages and produce canonical Pre-ASAP queries | -| Logical ASAP-aware optimization | `logical-asap-optimization` | Stage 1: per-computation candidates (Pass 1), ASAP-aware CSE (Pass 2), the analytical accuracy model | -| Physical ASAP-aware optimization | `physical-asap-optimization` | Stage 2: materialization and physical operator implementation | -| Plan selection | `plan-selection` | Stage 3: accuracy and latency checks, costing and selection; the planning models and the Stage 1 to Stage 3 driver | +| Stage 0 hash-consing | `stage0-memo` | The memo groups of the workload's query roots | +| Logical ASAP-aware optimization | `stage1-pass1-per-computation-candidates`, `stage1-pass2-reuse-candidates` | Stage 1: per-computation candidates (Pass 1), ASAP-aware CSE (Pass 2) | +| Physical ASAP-aware optimization | `stage2-physical-optimization` | Stage 2: materialization and physical operator implementation | +| Plan selection | `stage3-plan-selection` | Stage 3: accuracy and latency checks, costing and selection; the planning models and the Stage 1 to Stage 3 driver | | Planner facade | `planner` | `e2e_plan`: Stage 0 followed by Stages 1–3 | | Executor | `executor` | Stage 4: runs a `PhysicalASAPDAG` over `asap_sketchlib` summaries; no stage crate depends on it | | Developer inspection | `devtools` | `asap_planner` and the Stage Viewer documents, corpus coverage tools | diff --git a/docs/design_docs/architecture/updated_interface_with_pluggable_optimization.md b/docs/design_docs/architecture/updated_interface_with_pluggable_optimization.md index dfc46531b..f7fb57d5b 100644 --- a/docs/design_docs/architecture/updated_interface_with_pluggable_optimization.md +++ b/docs/design_docs/architecture/updated_interface_with_pluggable_optimization.md @@ -233,14 +233,16 @@ pass no longer runs these steps; another pass need not run any of them. | Crate | What it holds | |---|---| | `asap-types` | `ParsedWorkload` | -| `asap-plan-selection` | Stage 3: `select_plan`, `Selection` | +| `asap-stage3-plan-selection` | Stage 3: `select_plan`, `Selection` | | `asap-planner` *(new)* | `e2e_plan`, `UserInput`, `FrontendInput`, lowering dispatch; `OptimizationPass`, `OptimizationInput`, `PlanOutput`, `PlanningModels`, `optimize`, `PassRegistry`, `Stage1ToStage3Pass`, `run_planning` | ```text asap-planner ──┬──> asap-frontend-{sql, promql, metricsql} - ├──> asap-logical-asap-optimization ──> asap-types - ├──> asap-physical-asap-optimization ──> asap-types - └──> asap-plan-selection ──> asap-types, asap-cost, asap-accuracy + ├──> asap-stage0-memo ──> asap-types + ├──> asap-stage1-pass1-per-computation-candidates ──> asap-types, asap-accuracy + ├──> asap-stage1-pass2-reuse-candidates ──> asap-types + ├──> asap-stage2-physical-optimization ──> asap-types + └──> asap-stage3-plan-selection ──> asap-types, asap-cost, asap-accuracy ``` `asap-planner` is separate because it is the only crate depending on every diff --git a/docs/design_docs/decisions/concat-unique-keys.md b/docs/design_docs/decisions/concat-unique-keys.md index 4820d2185..4e18cd28f 100644 --- a/docs/design_docs/decisions/concat-unique-keys.md +++ b/docs/design_docs/decisions/concat-unique-keys.md @@ -75,7 +75,7 @@ Both current `Concat`-constructing call sites, and every consumer of test fixtures) — none of them builds a fresh `Concat` with a `Dedup` on top that this feature could remove. - **Every consumer of `Schema::unique_keys`** in the DAG, to check for a - cost beyond "a literal `Dedup` node": `share_common_sub_dags` (crate-private in `asap_logical_asap_optimization`, `stage0/cse.rs`) + cost beyond "a literal `Dedup` node": `share_common_sub_dags` (crate-private in `asap_stage0_memo`, `cse.rs`) (gates CSE producer-sharing on `Schema::has_unique_key()`) and `asap_aware_mapping::rollup::is_legal_rollup_source` (gates rollup-source legality the same way, on an *`Aggregate`'s* own output schema). Neither diff --git a/docs/design_docs/decisions/cse-cost-model.md b/docs/design_docs/decisions/cse-cost-model.md index b7a87edba..45d757f58 100644 --- a/docs/design_docs/decisions/cse-cost-model.md +++ b/docs/design_docs/decisions/cse-cost-model.md @@ -16,7 +16,7 @@ elimination) to identify eligible, structurally identical computations. A shared logical node records an opportunity for reuse; selecting maintained state or independent execution is a separate planning decision. -[`share_common_sub_dags`](../../../crates/logical-asap-optimization/src/stage0/cse.rs) +[`share_common_sub_dags`](../../../crates/stage0-memo/src/cse.rs) (issue #223 stages 1-2, PR #235) already *detects* every structurally-identical, legally-shareable (`Schema::unique_keys`-gated) sub-DAG and shares it **unconditionally** — there is no cost gate on top of legality. This document diff --git a/docs/design_docs/proposals/asap-primitive-schema.md b/docs/design_docs/proposals/asap-primitive-schema.md index a6b298c5f..e0a25e1a3 100644 --- a/docs/design_docs/proposals/asap-primitive-schema.md +++ b/docs/design_docs/proposals/asap-primitive-schema.md @@ -94,7 +94,7 @@ Based on our requirement, each field should contain the following information. | `FrequencyL2`, `FrequencyEntropy` | `Sketch`: `UnivMon` | `SummaryEstimate(FrequencyL2 \| FrequencyEntropy)` | | `Sum`, `Count`, `Min`, `Max`, `Rate`, `IRate`, `Increase` (exact) | `ExactAggregate(ExactKind, …)` | `FinalizeExactAccumulator` | - The sketch candidates are `summary_candidates(intent)` in `crates/logical-asap-optimization/src/pass1/realization.rs`; exact accumulators come from Pass 1's `ExactAccumulator` candidates in `pass1/computation_targets.rs`; the evaluations are `SketchStatistic` ([§6.5](#65-update-input-and-evaluations-summary_typestatisticrs-iroperatormaintained_populationrs)). + The sketch candidates are `summary_candidates(intent)` in `crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs`; exact accumulators come from Pass 1's `ExactAccumulator` candidates in `computation_targets.rs`; the evaluations are `SketchStatistic` ([§6.5](#65-update-input-and-evaluations-summary_typestatisticrs-iroperatormaintained_populationrs)). - **Time window aggregation intents**: whether states built over smaller windows can answer a larger one. This depends on how the family combines states: - **Merge** (`SummaryMerge`, §5.6): states over disjoint tumbling windows combine into the state of their union, e.g. two 1-minute KLL states answer a 2-minute quantile. Requires a mergeable family. @@ -1212,7 +1212,7 @@ This part of the code answers two questions about summary state: 1. **Update input** (`SummaryUpdate`): when a `SummaryAgg` reads one input row, what does it add to the state? It adds a **weight**, optionally under an **item** key. 2. **Evaluations**: once the state is built, what can be asked of it? `SketchStatistic` is what `SummaryEstimate` asks a sketch (§5.2). `MaintainedPopulation` and `PopulationStatistic` are the exact-population counterpart, used by `MaintainPopulation` and `EvaluatePopulation` (§5.4, §5.5). -**Update input examples** (as the planner builds them in Stage 1, `asap-logical-asap-optimization`): +**Update input examples** (as the planner builds them in Stage 1, `asap-stage1-pass1-per-computation-candidates`): | Query | Sketch | `item` | `weight` | `weight_domain` | |---|---|---|---|---| diff --git a/docs/design_docs/proposals/joint-planning-implementation-plan.md b/docs/design_docs/proposals/joint-planning-implementation-plan.md index a6cb40d31..30fa4bfca 100644 --- a/docs/design_docs/proposals/joint-planning-implementation-plan.md +++ b/docs/design_docs/proposals/joint-planning-implementation-plan.md @@ -12,14 +12,14 @@ Preserve supported accuracy semantics, physical eligibility, cost objectives, sc | Scope | Current implementation | Responsibility | | --- | --- | --- | -| Logical identity | `logical-asap-optimization/src/stage0.rs`; `types/src/stages/` | `DagOfLogicalMemoGroups`, `MemoGroup` (`asap_types::stages`; built by `memo_of_queries`), stable initial query/group references. | -| Computation and sharing rules | `logical-asap-optimization/src/pass2/memo/{candidates,rules,state_groups,shared_configurations,window_candidates}` | Populate groups, retain local candidates, expose shared states and compatible rewrites. | -| Physical legality | `physical-asap-optimization` | Executable operators, timing and materialization eligibility. | -| Candidate dependency inventory | `physical-asap-optimization/src/catalog`; `types/src/stages/physical` | Local `PhysicalCandidate`, `ProducerRequirement` (`asap_types::stages`), compatible producers, structural pruning; Stage 3 builds the selected plan (`PhysicalASAPDAG`) directly. Stage 2 makes no execution-scope copies; today's Stage 3 engine makes its own (`plan-selection/src/search/candidates/scopes.rs`). | -| Solver | `plan-selection/src/search/milp` | Activation, producer/root assignment, reachability, acyclicity, resource constraints, and solver warm starts. | -| Search and validation | `plan-selection/src/search/refinement` | Actual evaluator checks, sound cuts, objective-specific ranking, and certified component splitting. | -| Pricing support | `plan-selection/src/search/costing` | Certified local bounds and consistent calibration. Production execution demand is owned by `cost/src/plan/execution_demand.rs`; the search demand reference is test-only. | -| Pipeline and lifecycle | `plan-selection/src/search/{pipeline,route}` | Initial groups, generation accounting, seed/full search budgets, archives, reports, and selected workload outputs. | +| Logical identity | `stage0-memo/src/lib.rs`; `types/src/stages/` | `DagOfLogicalMemoGroups`, `MemoGroup` (`asap_types::stages`; built by `memo_of_queries`), stable initial query/group references. | +| Computation and sharing rules | `stage1-pass2-reuse-candidates/src/{lib.rs,rules.rs,rules/}` | Populate groups, retain local candidates, expose shared states and compatible rewrites. | +| Physical legality | `stage2-physical-optimization` | Executable operators, timing and materialization eligibility. | +| Candidate dependency inventory | `stage2-physical-optimization/src/lib.rs`; `types/src/stages/physical` | Local `PhysicalCandidate`, `ProducerRequirement` (`asap_types::stages`), compatible producers, structural pruning; Stage 3 builds the selected plan (`PhysicalASAPDAG`) directly. Stage 2 makes no execution-scope copies; today's Stage 3 engine makes its own (`stage3-plan-selection/src/search/candidates/scopes.rs`). | +| Solver | `stage3-plan-selection/src/search/milp` | Activation, producer/root assignment, reachability, acyclicity, resource constraints, and solver warm starts. | +| Search and validation | `stage3-plan-selection/src/search/refinement` | Actual evaluator checks, sound cuts, objective-specific ranking, and certified component splitting. | +| Pricing support | `stage3-plan-selection/src/search/costing` | Certified local bounds and consistent calibration. Production execution demand is owned by `cost/src/plan/execution_demand.rs`; the search demand reference is test-only. | +| Pipeline and lifecycle | `stage3-plan-selection/src/search/{pipeline,route}` | Initial groups, generation accounting, seed/full search budgets, archives, reports, and selected workload outputs. | `PhysicalCandidate` is a local selectable computation; the plan (`PhysicalASAPDAG`) is the complete workload DAG Stage 3 builds; they are not interchangeable. Physical candidate configuration in selection invokes the authoritative Stage 2 legality code rather than duplicating its rules. Logical rules do not depend on the solver crate. diff --git a/docs/design_docs/proposals/joint-planning-search.md b/docs/design_docs/proposals/joint-planning-search.md index 2558a5341..937f21269 100644 --- a/docs/design_docs/proposals/joint-planning-search.md +++ b/docs/design_docs/proposals/joint-planning-search.md @@ -632,7 +632,7 @@ After selection, the planner reconstructs the DAG and evaluates accuracy, latenc The implementation uses `DagOfLogicalMemoGroups` and `MemoGroup` for initial identities, and `Memo` / `CandidateForMemoGroup` for logical expansion. Local `PhysicalCandidate` choices have explicit producer requirements and compatible connections. Selection reconstructs a `PhysicalWorkloadPlan` and validates its resulting graph through the configured evaluators. The sole production engine is `CandidateConnections`; bounded and exhaustive modes use the same candidate representation and solver. Existing supported runtime operators determine which configurations can be generated. -The candidate memo and its Pass 2 rules belong in `logical-asap-optimization`; physical eligibility remains authoritative in `physical-asap-optimization`. Within selection, candidate inventory/reconstruction, MILP construction, evaluator refinement, pricing support, and route orchestration have separate scopes. State-local choices belong in candidates; cross-candidate decisions use connections and constraints. The retired `CouplingSite` selector representation and legacy search routes are removed rather than retained under new names. +The candidate memo and its Pass 2 rules belong in `stage1-pass2-reuse-candidates`; physical eligibility remains authoritative in `stage2-physical-optimization`. Within selection, candidate inventory/reconstruction, MILP construction, evaluator refinement, pricing support, and route orchestration have separate scopes. State-local choices belong in candidates; cross-candidate decisions use connections and constraints. The retired `CouplingSite` selector representation and legacy search routes are removed rather than retained under new names. Evaluation must distinguish generation coverage from selection correctness. Small workloads are exhaustively enumerated over candidate subsets and compatible connections under the same inventory, then compared with MILP results. Cases include multiple selected candidates in one group, shared build costs, separate execution scopes, fusion outputs, and composed accuracy/resource requirements. Scaling experiments measure candidate and connection counts, generation and solve time, planner memory, and validated execution savings. Together these measurements establish whether the representation avoids repeated search work and whether joint selection justifies its planning cost. diff --git a/docs/design_docs/proposals/planner-layering-example2-acceptance.md b/docs/design_docs/proposals/planner-layering-example2-acceptance.md index 0ec29bd09..b0d35a810 100644 --- a/docs/design_docs/proposals/planner-layering-example2-acceptance.md +++ b/docs/design_docs/proposals/planner-layering-example2-acceptance.md @@ -10,7 +10,7 @@ several computations". Tests: This spec was written by a test designer who does not implement the stages. Tests run the stages through `planner_layering_common::run_stages`: Pass 1 and composition, `optimize_physical_asap` and the whole-workload reference -pricer (`asap_plan_selection::reference_pricer::select_among_plans`). A test that +pricer (`asap_stage3_plan_selection::reference_pricer::select_among_plans`). A test that needs a missing feature is `#[ignore]`d with the PR that delivers it. ## Workload diff --git a/docs/design_docs/proposals/planner-layering.md b/docs/design_docs/proposals/planner-layering.md index 18ac149bb..52bd0b1ba 100644 --- a/docs/design_docs/proposals/planner-layering.md +++ b/docs/design_docs/proposals/planner-layering.md @@ -282,7 +282,7 @@ one. It makes no implementation choice, so this section counts it as Stage 0 (its output); the code runs it as Stage 1 starts, which is why [Stage inputs and outputs](#stage-inputs-and-outputs-whole-workload-candidates-and-memo) lists `memo_of_queries` with Pass 1. `memo_of_queries` runs -`share_common_sub_dags` (`crates/logical-asap-optimization/src/stage0/cse.rs`) over the frontends' +`share_common_sub_dags` (`crates/stage0-memo/src/cse.rs`) over the frontends' roots and numbers the shared nodes as groups. Two structurally equal nodes become one group only when sharing them is legal, that is, when every reader of the shared node reads the rows it would read alone. Equal nodes are @@ -513,20 +513,20 @@ full tumbling-window-width domain, with no time limit. #### Memo code interface -The memo rules are in `crates/logical-asap-optimization/src/` (module -`pass2::memo`, crate-private: the crate root re-exports each entry point); the memo types Stage 1 hands Stage 2 are in +The memo rules are in `crates/stage1-pass2-reuse-candidates/src/` (module +`memo`, crate-private: the crate root re-exports each entry point); the memo types Stage 1 hands Stage 2 are in `crates/types/src/stages/` (`asap_types::stages`); the facade that runs the stages is in `crates/planner/src/run.rs`; the search over Stage 2's -candidates is in `crates/plan-selection/src/` (`select.rs`, `groups/`, `milp/`). +candidates is in `crates/stage3-plan-selection/src/` (`lib.rs`, `groups/`, `milp/`). | Step | Entry point | Path | |---|---|---| | Stage 0 | `memo_of_queries` → `DagOfLogicalMemoGroups`, `MemoGroup`, `MemoGroupId` | `stage0.rs` (the types: `asap_types::stages`); hash-consing is `share_common_sub_dags` in `stage0/cse.rs` | -| Pass 1 | `pass1_memo` → `PerComputationLogicalMemoCandidates` (its `Memo` and its `PrunedCandidate`s; `ComputationTarget` is Pass 1's working type, in `asap_types::stages`), the one entry: inside it, the computation targets (walking the memo groups), the summaries the deployment does not support and those no query can use pruned, the candidates attached to the groups (`try_populate_pass1`), then the accuracy-scoped sizes | `pass1.rs`; `pass1/computation_targets.rs`; `pass1/memo_population.rs` | +| Pass 1 | `pass1_memo` → `PerComputationLogicalMemoCandidates` (its `Memo` and its `PrunedCandidate`s; `ComputationTarget` is Pass 1's working type, in `asap_types::stages`), the one entry: inside it, the computation targets (walking the memo groups), the summaries the deployment does not support and those no query can use pruned, the candidates attached to the groups (`try_populate_pass1`), then the accuracy-scoped sizes | `stage1-pass1-per-computation-candidates/src/lib.rs`; `computation_targets.rs`; `pass1/memo_population.rs` | | Memo types | `DagOfLogicalMemoGroups`, `PerComputationLogicalMemoCandidates`, `HowToComputeAggregateMeasure`, Pass 1's working types (`ComputationTarget`, `FusedComputation`, `HavingEntry`, `HavingPlacement`), `Memo`, `CandidateForMemoGroup`, `OriginOfCandidateForMemoGroup`, `LogicalASAPMemoCandidates`, `CandidateGenerationTimeout`, `root_groups`, `queries_rooted_at` | `crates/types/src/stages/` (`asap_types::stages`) | -| Pass 2 | `generate_logical_asap_memo_candidates` → `LogicalASAPMemoCandidates`, from Pass 1's output. It calls in this order: 1. window composition for every legal tumbling-window width (`add_local_window_composition`); 2–9. the rules in `pass2/memo/rules/`: scan widening, summary inputs, top-k reuse, finer aggregate, rollup, window rollup, summary results, state configurations; 10. `add_shared_summary_state_groups`, the shared builds | `pass2.rs` (`LogicalASAPMemoCandidates` itself: `asap_types::stages`); `pass2/memo/window_candidates.rs`, `pass2/memo/rules/`, `pass2/memo/state_groups.rs`, `pass2/memo/shared_configurations.rs` | +| Pass 2 | `generate_logical_asap_memo_candidates` → `LogicalASAPMemoCandidates`, from Pass 1's output. It calls in this order: 1. window composition for every legal tumbling-window width (`add_local_window_composition`); 2–9. the rules in `pass2/memo/rules/`: scan widening, summary inputs, top-k reuse, finer aggregate, rollup, window rollup, summary results, state configurations; 10. `add_shared_summary_state_groups`, the shared builds | `stage1-pass2-reuse-candidates/src/lib.rs` (`LogicalASAPMemoCandidates` itself: `asap_types::stages`); `pass2/memo/window_candidates.rs`, `pass2/memo/rules/`, `pass2/memo/state_groups.rs`, `pass2/memo/shared_configurations.rs` | | Memo to candidate DAGs | `enumerate`, `build_logical_asap_dags_from_chosen_candidates`, `ChosenCandidatePerMemoGroup`, `AllChosenCandidatesPerMemoGroup`, `ErrorBuildingLogicalASAPDagsFromChosenCandidates` | `pass2/memo/enumeration.rs` (re-exported at the crate root) | -| Production memo build and search | The facade's `run_planning` builds the DAG of logical memo groups and runs Pass 1 (`pass1_memo`) once; then `generate_logical_asap_memo_candidates`, `generate_physical_asap_memo_candidates` and Stage 3's `select_plan`, once each; `select_plan` builds the plan. Behind `select_plan`: the group selection MILP (#1095), `groups/` and `milp/` | `crates/planner/src/run.rs`; `crates/plan-selection/src/select.rs` | +| Production memo build and search | The facade's `run_planning` builds the DAG of logical memo groups and runs Pass 1 (`pass1_memo`) once; then `generate_logical_asap_memo_candidates`, `generate_physical_asap_memo_candidates` and Stage 3's `select_plan`, once each; `select_plan` builds the plan. Behind `select_plan`: the group selection MILP (#1095), `groups/` and `milp/` | `crates/planner/src/run.rs`; `crates/stage3-plan-selection/src/lib.rs` | ## ASAPPlanner Detailed Design: Planning Stages and their decisions/Strategies @@ -598,8 +598,8 @@ the memo path's entry points. | 1, Pass 1 | Logical roots; the deployment's supported summaries → the Pass 1 inventory, every computation's candidates (`PerComputationCandidates`, now Pass 1's crate-private working form) | Logical roots → `DagOfLogicalMemoGroups` (hash-consed `MemoGroup`s); with the Pass 1 inventory, less the summaries the deployment does not support and those no query reading them can use → `PerComputationLogicalMemoCandidates`: the `Memo` (each group's `CandidateForMemoGroup`s, with the accuracy-scoped sizes) and the pruned candidates (`PrunedCandidate`) | `memo_of_queries`, `pass1_memo` | | 1, Pass 2 | One Pass 1 choice per computation → that choice rewritten by each sharing rule, every subset of sharing choices (no longer in the code) | `Memo`; the entries' recurrence and range steps → the same memo with each rule's candidates added to the groups they implement | the memo rules (`pass2/memo/rules/`), `pass2::memo::window_candidates` | | 1, concrete summary-state groups | (part of Pass 2) | `Memo` → the memo with concrete summary-state groups: one group per shared size or tumbling-window layout that readers can read | `add_shared_summary_state_groups`, Pass 2's last step; the Pass 2 output is `LogicalASAPMemoCandidates` (`generate_logical_asap_memo_candidates`) | -| 2 | One whole-workload logical candidate; entries (recurrence, predictability), `DataWorkload`, query-time retention → its physical candidates, one per physical properties assignment | `LogicalASAPMemoCandidates`; entries, `DataWorkload`, query-time and raw-data retention → `PhysicalASAPMemoCandidates`: every operator node of every candidate with each allowed timing and lifetime (one physical candidate each, no copies), the producers of each input, reader constraints (each applied to every selected run of its candidate), and the pruned candidates (`PrunedCandidate`) | `generate_physical_asap_memo_candidates` (`asap_physical_asap_optimization`) | -| 3 | Every physical candidate; accuracy targets, accuracy model and evidence, cost model → one plan | `PhysicalASAPMemoCandidates`; entries, `DataWorkload`, `AccuracyCheckInputs`, `CostInputs`, Stage 2's realizer → `Selection`: the selected plan (`selected_dag`, a `DagOfSelectedCandidates`: one node per run of a candidate, so a candidate recomputed by two readers or shared as two instances over different inputs is two nodes, with an edge per input), its cost, the accepted accuracy per query and the search report | `select_plan` (`asap_plan_selection`); the facade (`run_planning`, output `PlanningRun`) runs it once and builds the selected `PhysicalWorkloadPlan` with `AssignmentRealizer::realize`, one plan node per selected node | +| 2 | One whole-workload logical candidate; entries (recurrence, predictability), `DataWorkload`, query-time retention → its physical candidates, one per physical properties assignment | `LogicalASAPMemoCandidates`; entries, `DataWorkload`, query-time and raw-data retention → `PhysicalASAPMemoCandidates`: every operator node of every candidate with each allowed timing and lifetime (one physical candidate each, no copies), the producers of each input, reader constraints (each applied to every selected run of its candidate), and the pruned candidates (`PrunedCandidate`) | `generate_physical_asap_memo_candidates` (`asap_stage2_physical_optimization`) | +| 3 | Every physical candidate; accuracy targets, accuracy model and evidence, cost model → one plan | `PhysicalASAPMemoCandidates`; entries, `DataWorkload`, `AccuracyCheckInputs`, `CostInputs`, Stage 2's realizer → `Selection`: the selected plan (`selected_dag`, a `DagOfSelectedCandidates`: one node per run of a candidate, so a candidate recomputed by two readers or shared as two instances over different inputs is two nodes, with an edge per input), its cost, the accepted accuracy per query and the search report | `select_plan` (`asap_stage3_plan_selection`); the facade (`run_planning`, output `PlanningRun`) runs it once and builds the selected `PhysicalWorkloadPlan` with `AssignmentRealizer::realize`, one plan node per selected node | | 4. Execution | The selected `PhysicalASAPDAG` → query results | Same: an `InstallablePlan` (`{dag, query_texts}`) → query results | The deployment runtime installs the `InstallablePlan` | What changed with the memo: diff --git a/docs/develop_docs/asap-aware-mapping-architecture.md b/docs/develop_docs/asap-aware-mapping-architecture.md index f22f1d0d5..2468e8daa 100644 --- a/docs/develop_docs/asap-aware-mapping-architecture.md +++ b/docs/develop_docs/asap-aware-mapping-architecture.md @@ -19,22 +19,26 @@ in `asap-integration-tests` (`crate_graph`) checks these edges with | --- | --- | | `asap-types` (`crates/types`) | Shared vocabulary, by scope: the operator IR by IR section, `ir::operator` (`OperatorNode`, `NonASAPOp`, `ASAPOp`, operator arguments, `AggIntent`), `ir::scalar` (`ScalarExpr`, `ColumnRef`), `ir::schema` (`Schema`, `FieldDataType`), `ir::properties` (execution timing, summary coverage) and `ir::flat`; summary types (`summary_type`: `SketchAlgorithm`, `SketchParams`, `SummaryTypeCapability`); accuracy targets and guarantees (`accuracy`: `AccuracyTarget`, `AccuracyMetric`, `AccuracyGuarantee`); the planner inputs (`workload`); the stage-boundary types (`stages`, with Stage 2's `PhysicalProperties` (timing and `Lifetime`)); and Stage 3's plan (`plan`: `plan::physical_asap_dag`, `plan::materialized_view`) | | `asap-frontend-sql`, `asap-frontend-promql`, `asap-frontend-metricsql` (with `asap-frontend-common`) | Stage 0, the query-language frontends: lower each query into the logical DAG (`QueryRoot`s of `NonASAPOp` nodes, no summaries, no timing) | -| `asap-logical-asap-optimization` (`crates/logical-asap-optimization`) | Stage 1: Pass 1 and Pass 2 (the memo rules) | +| `asap-stage0-memo` (`crates/stage0-memo`) | Stage 0 hash-consing: the memo groups of the workload's query roots (`memo_of_queries`) | +| `asap-stage1-pass1-per-computation-candidates` (`crates/stage1-pass1-per-computation-candidates`) | Stage 1, Pass 1: the initial candidates of each memo group | +| `asap-stage1-pass2-reuse-candidates` (`crates/stage1-pass2-reuse-candidates`) | Stage 1, Pass 2: the reuse rules over memo groups and the logical edges | | `asap-accuracy` (`crates/accuracy`) | The accuracy model the stages share: the analytical rules (per-algorithm estimators, composition, budget split, target check), the deployment's measured accuracy (`AccuracyEvidence`) and α^log (`producer_satisfies_logical_requirements`); depends only on `asap-types` | -| `asap-physical-asap-optimization` (`crates/physical-asap-optimization`) | Stage 2: materialization and physical operator implementation | +| `asap-stage2-physical-optimization` (`crates/stage2-physical-optimization`) | Stage 2: materialization and physical operator implementation | | `asap-cost` (`crates/cost`) | The cost model the stages share: resource-usage estimation (the analytical per-operator model, measured operation costs, state byte sizes) and the cost models (`ResourceUsage`, `CostModel`, `CostInputs`); depends only on `asap-types` | -| `asap-plan-selection` (`crates/plan-selection`) | Stage 3: `select_plan` over Stage 2's output; accuracy and latency checks, pricing candidates with `asap-cost` | +| `asap-stage3-plan-selection` (`crates/stage3-plan-selection`) | Stage 3: `select_plan` over Stage 2's output; accuracy and latency checks, pricing candidates with `asap-cost` | | `asap-planner` (`crates/planner`) | The facade: `e2e_plan` runs Stage 0, then the optimization pass (`Stage1ToStage3Pass` by default), which orchestrates Stages 1–3 (`run_planning`); the planning models (`PlanningModels`) and the `OptimizationPass` trait | | `asap-executor` (`crates/executor`) | Stage 4, the reference executor: operators and summary kernels over `asap_sketchlib`; it runs a `PhysicalASAPDAG` | | `asap-devtools` | `asap_planner` and the other inspection tools, the design-doc example workloads (`planner_layering_examples`) and the candidate labels | ```text asap-types ◄── frontends (Stage 0) -asap-types ◄── asap-cost (shared cost model) ◄── asap-physical-asap-optimization, asap-plan-selection -asap-types ◄── asap-accuracy (shared accuracy model) ◄── asap-logical-asap-optimization, asap-physical-asap-optimization, asap-plan-selection -asap-types ◄── asap-logical-asap-optimization (Stage 1) ◄── asap-planner -asap-types ◄── asap-physical-asap-optimization (Stage 2) ◄── asap-planner -asap-plan-selection (Stage 3) ◄── asap-planner (also depends on the frontends) +asap-types ◄── asap-cost (shared cost model) ◄── asap-stage2-physical-optimization, asap-stage3-plan-selection +asap-types ◄── asap-accuracy (shared accuracy model) ◄── asap-stage1-pass1-per-computation-candidates, asap-stage2-physical-optimization, asap-stage3-plan-selection +asap-types ◄── asap-stage0-memo (Stage 0 hash-consing) ◄── asap-planner +asap-types ◄── asap-stage1-pass1-per-computation-candidates (Stage 1, Pass 1) ◄── asap-planner +asap-types ◄── asap-stage1-pass2-reuse-candidates (Stage 1, Pass 2) ◄── asap-planner +asap-types ◄── asap-stage2-physical-optimization (Stage 2) ◄── asap-planner +asap-stage3-plan-selection (Stage 3) ◄── asap-planner (also depends on the frontends) asap-types ◄── asap-executor (Stage 4; no stage crate depends on it) ``` @@ -42,18 +46,18 @@ asap-types ◄── asap-executor (Stage 4; no stage crate depends on it) ```text QueryRoots (Stage 0) - │ memo_of_queries → DagOfLogicalMemoGroups, then - │ pass1_memo + │ asap_stage0_memo::memo_of_queries → DagOfLogicalMemoGroups, then + │ asap_stage1_pass1_per_computation_candidates::pass1_memo ▼ Stage 1, Pass 1 PerComputationLogicalMemoCandidates (Memo + pruned_candidates) - │ generate_logical_asap_memo_candidates - │ the memo rules (pass2/memo/rules/) over the candidate memo Stage 1, Pass 2 + │ asap_stage1_pass2_reuse_candidates::generate_logical_asap_memo_candidates + │ the memo rules (memo/rules/) over the candidate memo Stage 1, Pass 2 ▼ LogicalASAPMemoCandidates - │ asap_physical_asap_optimization::generate_physical_asap_memo_candidates Stage 2 + │ asap_stage2_physical_optimization::generate_physical_asap_memo_candidates Stage 2 ▼ PhysicalASAPMemoCandidates (operator nodes per timing/materialization + pruned_candidates) - │ asap_plan_selection::select_plan Stage 3 + │ asap_stage3_plan_selection::select_plan Stage 3 ▼ (PhysicalASAPDAG, Selection) — the plan, and accepted_accuracy_per_query, pruned_candidates and the selection MILP's size and time @@ -66,18 +70,18 @@ same pipeline behind the `OptimizationPass` trait. | Concern | Where it lives | | --- | --- | -| Pass 1: which computations a query has (`ComputationTarget`), how each can be computed (`HowToComputeAggregateMeasure`: `Exact`, `ExactAccumulator`, `Summary`), fused computations (`FusedComputation`), pruning (`PruneReason`) | `asap-logical-asap-optimization`, `pass1/computation_targets.rs` | -| Which summary families serve an intent (`summary_candidates`) | `asap-logical-asap-optimization`, `pass1/realization.rs` | -| Pass 2 memo rules: shared producers (identical expressions by memo group identity, one build at different sizes), scan-label widening, window composition (tumbling windows), rollup, exact top-k reuse and finer-aggregate reuse | `asap-logical-asap-optimization`, `pass2/memo/rules/` and `pass2/memo/window_candidates.rs`, over the helpers in `pass2/asap_aware_cse.rs` | -| Enumeration of the plans a memo stands for (reference pricer, DAG viewer) | `asap-logical-asap-optimization`, `pass2/memo/enumeration.rs` | +| Pass 1: which computations a query has (`ComputationTarget`), how each can be computed (`HowToComputeAggregateMeasure`: `Exact`, `ExactAccumulator`, `Summary`), fused computations (`FusedComputation`), pruning (`PruneReason`) | `asap-stage1-pass1-per-computation-candidates`, `computation_targets.rs` | +| Which summary families serve an intent (`summary_candidates`) | `asap-stage1-pass1-per-computation-candidates`, `summary_realization.rs` | +| Pass 2 steps: rollup from the finest common group (shared producers across group keys), top-k reuse, readout requirements, dead-candidate elimination, chain groups (tumbling windows) and the logical edges | `asap-stage1-pass2-reuse-candidates`, `lib.rs` (the steps in order) and `rules/` (`rollup.rs`, `topk.rs`, `chains.rs`) | +| Enumeration of the plans a memo stands for (reference pricer, DAG viewer) | none today (deleted in #1207 PR 0) | | What each summary type can merge and answer (`SummaryTypeCapability::of`: `merge_inputs`, `readouts`) | `asap-types`, `summary_type/capability.rs` | -| Stage 2: physical properties options per summary build (not materialized; materialized at ingestion time `AcrossEvaluations`; materialized at query time `OneEvaluation` or `AcrossEvaluations`), ingestion-time eligibility, physical operator implementation | `asap-physical-asap-optimization` | +| Stage 2: physical properties options per summary build (not materialized; materialized at ingestion time `AcrossEvaluations`; materialized at query time `OneEvaluation` or `AcrossEvaluations`), ingestion-time eligibility, physical operator implementation | `asap-stage2-physical-optimization` | | Timing and data-state edge rules applied from a `PhysicalPropertiesAssignment` | `asap-types`, `ir/properties/timing.rs` and `ir/properties/execution_data_state.rs`; `PhysicalProperties` and `Lifetime` in `physical/properties.rs` | -| Stage 3: accuracy check, latency check, resource usage (`ResourceUsage`), cost models 1–3 (`CostModel`), measured operation costs | `asap-plan-selection`, `lib.rs`; `asap-cost`, `lib.rs` and `measured.rs` | +| Stage 3: accuracy check, latency check, resource usage (`ResourceUsage`), cost models 1–3 (`CostModel`), measured operation costs | `asap-stage3-plan-selection`, `lib.rs`; `asap-cost`, `lib.rs` and `measured.rs` | | The analytical per-operator resource model Stage 3 measures with | `asap-cost`, `analytical.rs` and `operator_statistics.rs` | | The accuracy algebra: per-family guarantees, composition, budget split; guarantee propagation through a DAG; sizing a summary for its target, (ε, δ) budget and default sizes | `asap-accuracy` (`AccuracyEvidence`, `theoretical_guarantee`, `guarantee/`, `evidence.rs`, `requirements.rs`, `error_propagation.rs`, `composition.rs`, `budget.rs`, `propagation.rs`, `sizing.rs`) | -| What the executor supports (`DeploymentCapabilities`) | `asap-logical-asap-optimization`, `deployment_capabilities.rs`; Pass 1 receives only `supported_summaries` and Stage 2 only `query_time_results_retained` and `raw_data_retained` (`bool` arguments, so Stage 2 does not depend on the Stage 1 crate); Stage 3 reads none of it | -| The inputs every stage reads (`PlanningModels`: accuracy evidence, cost inputs, deployment capabilities) and the `OptimizationPass` trait | `asap-planner`, `pass.rs`; the facade gives Pass 2 the evidence and Stage 3 only `CostInputs` | +| What the executor supports (`DeploymentCapabilities`) | `asap-types`, `deployment_capabilities.rs`; Pass 1 receives only `supported_summaries` and Stage 2 only `query_time_results_retained` and `raw_data_retained` (`bool` arguments, so Stage 2 does not depend on the Stage 1 crate); Stage 3 reads none of it | +| The inputs every stage reads (`PlanningModels`: accuracy evidence, cost inputs, deployment capabilities) and the `OptimizationPass` trait | `asap-planner`, `models.rs` (`PlanningModels`) and `pass.rs` (the trait); the facade gives Pass 2 the evidence and Stage 3 only `CostInputs` | The current production search organizes these computations in memo result/state groups and jointly selects physical candidates and connections; it does not @@ -115,9 +119,10 @@ No stage caps the candidates it plans, and neither does `asap_planner`. ## Verification - Unit tests sit beside each module (`cargo nextest run -p - asap-logical-asap-optimization -p asap-physical-asap-optimization -p - asap-plan-selection -E 'test()'`). -- `crates/logical-asap-optimization/tests/per_computation_candidates.rs` covers + asap-stage0-memo -p asap-stage1-pass1-per-computation-candidates -p + asap-stage1-pass2-reuse-candidates -p asap-stage2-physical-optimization -p + asap-stage3-plan-selection -E 'test()'`). +- `crates/stage1-pass1-per-computation-candidates/src/per_computation_candidates_tests.rs` covers Pass 1. - `crates/integration-tests/tests/planner_layering_example{1,2,3,4}.rs` pin the design document's examples through every stage; diff --git a/docs/develop_docs/asap-aware-mapping-contracts.md b/docs/develop_docs/asap-aware-mapping-contracts.md index 4935b3c26..4af0ad108 100644 --- a/docs/develop_docs/asap-aware-mapping-contracts.md +++ b/docs/develop_docs/asap-aware-mapping-contracts.md @@ -5,8 +5,8 @@ the stage code relies on: what each stage's input and output may contain, and which component owns each decision. Read the [architecture](asap-aware-mapping-architecture.md) first; use the [extension guide](extend-asap-aware-mapping.md) when changing one. Field-level -details are in the rustdoc (`cargo doc -p asap-logical-asap-optimization -p -asap-physical-asap-optimization -p asap-plan-selection -p asap-types +details are in the rustdoc (`cargo doc -p asap-stage0-memo -p asap-stage1-pass1-per-computation-candidates -p +asap-stage1-pass2-reuse-candidates -p asap-stage2-physical-optimization -p asap-stage3-plan-selection -p asap-types --no-deps`). ## 1. IR at each stage @@ -18,7 +18,7 @@ asap-physical-asap-optimization -p asap-plan-selection -p asap-types | Stage 2 (`generate_physical_asap_memo_candidates`) and Stage 3 (`select_plan`, which builds the plan) | the same operators, with a timing and a `Lifetime` on each summary build | every node of the plan timed from the physical candidate it was built from (`selected_physical_candidate`) | - Structurally equal sub-DAGs are interned before Stage 1 - (`stage0/cse.rs` in `asap_logical_asap_optimization`), so Stage 1 compares nodes by structure and Pass 2 + (`cse.rs` in `asap_stage0_memo`), so Stage 1 compares nodes by structure and Pass 2 matches readers structurally, never by pointer. - Timing is applied with `apply_physical_properties`, which validates every data-state edge. A violation is an `ExecutionDataStateError`: @@ -37,7 +37,7 @@ asap-physical-asap-optimization -p asap-plan-selection -p asap-types - **Targets.** `ComputationTarget` is one measure of one `Aggregate`. Its `ways_to_compute` list the exact option first (`ExactAccumulator` when the intent has a mergeable exact state, else `Exact`), then each `Summary(family)` from - `realization::summary_candidates`. Candidates are unranked: Pass 1 never + `summary_realization::summary_candidates`. Candidates are unranked: Pass 1 never compares cost. - **Pruning.** A candidate that cannot meet the target is moved to the inventory's `pruned_ways_to_compute` (with its target) with a `PruneReason` (`RequiresExact`, diff --git a/docs/develop_docs/extend-asap-aware-mapping.md b/docs/develop_docs/extend-asap-aware-mapping.md index a95a8d4fe..9072b3536 100644 --- a/docs/develop_docs/extend-asap-aware-mapping.md +++ b/docs/develop_docs/extend-asap-aware-mapping.md @@ -24,8 +24,8 @@ A new sketch that Pass 1 can offer for an intent. evaluates is its own declaration, `EVALUATED_READOUTS` (`crates/executor/src/capability.rs`); add the family's readouts there once the executor answers them. -3. **Offer and size.** Place it in `realization::FAMILY_PREFERENCE` - (`crates/logical-asap-optimization`): `summary_candidates` offers it, in +3. **Offer and size.** Place it in `summary_realization::FAMILY_PREFERENCE` + (`crates/stage1-pass1-per-computation-candidates`): `summary_candidates` offers it, in that order, for every intent whose statistic its capability row answers. Size it in `asap_accuracy::sizing::default_size_params`. 4. **Accuracy.** Add its error model under @@ -44,7 +44,7 @@ A new sketch that Pass 1 can offer for an intent. not with a local copy. 7. **Labels.** Name it in `asap_devtools::candidate_labels`. -Tests: a Pass 1 test in `crates/logical-asap-optimization/tests/per_computation_candidates.rs` +Tests: a Pass 1 test in `crates/stage1-pass1-per-computation-candidates/src/per_computation_candidates_tests.rs` that the intent gets the new candidate (and that a deployment without it prunes it with `UnsupportedByDeployment`); an estimator test beside the estimator; an execution test in `crates/integration-tests/tests/` such as @@ -55,14 +55,14 @@ estimator; an execution test in `crates/integration-tests/tests/` such as A new way for computations of one Pass 1 candidate to share, split or reuse work. -1. Add a memo rule under `crates/logical-asap-optimization/src/pass2/memo/rules/` +1. Add a memo rule under `crates/stage1-pass2-reuse-candidates/src/memo/rules/` (for example `rollup.rs` or `topk.rs`): it adds candidates (and, when it needs them, groups) to the memo groups it implements, keeping every existing candidate. Read summary families only through `SummaryTypeCapability`. Shared rewrite helpers live in `pass2/asap_aware_cse.rs`. -2. Declare it in `pass2/memo/rules.rs` and call it from `apply_sharing_rules` - (`pass2.rs`), after the +2. Declare it in `rules.rs` and call it from `generate_logical_asap_memo_candidates` + (`stage1-pass2-reuse-candidates/src/lib.rs`), after the existing rules. 3. Add its row to the Pass 2 rule table of the [design](../design_docs/proposals/planner-layering.md). @@ -81,7 +81,7 @@ contains the candidate and that Stage 3 prices it. (`crates/types/src/stages/physical/properties.rs`, `PhysicalProperties::new` and `readable_at`) and its placement in `crates/types/src/ir/properties/timing.rs`, with its data-state edge rules. -2. Offer it in `crates/physical-asap-optimization/src/lib.rs` (the +2. Offer it in `crates/stage2-physical-optimization/src/lib.rs` (the `MaterializedOutputCandidate` options), after the existing options so default candidate ids stay the same, and gate it on the deployment input that allows it. diff --git a/docs/develop_docs/library-api.md b/docs/develop_docs/library-api.md index 41c6b5859..126c6615d 100644 --- a/docs/develop_docs/library-api.md +++ b/docs/develop_docs/library-api.md @@ -24,22 +24,23 @@ artifact, while preserving the checks required by its intended consumer. ## Dependencies Inside this workspace, depend on the frontend you need, the stage crates -(`asap-logical-asap-optimization` for Stage 1, `asap-physical-asap-optimization` -for Stage 2, `asap-plan-selection` for Stage 3), `asap-planner` for the facade that +(`asap-stage0-memo` for Stage 0 hash-consing, `asap-stage1-pass1-per-computation-candidates` and +`asap-stage1-pass2-reuse-candidates` for Stage 1, `asap-stage2-physical-optimization` +for Stage 2, `asap-stage3-plan-selection` for Stage 3), `asap-planner` for the facade that runs the stages, `asap-cost` for the cost model and its inputs (`CostInputs`), `asap-accuracy` for the accuracy rules and the deployment's measured accuracy (`AccuracyEvidence`), and `asap-types`, or on `asap-planner`, which wraps every frontend and the planning stages. External users can use Git dependencies pinned to a compatible revision; use the same revision across these crates, and pick a revision at least as new as the APIs you call. Replace `REV` below with a -`main` revision that has the stage crates (`crates/plan-selection`). +`main` revision that has the stage crates (`crates/stage3-plan-selection`). For the examples below: ```toml [dependencies] asap-planner = { git = "https://github.com/ProjectASAP/ASAPPlanner", rev = "REV" } asap-frontend-promql = { git = "https://github.com/ProjectASAP/ASAPPlanner", rev = "REV" } -asap-plan-selection = { git = "https://github.com/ProjectASAP/ASAPPlanner", rev = "REV" } +asap-stage3-plan-selection = { git = "https://github.com/ProjectASAP/ASAPPlanner", rev = "REV" } asap-cost = { git = "https://github.com/ProjectASAP/ASAPPlanner", rev = "REV" } asap-accuracy = { git = "https://github.com/ProjectASAP/ASAPPlanner", rev = "REV" } asap-types = { git = "https://github.com/ProjectASAP/ASAPPlanner", rev = "REV" } @@ -183,7 +184,7 @@ asap_planner::run_planning( ) -> Result // Stage 3 alone, over Stage 2's output: -asap_plan_selection::select_plan( +asap_stage3_plan_selection::select_plan( physical: &PhysicalASAPMemoCandidates, entries: &[QueryWorkloadEntry], data: &DataWorkload, @@ -195,7 +196,7 @@ asap_plan_selection::select_plan( | --- | --- | | `PlanningModels::new(evidence)` | Your `&dyn AccuracyEvidence` (measured guarantees; `NoMeasuredGuarantees` has none), with default cost inputs and deployment capabilities; `with_evidence` replaces it; `with_ignore_accuracy_guarantees(true)` gives every query no accuracy target | | `PlanningModels::builtin()` | No measured accuracy evidence. `with_cost_inputs(&settings)` sets the deployment's `CostInputs`; `with_deployment_capabilities(&capabilities)` sets its `DeploymentCapabilities` (field `deployment_capabilities`) | -| `DeploymentCapabilities` (`asap_logical_asap_optimization`, re-exported as `asap_planner::DeploymentCapabilities`) | What the executor supports: `supported_summaries` (`None`, the default, supports every summary the planner builds; otherwise `SupportedSummary { summary_type: SketchAlgorithm, readouts: Vec }` entries; Pass 1 prunes others with `PruneReason::UnsupportedByDeployment`), `raw_data_retained` (default `true`; when `false`, a candidate that scans raw data at query time is pruned by Stage 2, and stored data is refused with `asap_planner::SelectionError::InvalidDeploymentCapabilities`) and `query_time_results_retained` (default `false`; when `true`, Stage 2 offers query-time `AcrossEvaluations` for tumbling-window chains) | +| `DeploymentCapabilities` (`asap_types::deployment_capabilities`, re-exported as `asap_planner::DeploymentCapabilities`) | What the executor supports: `supported_summaries` (`None`, the default, supports every summary the planner builds; otherwise `SupportedSummary { summary_type: SketchAlgorithm, readouts: Vec }` entries; Pass 1 prunes others with `PruneReason::UnsupportedByDeployment`), `raw_data_retained` (default `true`; when `false`, a candidate that scans raw data at query time is pruned by Stage 2, and stored data is refused with `asap_planner::SelectionError::InvalidDeploymentCapabilities`) and `query_time_results_retained` (default `false`; when `true`, Stage 2 offers query-time `AcrossEvaluations` for tumbling-window chains) | | `CostInputs` (`asap_cost`) | `cost_model`, `resource_speed` (`ms_per_cpu_op`, `ms_per_scanned_byte`), `non_repeating_query_horizon_seconds` (default 3,600) and `measured_operation_costs` (`MeasuredOperationCosts`, default empty: `operators`, one `OperatorCost { operator, phase, sketch / exact / measure, ns_per_unit, ns_per_invocation, memory_bytes_per_state }` per measured operator kind, phase and family; `ns_per_evaluation` per query request; `provenance` (executor version, machine). A node with an entry is priced from it, a sketch between the two nearest measured sizes; every other node from the formulas times one calibration factor fitted from the measured nodes; each node's `NodeCost::cost_source` says which. The earlier JSON array of `MeasuredOperationCost { sketch, operation, cpu_ns_per_operation }` still loads) | | `CostModel::UsageOverTime(ResourceUnitCost)` | Cost model 1 (default, `ResourceUnitCost::illustrative()`): unit cost × usage per second; the cheapest valid candidate wins | | `CostModel::ProvisionedCapacity(ResourceUnitCost)` | Cost model 2: unit cost × peak memory, peak CPU cores and disk; the cheapest valid candidate wins | @@ -365,14 +366,15 @@ cost/guarantee evidence needed downstream instead of exporting only a bare DAG. For public symbol details, build local API documentation with: ```sh -cargo doc -p asap-logical-asap-optimization -p asap-physical-asap-optimization \ - -p asap-plan-selection -p asap-types --no-deps +cargo doc -p asap-stage0-memo -p asap-stage1-pass1-per-computation-candidates \ + -p asap-stage1-pass2-reuse-candidates -p asap-stage2-physical-optimization \ + -p asap-stage3-plan-selection -p asap-types --no-deps ``` ## Source references - [Frontend PromQL](../../crates/frontend-promql/src/lib.rs), [SQL](../../crates/frontend-sql/src/lib.rs), [MetricsQL](../../crates/frontend-metricsql/src/lib.rs) -- [Planner facade](../../crates/planner/src/lib.rs), [planning stages](../../crates/planner/src/run.rs), [plan selection and cost models 1–3](../../crates/plan-selection/src/lib.rs) -- [Deployment capabilities](../../crates/logical-asap-optimization/src/deployment_capabilities.rs) +- [Planner facade](../../crates/planner/src/lib.rs), [planning stages](../../crates/planner/src/run.rs), [plan selection and cost models 1–3](../../crates/stage3-plan-selection/src/lib.rs) +- [Deployment capabilities](../../crates/types/src/deployment_capabilities.rs) - [Workload types](../../crates/types/src/workload/mod.rs) - [Planner-runtime contract](../design_docs/architecture/planner-runtime-contract.md) diff --git a/docs/develop_docs/metrics-observability-corpora.md b/docs/develop_docs/metrics-observability-corpora.md index f9684a0ec..181f75045 100644 --- a/docs/develop_docs/metrics-observability-corpora.md +++ b/docs/develop_docs/metrics-observability-corpora.md @@ -1,5 +1,10 @@ # Metrics-observability corpus coverage +> **Status.** The executable corpus test, `metrics_observability.rs`, was deleted +> when each planning stage became its own crate: a frontend crate's tests may not +> call Stage 0 or Stage 1. The fixtures stay, for the Pass 1 coverage tests that +> replace it. The sections below describe the deleted test. + This note describes the PromQL corpora derived from the metrics-observability benchmark dump and the commands used to reproduce their measurements. The audience is developers evaluating changes to the PromQL front end or ASAP diff --git a/docs/develop_docs/pre-asap-ir.md b/docs/develop_docs/pre-asap-ir.md index 9a2d23dc5..f3346279b 100644 --- a/docs/develop_docs/pre-asap-ir.md +++ b/docs/develop_docs/pre-asap-ir.md @@ -149,7 +149,7 @@ yet — and calls `asap_frontend_common::resolve_root`, which does three things The result is `Rc`. `lower_sql` / `lower_sql_dialect` and `lower_metricsql` return it; `lower_promql_query_workload` returns a `QueryRoot` per query. -Workload search then runs structural CSE (`share_common_sub_dags` (crate-private in `asap_logical_asap_optimization`, `stage0/cse.rs`)) once +Workload search then runs structural CSE (`share_common_sub_dags` (crate-private in `asap_stage0_memo`, `cse.rs`)) once across every root: bottom-up hash-consing where the structural hash is only a filter and the typed `PartialEq` decides sharing, following scalar references like any other input, and gated by `NonASAPOp::is_shareable_when_equal` for non-ASAP producers. diff --git a/docs/develop_docs/target-candidate-api-migration.md b/docs/develop_docs/target-candidate-api-migration.md index ec899a98c..04d38d6c9 100644 --- a/docs/develop_docs/target-candidate-api-migration.md +++ b/docs/develop_docs/target-candidate-api-migration.md @@ -49,7 +49,7 @@ or `Operator::ASAP(ASAPOp)`. Old public names are not kept as aliases. | `SummaryFamilyType` | `FieldDataType` (its non-`Plain` variants) | | Timing stored on post-ASAP nodes | `OperatorNode::timing`, `None` until `ir::timing::apply_physical_properties` writes it from a `PhysicalPropertiesAssignment` (default: all query time) | | `UnresolvedQueryExpr` + `asap_types::pre_asap::resolve_root` | `UnresolvedOp` / `UnresolvedScalar` + `asap_frontend_common::resolve_root` | -| `pre_asap::canonicalize`, `pre_asap::cse::share_common_sub_dags` | `asap_frontend_common` `canonicalize` (crate-private), `share_common_sub_dags` (crate-private in `asap_logical_asap_optimization`, `stage0/cse.rs`) | +| `pre_asap::canonicalize`, `pre_asap::cse::share_common_sub_dags` | `asap_frontend_common` `canonicalize` (crate-private), `share_common_sub_dags` (crate-private in `asap_stage0_memo`, `cse.rs`) | | `asap_types::post_asap::compile_post_asap_dag` (wire version 5, `Fallback`/`Binary`/`Value` payloads) | `asap_types::plan::physical_asap_dag::compile_physical_asap_dag` (`PhysicalASAPDAG`, carried in the plan file versioned by `asap_planner::INSTALLABLE_PLAN_WIRE_VERSION`: one node per operator, `Operator` payloads, `ScalarRef` edges); input must be timed | | Exported schema JSON `columns` | `fields` |