diff --git a/crates/cost/src/measured.rs b/crates/cost/src/measured.rs index f0468a63b..7a660ce44 100644 --- a/crates/cost/src/measured.rs +++ b/crates/cost/src/measured.rs @@ -45,12 +45,12 @@ use std::mem::discriminant; use asap_types::ir::operator::AggIntent; use asap_types::ir::properties::ExecutionTiming; -use asap_types::ir::{ASAPOp, NonASAPOp, Operator}; -use asap_types::plan::physical_asap_dag::PhysicalASAPOperatorPayload as Payload; use asap_types::summary_type::{ExactKind, SketchParams}; use serde::{Deserialize, Serialize}; use crate::node::analytical::AnalyticalCostError; +/// The operator vocabulary the table is keyed by; it lives with the IR. +pub use asap_types::ir::operator::OperatorKind; /// The deployment's measured cost table /// ([`CostInputs::measured_operation_costs`]). In JSON, an object @@ -105,7 +105,22 @@ pub struct OperatorCost { /// when each of its measures has an entry. #[serde(default, skip_serializing_if = "Option::is_none")] pub measure: Option, - /// CPU nanoseconds per unit the operator processes ([`OperatorKind`]). + /// CPU nanoseconds per unit the operator processes. The unit is the + /// row the operator reads unless listed here: + /// + /// * `Scan`: per sample read. At ingestion time, an arriving sample; at + /// query time, a sample fetched and decoded from the database holding + /// raw data, part of the deployment's cost; + /// * `Aggregate`: per input row, for each measure; + /// * `SummaryAgg`: per input row inserted into its group's state; + /// * `SummaryEstimate`: per group read; + /// * `FinalizeExactAccumulator`: per accumulator finalized (one per + /// group); + /// * `SummaryMerge`: per input state merged (each tumbling window of a + /// chain is a state); + /// * `SummaryTumblingWindowChain`: per input row placed in its tumbling + /// window and inserted into that window's state. + /// /// It includes what the formulas charge apart, at the measured shape: /// the output rows a merge, an aggregate or an estimate builds per /// group and the label columns a grouping carries per row. Example: a @@ -126,98 +141,6 @@ pub struct OperatorCost { pub memory_bytes_per_state: Option, } -/// Every physical operator a physical plan DAG can contain, by the name it -/// has there. The unit each is priced per is the row it reads unless said -/// otherwise. -#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] -pub enum OperatorKind { - /// Per sample read. At ingestion time, an arriving sample; at query - /// time, a sample fetched and decoded from the database holding raw - /// data, part of the deployment's cost. - Scan, - Values, - Filter, - Project, - /// Per input row, for each measure. - Aggregate, - Join, - SetOp, - Concat, - Dedup, - Sort, - Limit, - BinaryOp, - SQLWindowFunc, - TimeRange, - TimeShift, - PromqlVectorFromScalar, - PromqlRelabel, - PromqlInfoEnrich, - PromqlSeriesSample, - PromqlSubquery, - /// Per input row inserted into its group's state. - SummaryAgg, - /// Per group read. - SummaryEstimate, - /// Per accumulator finalized (one per group). - FinalizeExactAccumulator, - MaintainPopulation, - EvaluatePopulation, - /// Per input state merged (each tumbling window of a chain is a state). - SummaryMerge, - /// Per input row placed in its tumbling window and inserted into that tumbling window's state. - // Named `PaneChain` before #1163. - #[serde(alias = "PaneChain")] - SummaryTumblingWindowChain, - SummarySubtract, - SummaryDelete, - SummaryJoin, - Extension, -} - -impl OperatorKind { - /// The kind of `payload`. - pub fn of(payload: &Payload) -> Self { - match payload { - Operator::NonASAP(op) => match op { - NonASAPOp::Scan { .. } => Self::Scan, - NonASAPOp::Values { .. } => Self::Values, - NonASAPOp::Filter { .. } => Self::Filter, - NonASAPOp::Project { .. } => Self::Project, - NonASAPOp::Aggregate { .. } => Self::Aggregate, - NonASAPOp::Join { .. } => Self::Join, - NonASAPOp::SetOp { .. } => Self::SetOp, - NonASAPOp::Concat { .. } => Self::Concat, - NonASAPOp::Dedup { .. } => Self::Dedup, - NonASAPOp::Sort { .. } => Self::Sort, - NonASAPOp::Limit { .. } => Self::Limit, - NonASAPOp::BinaryOp { .. } => Self::BinaryOp, - NonASAPOp::SQLWindowFunc { .. } => Self::SQLWindowFunc, - NonASAPOp::TimeRange { .. } => Self::TimeRange, - NonASAPOp::TimeShift { .. } => Self::TimeShift, - NonASAPOp::PromqlVectorFromScalar(_) => Self::PromqlVectorFromScalar, - NonASAPOp::PromqlRelabel { .. } => Self::PromqlRelabel, - NonASAPOp::PromqlInfoEnrich { .. } => Self::PromqlInfoEnrich, - NonASAPOp::PromqlSeriesSample { .. } => Self::PromqlSeriesSample, - NonASAPOp::PromqlSubquery { .. } => Self::PromqlSubquery, - }, - Operator::ASAP(op) => match op { - ASAPOp::SummaryAgg { .. } => Self::SummaryAgg, - ASAPOp::SummaryEstimate { .. } => Self::SummaryEstimate, - ASAPOp::FinalizeExactAccumulator { .. } => Self::FinalizeExactAccumulator, - ASAPOp::MaintainPopulation { .. } => Self::MaintainPopulation, - ASAPOp::EvaluatePopulation { .. } => Self::EvaluatePopulation, - ASAPOp::SummaryMerge { .. } => Self::SummaryMerge, - ASAPOp::SummaryTumblingWindowChain { .. } => Self::SummaryTumblingWindowChain, - ASAPOp::SummarySubtract { .. } => Self::SummarySubtract, - ASAPOp::SummaryDelete { .. } => Self::SummaryDelete, - ASAPOp::SummaryJoin { .. } => Self::SummaryJoin, - ASAPOp::Extension { .. } => Self::Extension, - }, - } - } -} - /// The state family a summary node works on, which selects its entries. #[derive(Debug, Clone, Copy, PartialEq)] pub enum StateFamily<'a> { @@ -326,7 +249,7 @@ pub(crate) fn aggregate_lookup( memory_bytes_per_state: None, }; for measure in measures { - let name = measure_name(measure); + let name = measure.kind_name(); let find = |for_phase: Option| { table.operators.iter().find(|e| { e.operator == OperatorKind::Aggregate @@ -341,14 +264,6 @@ pub(crate) fn aggregate_lookup( (!measures.is_empty()).then_some(total) } -/// An aggregate measure's name as an entry states it: its JSON `kind`. -fn measure_name(measure: &AggIntent) -> String { - serde_json::to_value(measure) - .ok() - .and_then(|value| value.get("kind")?.as_str().map(str::to_owned)) - .unwrap_or_else(|| format!("{measure:?}")) -} - fn price_of(entry: &OperatorCost) -> UnitPrice { UnitPrice { ns_per_unit: entry.ns_per_unit, diff --git a/crates/devtools/src/bin/asap_planner.rs b/crates/devtools/src/bin/asap_planner.rs index a233874c9..d5da82ff8 100644 --- a/crates/devtools/src/bin/asap_planner.rs +++ b/crates/devtools/src/bin/asap_planner.rs @@ -41,7 +41,9 @@ // field takes its default). // - `--deployment-capabilities `: the `DeploymentCapabilities` // (`supported_summaries`, `raw_data_retained`, -// `query_time_results_retained`; an omitted field takes its default). +// `query_time_results_retained`, `counter_semantics`, +// `state_not_mergeable_across_windows`, `excluded_candidates`; an +// omitted field takes its default). // Without `supported_summaries`, the executor's summary families are // supported, as `plan_installable` defaults it. // - `--ignore-accuracy-guarantees`: Stage 3 accepts every query output diff --git a/crates/devtools/src/bin/sketch_coverage.rs b/crates/devtools/src/bin/sketch_coverage.rs index 4438a9b71..61c5fdf22 100644 --- a/crates/devtools/src/bin/sketch_coverage.rs +++ b/crates/devtools/src/bin/sketch_coverage.rs @@ -57,7 +57,7 @@ fn analyze_corpus( rejected += 1; continue; }; - let Ok(pass1) = pass1_memo(memo, None) else { + let Ok(pass1) = pass1_memo(memo, &[]) else { rejected += 1; continue; }; diff --git a/crates/devtools/src/planner_fuzz/mod.rs b/crates/devtools/src/planner_fuzz/mod.rs index 91904f311..e363c06aa 100644 --- a/crates/devtools/src/planner_fuzz/mod.rs +++ b/crates/devtools/src/planner_fuzz/mod.rs @@ -227,6 +227,7 @@ impl FuzzWorkload { ), raw_data_retained: self.raw_data_retained, query_time_results_retained: self.query_time_results_retained, + ..DeploymentCapabilities::default() } } diff --git a/crates/devtools/src/planning_stages.rs b/crates/devtools/src/planning_stages.rs index dba4d1fe6..ef1e3a98f 100644 --- a/crates/devtools/src/planning_stages.rs +++ b/crates/devtools/src/planning_stages.rs @@ -257,16 +257,13 @@ pub fn run_stages_until( return Ok(stages); } let run = &mut stages.run; - let pass1 = pass1_memo( - stage0_dag, - models - .deployment_capabilities - .supported_summaries - .as_deref(), - ) - // As `run_planning`: a query Pass 1 cannot plan is reported before - // contradictory deployment capabilities. - .map_err(|error| PlanningStagesError::Pass1(error.to_string()))?; + // As `run_planning`: the exclusions are expanded once, for Pass 1 and + // Stage 2. + let exclusions = models.deployment_capabilities.exclusions(); + let pass1 = pass1_memo(stage0_dag, &exclusions) + // As `run_planning`: a query Pass 1 cannot plan is reported before + // contradictory deployment capabilities. + .map_err(|error| PlanningStagesError::Pass1(error.to_string()))?; if let Err(error) = models.deployment_capabilities.validate(data) { run.selection = Err(SelectionError::InvalidDeploymentCapabilities(error)); return Ok(stages); @@ -288,8 +285,7 @@ pub fn run_stages_until( return Ok(stages); } let logical = run.logical_asap_candidates.as_ref().expect("set above"); - let physical = - generate_physical_asap_memo_candidates(logical, data, models.deployment_capabilities); + let physical = generate_physical_asap_memo_candidates(logical, data, &exclusions); if until == RunUntil::Stage2 { run.physical_asap_candidates = Some(physical); return Ok(stages); diff --git a/crates/devtools/src/planning_stages_text.rs b/crates/devtools/src/planning_stages_text.rs index c3efbf9a4..68938d8bf 100644 --- a/crates/devtools/src/planning_stages_text.rs +++ b/crates/devtools/src/planning_stages_text.rs @@ -46,7 +46,7 @@ use asap_types::stages::{ AggregateCoverage, CandidateForMemoGroup, CandidateForMemoGroupId, ColumnLineage, EvaluationGrid, LogicalASAPMemoCandidates, LogicalEdge, Memo, MemoGroup, MemoGroupId, PhysicalASAPMemoCandidates, PhysicalCandidate, PhysicalCandidateId, PhysicalEdge, - PhysicalProperties, PrunedCandidate, RequiredAccuracy, RootPruneReason, + PhysicalProperties, PruneReason, PrunedCandidate, RequiredAccuracy, RootPruneReason, }; use asap_types::summary_type::SketchParams; @@ -1281,13 +1281,14 @@ fn write_physical_pruned( if !verbose { let reasons: Vec = pruned .iter() - .map(|pruned| { - let reason = format!("{:?}", pruned.reason); - reason + .map(|pruned| match &pruned.reason { + // Counted per capability it comes from. + PruneReason::ExcludedByDeployment(_) => prune_reason_text(&pruned.reason), + reason => format!("{reason:?}") .split(['(', ' ', '{']) .next() .unwrap_or_default() - .to_owned() + .to_owned(), }) .collect(); if !reasons.is_empty() { @@ -1305,7 +1306,7 @@ fn write_physical_pruned( vec![ candidate_id_text(pruned.candidate.logical_candidate_id), physical_properties_text(&pruned.candidate.physical_properties), - format!("{:?}", pruned.reason), + prune_reason_text(&pruned.reason), ] }) .collect(); @@ -1394,6 +1395,18 @@ fn write_physical_by_logical_candidate( } } +/// A Stage 2 or Stage 3 prune reason: a deployment exclusion names the +/// capability it comes from as the capabilities' JSON does, e.g. +/// `ExcludedByDeployment(raw_data_not_retained)` or +/// `ExcludedByDeployment(excluded_candidates[0])`; any other reason is its +/// debug form, e.g. `DominatedBy(PhysicalCandidateId(3))`. +fn prune_reason_text(reason: &PruneReason) -> String { + match reason { + PruneReason::ExcludedByDeployment(source) => format!("ExcludedByDeployment({source})"), + reason => format!("{reason:?}"), + } +} + /// Stage 3's plan, each node with its physical candidate, operator and /// input nodes; the plan's cost (`plan_cost`) with each node's charge; its /// materialized views (`materialized_views`), one line each with its node, diff --git a/crates/devtools/tests/asap_planner.rs b/crates/devtools/tests/asap_planner.rs index 908cffbd1..db141c0b6 100644 --- a/crates/devtools/tests/asap_planner.rs +++ b/crates/devtools/tests/asap_planner.rs @@ -768,7 +768,8 @@ fn aws_fargate_prices_example_4_in_dollars() { /// the document's `deployment_capabilities` shows (defaults filled in; /// without the flag, every summary supported, raw data retained, no /// query-time result retained). For Pattern B with KLL only and query-time -/// results retained: Pass 1 offers no DDSketch candidate. Without raw data, a plan is still selected +/// results retained: Pass 1 offers no DDSketch candidate (the deployment +/// excludes every DDSketch state outright). Without raw data, a plan is still selected /// with guarantees enforced, from materialized views. A deployment with an /// unknown field is refused. #[test] @@ -794,6 +795,9 @@ fn deployment_capabilities_flag_sets_the_capabilities_and_shows_them() { "supported_summaries": asap_executor::supported_summary_families(), "raw_data_retained": true, "query_time_results_retained": false, + "counter_semantics": { "reset_handling": true, "extrapolation": true }, + "state_not_mergeable_across_windows": [], + "excluded_candidates": [], }) ); let kll_kept = with_capabilities( @@ -807,6 +811,9 @@ fn deployment_capabilities_flag_sets_the_capabilities_and_shows_them() { "supported_summaries": [{ "summary_type": "Kll", "readouts": ["Quantile"] }], "raw_data_retained": true, "query_time_results_retained": true, + "counter_semantics": { "reset_handling": true, "extrapolation": true }, + "state_not_mergeable_across_windows": [], + "excluded_candidates": [], }) ); let has_ddsketch = |document: &Value| { diff --git a/crates/integration-tests/tests/crate_graph.rs b/crates/integration-tests/tests/crate_graph.rs index c948add4b..5eb14d2be 100644 --- a/crates/integration-tests/tests/crate_graph.rs +++ b/crates/integration-tests/tests/crate_graph.rs @@ -191,6 +191,50 @@ fn workspace_crate_graph_follows_the_target_graph() { assert!(violations.is_empty(), "{}", violations.join("\n")); } +/// Planning reads its inputs only from its arguments: no planning stage or +/// the facade reads the process environment, so what a deployment +/// excludes travels in `DeploymentCapabilities` and cannot come back as an +/// environment-variable hook patched into a stage (such as a variable +/// naming candidates Stage 3 must not select). Every `.rs` file under the +/// stage crates', the shared types' and the facade's `src`. +#[test] +fn planning_crates_read_no_environment_variables() { + let workspace = concat!(env!("CARGO_MANIFEST_DIR"), "/../.."); + let mut pending: Vec = [ + "types", + "stage0-memo", + "stage1-pass1-per-computation-candidates", + "stage1-pass2-reuse-candidates", + "stage2-physical-optimization", + "stage3-plan-selection", + "planner", + ] + .iter() + .map(|name| { + std::path::Path::new(workspace) + .join("crates") + .join(name) + .join("src") + }) + .collect(); + let mut readers = Vec::new(); + while let Some(path) = pending.pop() { + for entry in std::fs::read_dir(&path).expect("reads the source directory") { + let path = entry.expect("reads an entry").path(); + if path.is_dir() { + pending.push(path); + } else if path.extension().is_some_and(|extension| extension == "rs") { + let text = std::fs::read_to_string(&path).expect("reads a source file"); + // `env::var` also finds `env::var_os`. + if text.contains("env::var") { + readers.push(format!("{}: env::var", path.display())); + } + } + } + } + assert!(readers.is_empty(), "{}", readers.join("\n")); +} + /// A package of synthetic `cargo metadata` JSON with `[dependencies]` on /// `deps` and `[dev-dependencies]` on `dev_deps`. fn package(name: &str, deps: &[&str], dev_deps: &[&str]) -> Value { diff --git a/crates/integration-tests/tests/deployment_exclusions.rs b/crates/integration-tests/tests/deployment_exclusions.rs new file mode 100644 index 000000000..e64c4ec26 --- /dev/null +++ b/crates/integration-tests/tests/deployment_exclusions.rs @@ -0,0 +1,678 @@ +//! Deployment exclusions end to end: a deployment's capabilities (and the +//! caller's own `excluded_candidates`) expand into exclusions Stage 2 +//! applies as one filter, so Stage 3 never selects an excluded candidate +//! and reports when no plan is left without them. +//! +//! Every plan and cost below was observed at the base commit with a probe +//! that pruned the same candidates in Stage 2 (a throwaway patch, since +//! deleted); the counts of pruned candidates are the probe's. + +use asap_devtools::planning_stages::{lower_promql_roots, run_planning_stages_over}; +use asap_planner::{ + CandidateExclusion, CounterSemanticsSupport, DeploymentCapabilities, ErrorSelectingPlan, + ExclusionSource, OperatorKind, PlanningModels, PlanningRun, RejectionCause, Selection, + SelectionError, SketchAlgorithm, SketchParameterRange, SketchParams, SummaryFamily, +}; +use asap_types::deployment_capabilities::CandidateDescription; +use asap_types::ir::flat::NodeId; +use asap_types::ir::operator::arguments::Reduction; +use asap_types::ir::operator::AggIntent; +use asap_types::ir::properties::ExecutionTiming::{self, IngestionTime, QueryTime}; +use asap_types::ir::schema::FieldDataType; +use asap_types::ir::{ASAPOp, NonASAPOp, Operator}; +use asap_types::plan::physical_asap_dag::{PhysicalASAPDAG, PhysicalASAPDAGNode}; +use asap_types::stages::{PhysicalProperties, PruneReason}; +use asap_types::summary_type::ExactKind; +use asap_types::workload::PlanningWorkload; + +// --------------------------------------------------------------------------- +// Workloads. + +/// One repeating PromQL `query` every `interval_ms`, with `requirements` +/// (the inside of the JSON object), over `arrival` and `sources`. +fn workload( + query: &str, + interval_ms: u32, + requirements: &str, + arrival: &str, + sources: &str, +) -> PlanningWorkload { + serde_json::from_str(&format!( + r#"{{"query_workload": {{"language": "promql", "repeating_queries": [ + {{"query": {query:?}, "demand": {{"fixed_interval_at": {{"interval": {interval_ms}, "evaluation_phase": 0}}}}, + "requirements": {{{requirements}}}, "predictability": {{"predictable": {{"known_at": null}}}}}}]}}, + "data_workload": {{"arrival": {arrival}, "sources": {sources}}}}}"# + )) + .unwrap() +} + +const INGESTING_1000: &str = r#"{"ingesting": {"rows_per_second": 1000.0}}"#; +/// The gauge `m`: 1,000 series at 1 Hz. +const GAUGE_M: &str = + r#"{"m": {"series_count": 1000, "metric_type": "gauge", "sample_interval": 1000}}"#; +/// The counter `c`: 1,000 series at 1 Hz. +const COUNTER_C: &str = + r#"{"c": {"series_count": 1000, "metric_type": "counter", "sample_interval": 1000}}"#; + +/// `quantile_over_time(0.99, m[1h])` every 60 s over one series at 10 Hz, +/// with a per-value Rank target of 0.005 at δ = 0.01. One series, so δ is +/// not split per readout value and Pass 2 keeps KLL at k = 547, 1,404 and +/// 2,863 (five physical candidates each). +fn kll_workload() -> PlanningWorkload { + workload( + "quantile_over_time(0.99, m[1h])", + 60_000, + r#""accuracy": {"accuracy_metric": "rank", "max_error": 0.005, "failure_probability": 0.01, "accuracy_scope": "per_value"}"#, + r#"{"ingesting": {"rows_per_second": 10.0}}"#, + r#"{"m": {"series_count": 1, "metric_type": "gauge", "sample_interval": 100}}"#, + ) +} + +/// `sum_over_time(m[5m])` every 300 s over `GAUGE_M`, arriving. +fn sum_workload() -> PlanningWorkload { + workload("sum_over_time(m[5m])", 300_000, "", INGESTING_1000, GAUGE_M) +} + +/// `quantile_over_time(0.5, m[1m])` and `(0.9, m[5m])` every 10 s over +/// `GAUGE_M` (the shared-scan workload of `stage3_objective`). +fn shared_scan_workload() -> PlanningWorkload { + serde_json::from_str(&format!( + r#"{{"query_workload": {{"language": "promql", "repeating_queries": [ + {{"query": "quantile_over_time(0.5, m[1m])", "demand": {{"fixed_interval_at": {{"interval": 10000, "evaluation_phase": 0}}}}, + "requirements": {{}}, "predictability": {{"predictable": {{"known_at": null}}}}}}, + {{"query": "quantile_over_time(0.9, m[5m])", "demand": {{"fixed_interval_at": {{"interval": 10000, "evaluation_phase": 0}}}}, + "requirements": {{}}, "predictability": {{"predictable": {{"known_at": null}}}}}}]}}, + "data_workload": {{"arrival": {INGESTING_1000}, "sources": {GAUGE_M}}}}}"# + )) + .unwrap() +} + +/// `function(c[range])` every 60 s over `COUNTER_C`, arriving. +fn counter_workload(function: &str, range: &str) -> PlanningWorkload { + workload( + &format!("{function}(c[{range}])"), + 60_000, + "", + INGESTING_1000, + COUNTER_C, + ) +} + +// --------------------------------------------------------------------------- +// Planning and reading the result. + +/// The facade's stages over `workload` with `capabilities`. +fn planned(workload: &PlanningWorkload, capabilities: &DeploymentCapabilities) -> PlanningRun { + let entries: Vec<_> = workload.query_workload.entries().collect(); + let data = workload.data_workload.clone().unwrap(); + let roots = lower_promql_roots(workload).unwrap(); + let models = PlanningModels::builtin().with_deployment_capabilities(capabilities); + run_planning_stages_over(roots, &entries, &data, models) + .unwrap() + .run +} + +/// The capabilities of the default deployment plus the caller's +/// `excluded_candidates`. +fn excluding(excluded_candidates: Vec) -> DeploymentCapabilities { + DeploymentCapabilities { + excluded_candidates, + ..Default::default() + } +} + +fn selected(run: &PlanningRun) -> (&PhysicalASAPDAG, &Selection) { + let (plan, selection) = run.selection.as_ref().expect("a plan is selected"); + (plan, selection) +} + +/// The plan's operators and timings, in node order. +fn operators(plan: &PhysicalASAPDAG) -> Vec<(OperatorKind, ExecutionTiming)> { + plan.nodes + .iter() + .map(|node| (OperatorKind::of(&node.payload), node.output_state.timing)) + .collect() +} + +/// The summary type and θ of each state build of the plan, in node order. +fn builds(plan: &PhysicalASAPDAG) -> Vec<(FieldDataType, Option)> { + plan.nodes + .iter() + .filter_map(|node| match &node.payload { + Operator::ASAP( + ASAPOp::SummaryAgg { summary_type, .. } + | ASAPOp::SummaryTumblingWindowChain { summary_type, .. }, + ) => Some((summary_type.clone(), node.parameters.clone())), + _ => None, + }) + .collect() +} + +/// How many of Stage 2's pruned alternatives `source` excluded. +fn pruned_by(run: &PlanningRun, source: ExclusionSource) -> usize { + run.physical_asap_candidates + .as_ref() + .expect("Stage 2 ran") + .pruned_candidates + .iter() + .filter(|pruned| pruned.reason == PruneReason::ExcludedByDeployment(source)) + .count() +} + +/// `node` of `plan` as Stage 2 described its candidate: its payload, +/// `parameters`, `output_state.timing` and `lifetime`, and for a +/// `SummaryEstimate` the state field type of its input node's schema. +fn description_of_plan_node<'a>( + plan: &'a PhysicalASAPDAG, + node: &'a PhysicalASAPDAGNode, +) -> CandidateDescription<'a, NodeId> { + let read_summary_type = match &node.payload { + Operator::ASAP(ASAPOp::SummaryEstimate { summary_input, .. }) => plan + .nodes + .iter() + .find(|state| state.id == *summary_input) + .and_then(|state| state.output_schema.summary_state_type()), + _ => None, + }; + CandidateDescription { + operator: &node.payload, + parameters: node.parameters.as_ref(), + physical_properties: PhysicalProperties::new(node.output_state.timing, node.lifetime) + .expect("a plan node's timing and lifetime go together"), + read_summary_type, + } +} + +/// Whether some node of `plan` matches `exclusion`. +fn some_node_matches(plan: &PhysicalASAPDAG, exclusion: &CandidateExclusion) -> bool { + plan.nodes + .iter() + .any(|node| exclusion.matches(&description_of_plan_node(plan, node))) +} + +/// Asserts the selected plan costs `expected` per second, as observed (six +/// decimals). +fn assert_cost(selection: &Selection, expected: f64) { + let cost = selection.selected_plan_cost_per_second; + assert!( + (cost - expected).abs() <= 5e-7, + "cost {cost} per second, expected {expected}" + ); +} + +/// The one rejection of a run whose deployment left no plan. +fn only_rejection(run: &PlanningRun) -> &asap_planner::ErrorSelectingPlan { + match &run.selection { + Err(SelectionError::Selection(error)) => error, + other => panic!( + "expected no plan, got {:?}", + other.as_ref().map(|(plan, _)| plan) + ), + } +} + +/// Asserts no plan is left and the one rejection is +/// `ExcludedByDeployment`, whose reason contains each of `named`. +fn assert_excluded_by_deployment(run: &PlanningRun, named: &[&str]) { + let ErrorSelectingPlan::NoValidCandidate(rejections) = only_rejection(run) else { + panic!("expected NoValidCandidate, got {:?}", only_rejection(run)); + }; + assert_eq!(rejections.len(), 1, "{rejections:?}"); + assert_eq!(rejections[0].cause, RejectionCause::ExcludedByDeployment); + for name in named { + assert!( + rejections[0].reason.contains(name), + "reason {:?} does not name {name:?}", + rejections[0].reason + ); + } + assert!(!RejectionCause::ExcludedByDeployment.failed_a_check()); +} + +fn kll_at_most(k: u32) -> CandidateExclusion { + CandidateExclusion { + sketch_parameter_range: Some(SketchParameterRange::KllK { + at_least: None, + at_most: Some(k), + }), + ..Default::default() + } +} + +/// The four exclusions of an arm with no query-time scan: no query-time +/// scan, no per-series aggregate, no query-time build or chain. +fn stored_arm() -> Vec { + vec![ + CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::Scan), + ..Default::default() + }, + CandidateExclusion { + operator: Some(OperatorKind::Aggregate), + per_entity_reduction: Some(true), + ..Default::default() + }, + CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::SummaryAgg), + ..Default::default() + }, + CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..Default::default() + }, + ] +} + +const KLL_PLAN: [(OperatorKind, ExecutionTiming); 5] = [ + (OperatorKind::Scan, QueryTime), + (OperatorKind::TimeRange, QueryTime), + (OperatorKind::SummaryAgg, QueryTime), + (OperatorKind::SummaryEstimate, QueryTime), + (OperatorKind::Project, QueryTime), +]; + +fn kll(k: u32) -> (FieldDataType, Option) { + ( + FieldDataType::Sketch(SketchAlgorithm::Kll), + Some(SketchParams::Kll { k }), + ) +} + +// --------------------------------------------------------------------------- +// Caller exclusions. + +/// An exclusion that matches no candidate (no KMV answers a quantile or a +/// sum) changes neither the plan nor its cost, and prunes nothing. +#[test] +fn an_exclusion_matching_nothing_changes_nothing() { + let nothing = excluding(vec![CandidateExclusion { + sketch_parameter_range: Some(SketchParameterRange::KmvK { + at_least: None, + at_most: Some(106_263), + }), + ..Default::default() + }]); + for workload in [kll_workload(), sum_workload(), shared_scan_workload()] { + let default = planned(&workload, &DeploymentCapabilities::default()); + let restricted = planned(&workload, ¬hing); + let (default_plan, default_selection) = selected(&default); + let (plan, selection) = selected(&restricted); + assert_eq!(plan, default_plan); + assert_eq!( + selection.selected_plan_cost_per_second, + default_selection.selected_plan_cost_per_second + ); + assert_eq!( + pruned_by(&restricted, ExclusionSource::ExcludedCandidate { index: 0 }), + 0 + ); + } +} + +/// The answer-10 example: a KLL `k` range moves the quantile's state from +/// k = 547 to k = 1,404, and to 2,863 when 1,404 is excluded too; the +/// plan's shape stays and its cost never falls as more is excluded. +#[test] +fn a_kll_k_range_moves_the_quantile_from_k_547_to_k_1404() { + let workload = kll_workload(); + let cases = [ + (None, 547, 0.060946), + (Some(kll_at_most(1403)), 1404, 0.061518), + (Some(kll_at_most(2862)), 2863, 0.062491), + ]; + for (exclusion, k, cost) in cases { + let run = planned(&workload, &excluding(exclusion.iter().cloned().collect())); + let (plan, selection) = selected(&run); + assert_eq!(operators(plan), KLL_PLAN, "k = {k}"); + assert_eq!(builds(plan), vec![kll(k)]); + assert_cost(selection, cost); + if let Some(exclusion) = &exclusion { + assert!(!some_node_matches(plan, exclusion), "k = {k}"); + } + } +} + +/// Excluding every KLL size, by family or by a range covering the largest, +/// leaves the exact per-series quantile, at a higher cost. +#[test] +fn excluding_every_kll_size_selects_a_plan_without_kll() { + let workload = kll_workload(); + let by_family = CandidateExclusion { + summary_family: Some(SummaryFamily::Sketch(SketchAlgorithm::Kll)), + ..Default::default() + }; + for exclusion in [by_family, kll_at_most(2863)] { + let run = planned(&workload, &excluding(vec![exclusion.clone()])); + let (plan, selection) = selected(&run); + assert_eq!( + operators(plan), + [ + (OperatorKind::Scan, QueryTime), + (OperatorKind::TimeRange, QueryTime), + (OperatorKind::Aggregate, QueryTime), + ] + ); + assert!(matches!( + &plan.nodes[2].payload, + Operator::NonASAP(NonASAPOp::Aggregate { reduction: Reduction::PerEntity, measures, .. }) + if measures == &[AggIntent::Quantile { col: None, q: 0.99 }] + )); + assert_eq!(builds(plan), vec![]); + assert_cost(selection, 0.072584); + assert!(!some_node_matches(plan, &exclusion)); + } +} + +/// An arm with no query-time scan: without query-time scans, per-series +/// aggregates and query-time builds, the sum is read from an ingestion-time +/// chain of exact sums; eight candidates are excluded. +#[test] +fn the_stored_arm_exclusions_select_an_ingestion_time_chain() { + let workload = sum_workload(); + let unrestricted = planned(&workload, &DeploymentCapabilities::default()); + let (plan, selection) = selected(&unrestricted); + assert_eq!( + operators(plan), + [ + (OperatorKind::Scan, QueryTime), + (OperatorKind::TimeRange, QueryTime), + (OperatorKind::Aggregate, QueryTime), + ] + ); + assert_cost(selection, 0.060534); + + let stored = planned(&workload, &excluding(stored_arm())); + let (plan, selection) = selected(&stored); + assert_eq!( + operators(plan), + [ + (OperatorKind::Scan, IngestionTime), + (OperatorKind::SummaryTumblingWindowChain, IngestionTime), + (OperatorKind::TimeRange, QueryTime), + (OperatorKind::SummaryMerge, QueryTime), + (OperatorKind::FinalizeExactAccumulator, QueryTime), + ] + ); + assert_eq!( + builds(plan), + vec![(FieldDataType::exact(ExactKind::Sum), None)] + ); + assert_cost(selection, 0.113237); + let excluded: usize = (0..4) + .map(|index| pruned_by(&stored, ExclusionSource::ExcludedCandidate { index })) + .sum(); + assert_eq!(excluded, 8); +} + +/// Data at rest has no ingestion pipeline, so only query-time scans can +/// feed the sum. Excluding them leaves no plan: the rejection is +/// `ExcludedByDeployment`, naming the exclusion and the two candidates it +/// pruned, never a plan with a scan, and never the generic `Infeasible`. +#[test] +fn an_excluded_candidate_is_never_selected_even_when_it_is_the_only_feasible_one() { + let workload = workload( + "sum_over_time(m[5m])", + 300_000, + "", + r#""at_rest""#, + r#"{"m": {"series_count": 1000, "metric_type": "gauge", "sample_interval": 1000, "rows_held": 300000000}}"#, + ); + let unrestricted = planned(&workload, &DeploymentCapabilities::default()); + let (plan, selection) = selected(&unrestricted); + assert_eq!(operators(plan)[0], (OperatorKind::Scan, QueryTime)); + assert_cost(selection, 0.060534); + + let no_scan = planned( + &workload, + &excluding(vec![CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::Scan), + ..Default::default() + }]), + ); + assert_eq!( + pruned_by(&no_scan, ExclusionSource::ExcludedCandidate { index: 0 }), + 2 + ); + assert_excluded_by_deployment( + &no_scan, + &[ + "excluded_candidates[0] (2 candidates)", + "may be infeasible without", + ], + ); +} + +/// Stage 2 records each matched build with the caller's exclusion, by its +/// index: the five KLL k = 547 alternatives, then the ten at k = 547 and +/// 1,404. None is left for Stage 3 to report as not costable, and nothing +/// is excluded without an exclusion. +#[test] +fn excluded_candidates_are_pruned_in_stage2_with_their_index() { + let workload = kll_workload(); + for (exclusions, count) in [ + (vec![], 0), + (vec![kll_at_most(1403)], 5), + (vec![kll_at_most(2862)], 10), + ] { + let run = planned(&workload, &excluding(exclusions)); + assert_eq!( + pruned_by(&run, ExclusionSource::ExcludedCandidate { index: 0 }), + count + ); + let (_, selection) = selected(&run); + assert!(selection + .pruned_candidates + .iter() + .all(|pruned| pruned.reason != PruneReason::UsageNotCostable)); + } +} + +/// The exclusions reach Stage 2 through `PlanningModels` with the +/// deployment's other capabilities: the same run through +/// `run_planning_stages_over` honours `DeploymentCapabilities::validate`, +/// so an exclusion that sets no field is refused before planning. +#[test] +fn an_exclusion_setting_no_field_is_refused_before_planning() { + let run = planned( + &kll_workload(), + &excluding(vec![CandidateExclusion::default()]), + ); + assert!( + matches!( + run.selection, + Err(SelectionError::InvalidDeploymentCapabilities( + asap_types::deployment_capabilities::DeploymentCapabilitiesError::InvalidExclusion { + index: 0, + .. + } + )) + ), + "{:?}", + run.selection.as_ref().map(|(plan, _)| plan) + ); +} + +// --------------------------------------------------------------------------- +// Capabilities a target may lack (the new dimensions). + +/// A target without mergeable rate state: `rate(c[5m])` no longer reads an +/// ingestion-time chain of rate states merged across windows, but builds +/// and finalizes the rate state within each evaluation. `increase` the +/// same with its own state. No node of the new plans keeps a counter state +/// across windows. +#[test] +fn a_target_without_mergeable_rate_state_builds_rate_within_one_evaluation() { + let not_mergeable = DeploymentCapabilities { + state_not_mergeable_across_windows: vec![ + SummaryFamily::Exact(ExactKind::Rate), + SummaryFamily::Exact(ExactKind::Increase), + ], + ..Default::default() + }; + // A counter state merged across windows: a chain of it, or a build of + // it kept across evaluations. + let merged_state = |kind| { + [ + CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(kind)), + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..Default::default() + }, + CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(kind)), + kept_across_evaluations: Some(true), + ..Default::default() + }, + ] + }; + let cases = [ + ("rate", "5m", ExactKind::Rate, 0.279284, 0.367671), + ("increase", "1h", ExactKind::Increase, 1.490206, 3.953715), + ]; + for (function, range, kind, unrestricted_cost, restricted_cost) in cases { + let workload = counter_workload(function, range); + let unrestricted = planned(&workload, &DeploymentCapabilities::default()); + let (plan, selection) = selected(&unrestricted); + assert_eq!( + operators(plan), + [ + (OperatorKind::Scan, IngestionTime), + (OperatorKind::SummaryTumblingWindowChain, IngestionTime), + (OperatorKind::TimeRange, QueryTime), + (OperatorKind::SummaryMerge, QueryTime), + (OperatorKind::FinalizeExactAccumulator, QueryTime), + ], + "{function}" + ); + assert_eq!(builds(plan), vec![(FieldDataType::exact(kind), None)]); + assert_cost(selection, unrestricted_cost); + + let restricted = planned(&workload, ¬_mergeable); + let (plan, selection) = selected(&restricted); + assert_eq!( + operators(plan), + [ + (OperatorKind::Scan, QueryTime), + (OperatorKind::TimeRange, QueryTime), + (OperatorKind::SummaryAgg, QueryTime), + (OperatorKind::FinalizeExactAccumulator, QueryTime), + ], + "{function}" + ); + assert_eq!(builds(plan), vec![(FieldDataType::exact(kind), None)]); + assert_cost(selection, restricted_cost); + for merged in merged_state(kind) { + assert!(!some_node_matches(plan, &merged), "{function}"); + } + assert_eq!( + pruned_by(&restricted, ExclusionSource::StateNotMergeableAcrossWindows), + 3, + "{function}" + ); + } +} + +/// Why an aggregate's measure is a dimension of its own: excluding every +/// rate state alone lets the planner rebuild the query-time rate as a +/// per-series `Aggregate[rate]` over raw rows; excluding that measure too +/// leaves no plan, reported as excluded by the deployment. +#[test] +fn excluding_rate_state_alone_rebuilds_it_as_an_aggregate_unless_its_measure_is_excluded() { + let workload = counter_workload("rate", "5m"); + let rate_state = CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(ExactKind::Rate)), + ..Default::default() + }; + let state_only = planned(&workload, &excluding(vec![rate_state.clone()])); + let (plan, selection) = selected(&state_only); + assert_eq!( + operators(plan), + [ + (OperatorKind::Scan, QueryTime), + (OperatorKind::TimeRange, QueryTime), + (OperatorKind::Aggregate, QueryTime), + ] + ); + assert!(matches!( + &plan.nodes[2].payload, + Operator::NonASAP(NonASAPOp::Aggregate { reduction: Reduction::PerEntity, measures, .. }) + if measures == &[AggIntent::Rate] + )); + assert_cost(selection, 0.447669); + assert_eq!( + pruned_by(&state_only, ExclusionSource::ExcludedCandidate { index: 0 }), + 5 + ); + + let query_time_rate = CandidateExclusion { + timing: Some(QueryTime), + aggregate_measure: Some("rate".to_string()), + ..Default::default() + }; + let neither = planned(&workload, &excluding(vec![rate_state, query_time_rate])); + assert_excluded_by_deployment( + &neither, + &["excluded_candidates[0]", "excluded_candidates[1]"], + ); +} + +/// A target whose counter functions do not extrapolate plans no `rate` +/// (every rate state and `Aggregate[rate]` needs extrapolation), but plans +/// `irate` as before; one that does not handle counter resets plans +/// neither. +#[test] +fn counter_semantics_a_target_lacks_rule_out_the_functions_that_need_them() { + let without = |reset_handling, extrapolation| DeploymentCapabilities { + counter_semantics: CounterSemanticsSupport { + reset_handling, + extrapolation, + }, + ..Default::default() + }; + let rate = counter_workload("rate", "5m"); + let irate = counter_workload("irate", "5m"); + + let no_extrapolation = planned(&rate, &without(true, false)); + assert_eq!( + pruned_by(&no_extrapolation, ExclusionSource::CounterNotExtrapolated), + 7 + ); + assert_excluded_by_deployment( + &no_extrapolation, + &["counter_not_extrapolated (7 candidates)"], + ); + + let default_irate = planned(&irate, &DeploymentCapabilities::default()); + let irate_without_extrapolation = planned(&irate, &without(true, false)); + let (default_plan, _) = selected(&default_irate); + let (plan, selection) = selected(&irate_without_extrapolation); + assert_eq!(plan, default_plan); + assert_eq!( + builds(plan), + vec![(FieldDataType::exact(ExactKind::IRate), None)] + ); + assert_cost(selection, 0.367671); + assert_eq!( + pruned_by( + &irate_without_extrapolation, + ExclusionSource::CounterNotExtrapolated + ), + 0 + ); + + let irate_without_resets = planned(&irate, &without(false, true)); + assert_eq!( + pruned_by( + &irate_without_resets, + ExclusionSource::CounterResetsNotHandled + ), + 4 + ); + assert_excluded_by_deployment(&irate_without_resets, &["counter_resets_not_handled"]); + let rate_without_resets = planned(&rate, &without(false, true)); + assert_excluded_by_deployment(&rate_without_resets, &["counter_resets_not_handled"]); +} diff --git a/crates/integration-tests/tests/main.rs b/crates/integration-tests/tests/main.rs index b650d32e6..43d25116d 100644 --- a/crates/integration-tests/tests/main.rs +++ b/crates/integration-tests/tests/main.rs @@ -11,6 +11,7 @@ mod aggregate; mod binary_op; mod crate_graph; mod default_cost_plan_ranking; +mod deployment_exclusions; mod exact_reduce_execution; mod filtered_aggregates; mod finer_aggregate_reuse; diff --git a/crates/integration-tests/tests/pass1_candidates.rs b/crates/integration-tests/tests/pass1_candidates.rs index 81614f9cd..8858d0f14 100644 --- a/crates/integration-tests/tests/pass1_candidates.rs +++ b/crates/integration-tests/tests/pass1_candidates.rs @@ -92,7 +92,7 @@ fn stage0(root: QueryRoot) -> Memo { /// Pass 1's memo of the one query `root`. fn pass1(root: QueryRoot) -> Memo { - pass1_memo(stage0(root), None).unwrap() + pass1_memo(stage0(root), &[]).unwrap() } /// The one `Aggregate` group of `memo`. @@ -107,7 +107,7 @@ fn root_group(memo: &Memo) -> MemoGroupId { /// have. Each outputs its group's schema, or `Memo::add_candidate` would /// have rejected it and Pass 1 failed. fn candidates_of_aggregates(label: &str, root: QueryRoot) -> usize { - let memo = pass1_memo(stage0(root), None).unwrap_or_else(|e| panic!("{label}: {e}")); + let memo = pass1_memo(stage0(root), &[]).unwrap_or_else(|e| panic!("{label}: {e}")); aggregate_groups(&memo) .iter() .map(|group| memo.groups()[group.0 as usize].candidates.len()) @@ -624,7 +624,7 @@ async fn an_unsupported_way_under_a_key_only_having_adds_no_group() { .await .unwrap(); let stage0 = stage0(QueryRoot::Operator(root)); - let memo = pass1_memo(stage0.clone(), None).unwrap(); + let memo = pass1_memo(stage0.clone(), &[]).unwrap(); assert_eq!(memo.groups().len(), stage0.groups().len()); assert!(memo .groups() @@ -643,7 +643,7 @@ async fn a_multi_measure_aggregates_part_is_the_equal_stage0_group() { ]; let stage0 = asap_stage0_memo::memo_of_queries(&roots, &[None, None], &DataWorkload::default()).unwrap(); - let memo = pass1_memo(stage0, None).unwrap(); + let memo = pass1_memo(stage0, &[]).unwrap(); let counts = memo .groups() .iter() diff --git a/crates/planner/src/installable/tests.rs b/crates/planner/src/installable/tests.rs index 5e5025c40..1386370a5 100644 --- a/crates/planner/src/installable/tests.rs +++ b/crates/planner/src/installable/tests.rs @@ -307,7 +307,16 @@ fn unrestricted_summaries_default_to_the_executors_families() { Some(asap_executor::supported_summary_families()) ); assert!(!defaulted.raw_data_retained); - assert!(!defaulted.supports(&SketchAlgorithm::CountSketch, StatisticKind::ItemFrequency)); + // The executor does not answer a Count Sketch's item frequency. + assert!(!defaulted + .supported_summaries + .as_ref() + .unwrap() + .iter() + .any(|s| { + s.summary_type == SketchAlgorithm::CountSketch + && s.readouts.contains(&StatisticKind::ItemFrequency) + })); let kll_only = DeploymentCapabilities { supported_summaries: Some(vec![SupportedSummary { summary_type: SketchAlgorithm::Kll, diff --git a/crates/planner/src/lib.rs b/crates/planner/src/lib.rs index cc9b7afa5..b7b0cf9ce 100644 --- a/crates/planner/src/lib.rs +++ b/crates/planner/src/lib.rs @@ -68,7 +68,10 @@ pub use asap_frontend_sql::SqlCatalog; pub use asap_stage3_plan_selection::{ AcceptedAccuracy, ErrorSelectingPlan, RejectionCause, Selection, }; -pub use asap_types::deployment_capabilities::{DeploymentCapabilities, SupportedSummary}; +pub use asap_types::deployment_capabilities::{ + CandidateExclusion, CounterSemanticsSupport, DeploymentCapabilities, ExclusionSource, + SketchReadout, SupportedSummary, +}; pub use asap_types::ir::properties::selection::{ Constraint, IntervalConstraintLimit, SelectionBox, }; @@ -79,7 +82,9 @@ pub use asap_types::plan::materialized_view::{ }; pub use asap_types::plan::physical_asap_dag::{PhysicalASAPDAG, PhysicalASAPNodeId, ViewCoverage}; pub use asap_types::plan::TimeWindow; -pub use asap_types::summary_type::{SketchAlgorithm, SketchParams, StatisticKind}; +pub use asap_types::summary_type::{ + SketchAlgorithm, SketchParameterRange, SketchParams, StatisticKind, SummaryFamily, +}; pub use asap_types::workload::PlanningWorkload; // ── Input ──────────────────────────────────────────────────────────────── diff --git a/crates/planner/src/run.rs b/crates/planner/src/run.rs index 2caf7e752..e7fa25790 100644 --- a/crates/planner/src/run.rs +++ b/crates/planner/src/run.rs @@ -106,15 +106,13 @@ pub fn run_planning( }) .collect(); let initial = memo_of_queries(&roots, &accuracy_targets, data)?; - // Pass 1: the initial candidates the deployment can run. A query Pass 1 - // cannot plan is an input error. - let pass1 = pass1_memo( - initial, - models - .deployment_capabilities - .supported_summaries - .as_deref(), - )?; + // The deployment's capabilities as exclusions, expanded once for Pass 1 + // and Stage 2. + let exclusions = models.deployment_capabilities.exclusions(); + // Pass 1: the initial candidates, without the summaries the deployment + // excludes outright (Stage 2 prunes the rest it cannot run). A query + // Pass 1 cannot plan is an input error. + let pass1 = pass1_memo(initial, &exclusions)?; let mut report = PlanningReport { pass1_ms: elapsed_ms(started), ..PlanningReport::default() @@ -143,8 +141,7 @@ pub fn run_planning( .sum(); // Stage 2. let started = Instant::now(); - let physical = - generate_physical_asap_memo_candidates(logical, data, models.deployment_capabilities); + let physical = generate_physical_asap_memo_candidates(logical, data, &exclusions); report.stage2_ms = elapsed_ms(started); let physical = physical_asap_candidates.insert(physical); report.physical_candidates = physical.physical_candidates.len(); diff --git a/crates/planner/tests/deployment_exclusions.rs b/crates/planner/tests/deployment_exclusions.rs new file mode 100644 index 000000000..6dcbdc39b --- /dev/null +++ b/crates/planner/tests/deployment_exclusions.rs @@ -0,0 +1,81 @@ +//! The deployment's exclusions reach Stage 2 through the facade: a caller +//! of `plan_installable` or `e2e_plan` passes them in +//! `PlanningModels::deployment_capabilities`, beside the executor's +//! summaries the facade fills in. + +use asap_planner::{ + e2e_plan, plan_installable, CandidateExclusion, DeploymentCapabilities, FrontendInput, + PhysicalASAPDAG, PlanningModels, PlanningWorkload, SketchParameterRange, SketchParams, + UserInput, +}; +use asap_types::ir::{ASAPOp, Operator}; + +/// `quantile_over_time(0.99, m[1h])` every 60 s over one series at 10 Hz, +/// with a per-value Rank target of 0.005 at δ = 0.01: planned with KLL at +/// k = 547 by default. +fn kll_workload() -> PlanningWorkload { + serde_json::from_str( + r#"{"query_workload": {"language": "promql", "repeating_queries": [ + {"query": "quantile_over_time(0.99, m[1h])", "demand": {"fixed_interval_at": {"interval": 60000, "evaluation_phase": 0}}, + "requirements": {"accuracy": {"accuracy_metric": "rank", "max_error": 0.005, "failure_probability": 0.01, "accuracy_scope": "per_value"}}, + "predictability": {"predictable": {"known_at": null}}}]}, + "data_workload": {"arrival": {"ingesting": {"rows_per_second": 10.0}}, + "sources": {"m": {"series_count": 1, "metric_type": "gauge", "sample_interval": 100}}}}"#, + ) + .unwrap() +} + +/// The θ of each `SummaryAgg` of `dag`. +fn summary_agg_parameters(dag: &PhysicalASAPDAG) -> Vec> { + dag.nodes + .iter() + .filter(|node| matches!(node.payload, Operator::ASAP(ASAPOp::SummaryAgg { .. }))) + .map(|node| node.parameters.clone()) + .collect() +} + +/// Excluding KLL at k ≤ 1,403 moves the installable plan's KLL from +/// k = 547 to k = 1,404, and `e2e_plan` with the same models selects the +/// same; without the exclusion it stays at k = 547. +#[tokio::test] +async fn exclusions_reach_stage2_through_plan_installable() { + let workload = kll_workload(); + let capabilities = DeploymentCapabilities { + excluded_candidates: vec![CandidateExclusion { + sketch_parameter_range: Some(SketchParameterRange::KllK { + at_least: None, + at_most: Some(1403), + }), + ..Default::default() + }], + ..Default::default() + }; + let restricted = PlanningModels::builtin().with_deployment_capabilities(&capabilities); + let (installable, _) = + plan_installable(UserInput::new(&workload, FrontendInput::Promql, restricted)) + .await + .expect("plans"); + assert_eq!( + summary_agg_parameters(&installable.dag), + vec![Some(SketchParams::Kll { k: 1404 })] + ); + let output = e2e_plan(UserInput::new(&workload, FrontendInput::Promql, restricted)) + .await + .expect("plans"); + assert_eq!( + summary_agg_parameters(&output.plan), + vec![Some(SketchParams::Kll { k: 1404 })] + ); + + let (unrestricted, _) = plan_installable(UserInput::new( + &workload, + FrontendInput::Promql, + PlanningModels::builtin(), + )) + .await + .expect("plans"); + assert_eq!( + summary_agg_parameters(&unrestricted.dag), + vec![Some(SketchParams::Kll { k: 547 })] + ); +} diff --git a/crates/planner/tests/main.rs b/crates/planner/tests/main.rs index d72a470e7..db365b856 100644 --- a/crates/planner/tests/main.rs +++ b/crates/planner/tests/main.rs @@ -5,6 +5,7 @@ mod time_series; mod columnar_batches; +mod deployment_exclusions; mod e2e_plan; mod exact_only_reads; mod metricsql_workloads; diff --git a/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs b/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs index 9e2b5751a..2cd678f26 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs @@ -14,6 +14,7 @@ //! The input must be a logical memo: a group whose expression is an ASAP //! operator is rejected. No cost model and no accuracy target is read. +use asap_types::deployment_capabilities::{DeploymentExclusion, SketchReadout}; use asap_types::ir::operator::arguments::Reduction; use asap_types::ir::operator::arguments::Source; use asap_types::ir::operator::non_asap::any_measure_filtered; @@ -23,11 +24,10 @@ use asap_types::ir::schema::{ColumnId, Schema}; use asap_types::ir::{NonASAPOp, Operator, OperatorResultKind, ScalarExpr}; use asap_types::stages::{Memo, MemoGroupId}; use asap_types::summary_type::{ - ExactKind, SketchAlgorithm, SketchStatistic, StatisticKind, SummaryInputExpr, SummaryUpdate, + ExactKind, SketchAlgorithm, SketchStatistic, StatisticKind, SummaryFamily, SummaryInputExpr, + SummaryUpdate, }; -use asap_types::deployment_capabilities::{summary_supported, SupportedSummary}; - use crate::candidates::having::has_having; use crate::summary_realization::{realize_keyed_additive_summary_input, summary_candidates}; use crate::{expression, schema, PerComputationCandidateError}; @@ -84,9 +84,9 @@ pub(crate) struct FusedComputation { /// the groups any of these targets' own fused computations replace. pub absorbed_groups: Vec, /// How the fused computation is computed: by an exact accumulator or a - /// summary. Empty - /// when Pass 1 pruned every one (today only for an algorithm the deployment - /// does not support); the fusion is then not offered. + /// summary. Empty when Pass 1 skipped every one (today only for a sketch + /// algorithm the deployment excludes outright); the fusion is then not + /// offered. pub ways_to_compute: Vec, } @@ -142,15 +142,14 @@ fn nullable_avg_input(input: &Schema, intent: &AggIntent) -> bool { /// Pass 1 walks the groups, so an aggregate several queries read is one /// target per measure. An aggregate measure is eligible when it has a /// realization besides exact execution, even if every such realization is -/// pruned. The summaries the deployment does not support -/// (`supported_summaries`, the deployment's -/// `DeploymentCapabilities::supported_summaries`; `None` supports every -/// one) are dropped: a target's own, and a fused computation's (with all -/// of them dropped, the fusion is not offered). Measure filters and -/// `HAVING` keep every candidate. +/// pruned. A summary whose sketch algorithm, or the readout the measure +/// reads from it, one of the deployment's `exclusions` rules out outright +/// is skipped ([`without_excluded_summaries`]); Stage 2 prunes the rest the +/// deployment cannot run. Measure filters and `HAVING` +/// keep every candidate. pub(crate) fn computation_targets( memo: &Memo, - supported_summaries: Option<&[SupportedSummary]>, + exclusions: &[DeploymentExclusion], ) -> Result, PerComputationCandidateError> { if memo .groups() @@ -199,37 +198,60 @@ pub(crate) fn computation_targets( prune_topk_heaps_over_one_row_per_item(memo, &mut targets); add_nested_distributive_targets(memo, &mut targets); close_absorptions(&mut targets); - without_unsupported_summaries(memo, &mut targets, supported_summaries); + without_excluded_summaries(memo, &mut targets, exclusions); Ok(targets) } -/// Drops from `targets` the summary candidates the executor does not -/// support (`supported_summaries`; `None` supports every one): a target's -/// own, and its fused computation's. The readout is the statistic the -/// measure's estimate reads (the outer measure's for a fused computation). -fn without_unsupported_summaries( +/// Drops from `targets`, and from their fused computations, each summary +/// Stage 2 would prune every build of, or every readout of for the +/// measure: its sketch algorithm is excluded outright +/// (`CandidateExclusion::family_excluded_outright`), or the statistic the +/// measure reads from it is (`CandidateExclusion::readout_excluded_outright`; +/// the outer measure's for a fused computation). E.g. under +/// `supported_summaries: []` a quantile keeps no summary, only its exact +/// expression, and with KLL listed without its `Quantile` readout a +/// quantile keeps no KLL. A narrower exclusion (KLL tumbling-window chains +/// only) keeps the summary: Stage 2 decides per candidate. Exact +/// accumulators are left to Stage 2 too. +fn without_excluded_summaries( memo: &Memo, targets: &mut [ComputationTarget], - supported_summaries: Option<&[SupportedSummary]>, + exclusions: &[DeploymentExclusion], ) { + let families: Vec = exclusions + .iter() + .filter_map(|exclusion| exclusion.exclusion.family_excluded_outright()) + .collect(); + let readouts: Vec = exclusions + .iter() + .filter_map(|exclusion| exclusion.exclusion.readout_excluded_outright()) + .collect(); + if families.is_empty() && readouts.is_empty() { + return; + } for target in targets.iter_mut() { - let Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) = - expression(memo, target.aggregate_group) - else { - continue; - }; - let Some(readout) = - SketchStatistic::for_intent(&measures[target.measure_index]).map(|s| s.kind()) - else { - continue; + let read_statistic = match expression(memo, target.aggregate_group) { + Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) => { + SketchStatistic::for_intent(&measures[target.measure_index]) + .map(|statistic| statistic.kind()) + } + _ => None, }; - let unsupported = |candidate: &HowToComputeAggregateMeasure| { - matches!(candidate, HowToComputeAggregateMeasure::Summary(algorithm) - if !summary_supported(supported_summaries, algorithm, readout)) + let excluded = |way: &HowToComputeAggregateMeasure| { + let HowToComputeAggregateMeasure::Summary(algorithm) = way else { + return false; + }; + families.contains(&SummaryFamily::Sketch(*algorithm)) + || read_statistic.is_some_and(|statistic| { + readouts.contains(&SketchReadout { + summary_type: *algorithm, + statistic, + }) + }) }; - target.ways_to_compute.retain(|way| !unsupported(way)); + target.ways_to_compute.retain(|way| !excluded(way)); if let Some(fused) = &mut target.fused_computation { - fused.ways_to_compute.retain(|way| !unsupported(way)); + fused.ways_to_compute.retain(|way| !excluded(way)); } } } diff --git a/crates/stage1-pass1-per-computation-candidates/src/lib.rs b/crates/stage1-pass1-per-computation-candidates/src/lib.rs index 9a5ffbe82..0da74abde 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/lib.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/lib.rs @@ -33,7 +33,7 @@ mod test_fixtures; #[cfg(test)] mod tests; -use asap_types::deployment_capabilities::SupportedSummary; +use asap_types::deployment_capabilities::DeploymentExclusion; use asap_types::ir::schema::Schema; use asap_types::ir::{Operator, SchemaDerivationError}; use asap_types::stages::{CandidateError, Memo, MemoGroupError, MemoGroupId}; @@ -66,10 +66,13 @@ pub enum 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 +/// execution, skips each summary whose sketch algorithm, or the readout +/// the measure reads from it, one of the deployment's `exclusions` +/// (`DeploymentCapabilities::exclusions`) rules out outright (e.g. every +/// KLL build when the executor does not list KLL, or a quantile's KLL when +/// it lists KLL without `Quantile`; Stage 2 prunes the rest the deployment +/// cannot run), and adds each way to +/// compute a group as candidates, through /// `Memo::find_or_add_group` and `Memo::add_candidate`: every group's own /// expression, exact accumulators, one summary build per configuration of /// the algorithm's predefined list with separate readouts, and fused builds. @@ -77,9 +80,9 @@ pub enum PerComputationCandidateError { /// accuracy and eliminates the candidates no query can use. pub fn pass1_memo( mut memo: Memo, - supported_summaries: Option<&[SupportedSummary]>, + exclusions: &[DeploymentExclusion], ) -> Result { - let targets = computation_targets(&memo, supported_summaries)?; + let targets = computation_targets(&memo, exclusions)?; add_pass1_candidates(&mut memo, &targets)?; Ok(memo) } diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/candidates.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/candidates.rs index 807085b80..170965ba5 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/candidates.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/candidates.rs @@ -19,7 +19,7 @@ fn every_group_offers_its_own_expression() { let s = aggregate_group(&mut memo, rows, Reduction::by(vec![2]), vec![sum()], None); query(&mut memo, s, None); let stage0 = memo.groups().len(); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); for index in 0..stage0 { let group = &memo.groups()[index]; let own = &group.candidates[0]; @@ -37,7 +37,7 @@ fn exact_accumulator_is_a_state_group_and_a_finalize() { let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); let s = aggregate_group(&mut memo, rows, Reduction::by(vec![2]), vec![sum()], None); query(&mut memo, s, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let states = groups_where(&memo, |e| { matches!( e, @@ -103,7 +103,7 @@ fn multi_measure_candidate_joins_single_measure_groups() { None, ); query(&mut memo, both, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let single = groups_where( &memo, |e| matches!(e, Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) if measures.len() == 1), @@ -150,7 +150,7 @@ fn pass1_sets_no_input_requirement() { ); query(&mut memo, ranked, None); query(&mut memo, p, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); // The top-k readout is offered, and has no input requirement either. assert!(!groups_where(&memo, |e| matches!( e, diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/fused.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/fused.rs index ac0dc7033..32b9ec573 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/fused.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/fused.rs @@ -36,7 +36,7 @@ fn whole_expression_topk_heaps_read_the_raw_samples() { None, ); query(&mut memo, ranked, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); for algorithm in [ SketchAlgorithm::CmsWithHeap, SketchAlgorithm::CountSketchWithHeap, @@ -87,7 +87,7 @@ fn whole_expression_topk_heap_candidates() { None, ); query(&mut memo, ranked, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); // The top-k group's own expression, then one ranked `Project` per heap. let ranked_candidates = candidates_of(&memo, ranked); let kinds: Vec<&str> = ranked_candidates @@ -149,7 +149,7 @@ fn count_ranked_topk_counts_with_unit_weight() { None, ); query(&mut memo, ranked, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let (_, update) = state_group(&memo, SketchAlgorithm::CmsWithHeap); assert_eq!(update.weight, SummaryInputExpr::Constant(1.0)); } @@ -176,7 +176,7 @@ fn ranked_item_is_the_keys_outside_the_partition() { None, ); query(&mut memo, ranked, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let (_, update) = state_group(&memo, SketchAlgorithm::CountSketchWithHeap); assert_eq!( update.item, diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/having.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/having.rs index 2e1a97802..5ee6a0aa5 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/having.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/having.rs @@ -55,7 +55,7 @@ fn key_only_having_is_pushed_below_into_the_filter_group() { ); query(&mut memo, having, None); query(&mut memo, by_job, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let below = pushed_below(&memo, rows); assert_eq!(below.len(), 1, "{}", memo_printout(&memo)); // The Filter group: its own expression, then one readout per algorithm @@ -83,7 +83,7 @@ fn value_having_stays_above() { compare(1, CompareOpKind::Gt, ScalarValue::Float64(10.0)), ); query(&mut memo, having, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); assert!(pushed_below(&memo, rows).is_empty()); assert_eq!(candidates_of(&memo, having).len(), 1); } @@ -107,7 +107,7 @@ fn global_aggregate_having_stays_above() { Predicate(ScalarExpr::Literal(ScalarValue::Boolean(false))), ); query(&mut memo, having, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); assert!(pushed_below(&memo, rows).is_empty()); } @@ -173,7 +173,7 @@ fn a_constant_having_of_a_grouped_aggregate_is_pushed_below() { }), ); query(&mut memo, having, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); assert_eq!( pushed_below(&memo, rows).len(), 1, @@ -197,7 +197,7 @@ fn own_value_having_filters_each_readout() { Some(compare(1, CompareOpKind::Gt, ScalarValue::Float64(10.0))), ); query(&mut memo, by_job, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let kinds: Vec<&str> = candidates_of(&memo, by_job) .iter() .map(|c| c.expression.operator.kind_name()) diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/nested_merges.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/nested_merges.rs index d89e4d733..56e2e570e 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/nested_merges.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/nested_merges.rs @@ -39,7 +39,7 @@ fn nested_distributive_aggregate_merges_into_the_outer_state_group() { None, ); query(&mut memo, by_job, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let outer_state = groups_where( &memo, |e| matches!(e, Operator::ASAP(ASAPOp::SummaryAgg { child, summary_type: FieldDataType::ExactAggregate(state, _), .. }) if *child == per_series && *state == kind), @@ -77,7 +77,7 @@ fn nested_merge_needs_the_same_distributive_aggregate() { None, ); query(&mut memo, by_job, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); assert!(memo .groups() .iter() diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/running_example.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/running_example.rs index b22c9dadd..f2a56611c 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/running_example.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/running_example.rs @@ -56,7 +56,7 @@ fn running_example_gives_one_build_per_theta_and_separate_readouts() { ); query(&mut memo, g3, None); query(&mut memo, g6, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); println!("{}", memo_printout(&memo)); let (kll, _) = state_group(&memo, SketchAlgorithm::Kll); let (ddsketch, _) = state_group(&memo, SketchAlgorithm::DDSketch); diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/series_identity.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/series_identity.rs index 54913a895..fac983083 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/series_identity.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/series_identity.rs @@ -28,7 +28,7 @@ fn per_series_readouts_keep_the_series_identity() { None, ); query(&mut memo, per_series, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let output = &memo.groups()[per_series.0 as usize].group_properties.schema; assert!(output.closed && output.has_promql_series_identity()); let readouts = &candidates_of(&memo, per_series)[1..]; @@ -81,7 +81,7 @@ fn an_open_per_series_aggregate_offers_no_renamed_readout() { None, ); query(&mut memo, per_series, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); assert!( !memo.groups()[per_series.0 as usize] .group_properties diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/targets.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/targets.rs index e72f2bacd..1e61cd80d 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/targets.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/targets.rs @@ -2,13 +2,19 @@ use super::{quantile, selector, sum}; use crate::computation_targets::computation_targets; use crate::test_fixtures::aggregate_group; use crate::{pass1_memo, PerComputationCandidateError}; +use asap_types::deployment_capabilities::{ + CandidateExclusion, DeploymentCapabilities, DeploymentExclusion, ExclusionSource, + SupportedSummary, +}; use asap_types::ir::operator::arguments::Reduction; use asap_types::ir::operator::AggIntent; use asap_types::ir::scalar::ColumnRef; use asap_types::ir::schema::FieldDataType; use asap_types::ir::{ASAPOp, Operator, TimeRangeKind}; use asap_types::stages::{Memo, MemoGroupId}; -use asap_types::summary_type::{ExactKind, SummaryUpdate}; +use asap_types::summary_type::{ + ExactKind, SketchAlgorithm, StatisticKind, SummaryFamily, SummaryUpdate, +}; use asap_types::test_support::memo_builders::{candidates_of, group, groups_where, query}; use asap_types::workload::DataWorkload; @@ -26,7 +32,7 @@ fn multi_measure_aggregate_has_one_target_per_measure() { None, ); query(&mut memo, both, None); - let targets = computation_targets(&memo, None).unwrap(); + let targets = computation_targets(&memo, &[]).unwrap(); let measures: Vec<(MemoGroupId, usize)> = targets .iter() .map(|target| (target.aggregate_group, target.measure_index)) @@ -51,8 +57,8 @@ fn aggregate_without_realization_is_not_a_target() { None, ); query(&mut memo, stddev, None); - assert!(computation_targets(&memo, None).unwrap().is_empty()); - let memo = pass1_memo(memo, None).unwrap(); + assert!(computation_targets(&memo, &[]).unwrap().is_empty()); + let memo = pass1_memo(memo, &[]).unwrap(); assert_eq!(candidates_of(&memo, stddev).len(), 1); } @@ -71,7 +77,7 @@ fn an_aggregate_read_by_several_roots_is_one_target() { ); query(&mut memo, p, None); query(&mut memo, p, None); - assert_eq!(computation_targets(&memo, None).unwrap().len(), 1); + assert_eq!(computation_targets(&memo, &[]).unwrap().len(), 1); } /// A memo whose groups already hold ASAP operators fails at the stage @@ -92,25 +98,98 @@ fn asap_input_is_rejected() { ); query(&mut memo, state, None); assert!(matches!( - pass1_memo(memo, None), + pass1_memo(memo, &[]), Err(PerComputationCandidateError::ContainsAsap) )); } -/// The summaries the deployment does not support are not offered. -#[test] -fn unsupported_summaries_are_not_offered() { +/// One global aggregate of `measure` over the instant selector `m` +/// (`quantile(0.9, m)`), planned by Pass 1 under `exclusions`; returns the +/// memo and the aggregate's group. +fn pass1_under(measure: AggIntent, exclusions: &[DeploymentExclusion]) -> (Memo, MemoGroupId) { let mut memo = Memo::new(&DataWorkload::default()); - let rows = selector(&mut memo, TimeRangeKind::Range, "m", &[]); - let p = aggregate_group( - &mut memo, - rows, - Reduction::by(vec![]), - vec![quantile(0.9)], - None, - ); - query(&mut memo, p, None); - let memo = pass1_memo(memo, Some(&[])).unwrap(); - assert_eq!(candidates_of(&memo, p).len(), 1); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &[]); + let aggregate = aggregate_group(&mut memo, rows, Reduction::by(vec![]), vec![measure], None); + query(&mut memo, aggregate, None); + (pass1_memo(memo, exclusions).unwrap(), aggregate) +} + +/// The summary types of the state builds Pass 1 added to `memo`. +fn built_summary_types(memo: &Memo) -> Vec { + groups_where(memo, |e| { + matches!(e, Operator::ASAP(ASAPOp::SummaryAgg { .. })) + }) + .into_iter() + .filter_map(|g| match &memo.groups()[g.0 as usize].expression { + Operator::ASAP(ASAPOp::SummaryAgg { summary_type, .. }) => Some(summary_type.clone()), + _ => None, + }) + .collect() +} + +/// Under exact-only capabilities (`supported_summaries: []`) every sketch +/// family is excluded outright, so Pass 1 offers no summary for a +/// quantile: the aggregate keeps only its own exact expression, as Stage 2 +/// would have pruned every build. +#[test] +fn exact_only_capabilities_offer_no_summary() { + let exact_only = DeploymentCapabilities { + supported_summaries: Some(vec![]), + ..Default::default() + }; + let (memo, aggregate) = pass1_under(quantile(0.9), &exact_only.exclusions()); + assert_eq!(candidates_of(&memo, aggregate).len(), 1); assert!(groups_where(&memo, |e| matches!(e, Operator::ASAP(_))).is_empty()); } + +/// Exact accumulators are left to Stage 2: with every `Sum` state +/// excluded, Pass 1 still offers a `sum` its accumulator. +#[test] +fn an_excluded_exact_family_is_left_to_stage_2() { + let no_sum_state = [DeploymentExclusion { + source: ExclusionSource::ExcludedCandidate { index: 0 }, + exclusion: CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(ExactKind::Sum)), + ..Default::default() + }, + }]; + let (memo, _) = pass1_under(sum(), &no_sum_state); + assert!(built_summary_types(&memo).contains(&FieldDataType::exact(ExactKind::Sum))); +} + +/// A KLL listed without its quantile readout cannot answer a quantile, so +/// Pass 1 offers a quantile no KLL build (and, with every other algorithm +/// unlisted, no summary at all). A readout the measure does not read +/// (KLL's `Total`) keeps the build. +#[test] +fn an_excluded_readout_of_the_measure_skips_the_summary() { + let kll_with = |readouts| DeploymentCapabilities { + supported_summaries: Some(vec![SupportedSummary { + summary_type: SketchAlgorithm::Kll, + readouts, + }]), + ..Default::default() + }; + let (memo, aggregate) = pass1_under(quantile(0.9), &kll_with(vec![]).exclusions()); + assert!(built_summary_types(&memo).is_empty()); + assert_eq!(candidates_of(&memo, aggregate).len(), 1); + + let (memo, _) = pass1_under( + quantile(0.9), + &kll_with(vec![StatisticKind::Quantile]).exclusions(), + ); + assert!(built_summary_types(&memo).contains(&FieldDataType::Sketch(SketchAlgorithm::Kll))); +} + +/// Only an exclusion of every state of a family, or of the readout the +/// measure reads, skips a summary in Pass 1. KLL not mergeable across +/// windows still has builds Stage 2 may keep, so Pass 1 offers them. +#[test] +fn a_partial_exclusion_keeps_the_summary() { + let kll_not_mergeable = DeploymentCapabilities { + state_not_mergeable_across_windows: vec![SummaryFamily::Sketch(SketchAlgorithm::Kll)], + ..Default::default() + }; + let (memo, _) = pass1_under(quantile(0.9), &kll_not_mergeable.exclusions()); + assert!(built_summary_types(&memo).contains(&FieldDataType::Sketch(SketchAlgorithm::Kll))); +} diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests/update_weights.rs b/crates/stage1-pass1-per-computation-candidates/src/tests/update_weights.rs index 5ab2e70dd..8f6ff5f10 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests/update_weights.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests/update_weights.rs @@ -24,14 +24,14 @@ fn update_weights_follow_the_measure() { None, ); query(&mut memo, counts, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let (_, update) = state_group(&memo, SketchAlgorithm::Cms); assert_eq!(update.weight, SummaryInputExpr::Constant(1.0)); let mut memo = Memo::new(&DataWorkload::default()); let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); let sums = aggregate_group(&mut memo, rows, Reduction::by(vec![2]), vec![sum()], None); query(&mut memo, sums, None); - let memo = pass1_memo(memo, None).unwrap(); + let memo = pass1_memo(memo, &[]).unwrap(); let state = groups_where( &memo, |e| matches!(e, Operator::ASAP(ASAPOp::SummaryAgg { input, .. }) if input.weight == SummaryInputExpr::Column(ColumnRef::SampleValue)), diff --git a/crates/stage2-physical-optimization/src/candidate.rs b/crates/stage2-physical-optimization/src/candidate.rs index d58b0f928..c7c5b4413 100644 --- a/crates/stage2-physical-optimization/src/candidate.rs +++ b/crates/stage2-physical-optimization/src/candidate.rs @@ -7,7 +7,7 @@ use std::collections::{BTreeSet, HashMap, HashSet}; -use asap_types::deployment_capabilities::DeploymentCapabilities; +use asap_types::deployment_capabilities::{CandidateDescription, DeploymentExclusion}; use asap_types::ir::operator::arguments::Source; use asap_types::ir::properties::ExecutionTiming; use asap_types::ir::schema::FieldDataType; @@ -59,16 +59,29 @@ pub(super) struct OfferedPhysicalProperties { /// between batches, so it is materialized. /// /// A value not offered is not returned, and neither is the invalid -/// (IngestionTime, OneEvaluation). +/// (IngestionTime, OneEvaluation). The prune rules, in order: a Count-Min +/// build whose weights are not proven non-negative, ingestion-time work +/// without an ingestion pipeline, then the first of the deployment's +/// `exclusions` (`DeploymentCapabilities::exclusions`) that matches it. pub(super) fn offered_physical_properties( memo: &Memo, candidate: CandidateForMemoGroupId, ingestion_time_offered_for_group: bool, across_evaluations_offered_for_group: bool, data: &DataWorkload, - capabilities: &DeploymentCapabilities, + exclusions: &[DeploymentExclusion], ) -> Vec { - let operator = &memo.candidate(candidate).expression.operator; + let logical_candidate = memo.candidate(candidate); + let operator = &logical_candidate.expression.operator; + // For a readout, the summary type of the state it reads. + let read_summary_type = match operator { + Operator::ASAP(ASAPOp::SummaryEstimate { summary_input, .. }) => memo.groups() + [summary_input.0 as usize] + .group_properties + .schema + .summary_state_type(), + _ => None, + }; let build = summary_build(operator); let ingestion_time_offered = ingestion_time_offered_for_group && build.is_none_or(|(summary_type, child)| { @@ -82,7 +95,6 @@ pub(super) fn offered_physical_properties( count_min_weights_not_proven_non_negative(memo, candidate.group, summary_type) }); let has_ingestion_pipeline = data.arrival.rows_per_second().is_some(); - let scans_raw_data = matches!(operator, Operator::NonASAP(NonASAPOp::Scan { .. })); let builds_summary = build.is_some() || matches!(operator, Operator::ASAP(ASAPOp::MaintainPopulation { .. })); let mut offered = Vec::new(); @@ -104,21 +116,21 @@ pub(super) fn offered_physical_properties( let Ok(physical_properties) = PhysicalProperties::new(timing, lifetime) else { continue; }; - let query_time = timing == ExecutionTiming::QueryTime; + let description = CandidateDescription { + operator, + parameters: logical_candidate.logical_properties.parameters(), + physical_properties, + read_summary_type, + }; let prune_reason = if count_min_weights_not_proven_non_negative { Some(PruneReason::CountMinWeightsNotProvenNonNegative) - } else if !query_time && !has_ingestion_pipeline { + } else if timing == ExecutionTiming::IngestionTime && !has_ingestion_pipeline { Some(PruneReason::NoIngestionPipeline) - } else if (query_time || across_evaluations) - && scans_raw_data - && !capabilities.raw_data_retained - { - Some(PruneReason::RawDataNotRetained) - } else if query_time && across_evaluations && !capabilities.query_time_results_retained - { - Some(PruneReason::QueryTimeResultsNotRetained) } else { - None + exclusions + .iter() + .find(|exclusion| exclusion.exclusion.matches(&description)) + .map(|exclusion| PruneReason::ExcludedByDeployment(exclusion.source)) }; offered.push(OfferedPhysicalProperties { physical_properties, diff --git a/crates/stage2-physical-optimization/src/lib.rs b/crates/stage2-physical-optimization/src/lib.rs index 208aa88a3..586a24ccd 100644 --- a/crates/stage2-physical-optimization/src/lib.rs +++ b/crates/stage2-physical-optimization/src/lib.rs @@ -24,7 +24,7 @@ mod tests; use std::collections::{HashMap, HashSet}; use std::ops::Range; -use asap_types::deployment_capabilities::DeploymentCapabilities; +use asap_types::deployment_capabilities::DeploymentExclusion; use asap_types::stages::{ CandidateForMemoGroupId, LogicalASAPMemoCandidates, MemoGroupId, PhysicalASAPMemoCandidates, PhysicalCandidate, PhysicalCandidateId, PhysicalEdge, PrunedCandidate, @@ -36,12 +36,15 @@ use candidate::{offered_physical_properties, OfferedPhysicalProperties}; /// Stage 2: expand every logical candidate of `logical` that survived Pass 2 /// into its physical alternatives (decision-tree levels 3–4: timing and -/// lifetime) the data and the deployment's `capabilities` allow, and every +/// lifetime) the data and the deployment's `exclusions` allow, and every /// logical edge into its physical edges with $\alpha^{\log}$ and /// $\alpha^{\mathrm{phys}}$. Every alternative rejected is recorded in the /// output's `pruned_candidates` with its `PruneReason`: first those a -/// decision-tree prune rule removes ([`candidate`]), then those that -/// cannot be built or that no query output can read ([`pruning`]). A value +/// decision-tree prune rule removes ([`candidate`]; among them those one of +/// the deployment's `exclusions` matches, `DeploymentCapabilities::exclusions` +/// as the facade expanded them, e.g. every query-time scan when raw data is +/// not retained), then those +/// that cannot be built or that no query output can read ([`pruning`]). A value /// outside a dimension's declared value set (`AcrossEvaluations` on a /// candidate of a time-dependent group with no known grid) is not offered /// and not recorded. Costs nothing, and cannot fail; alignment with each @@ -49,7 +52,7 @@ use candidate::{offered_physical_properties, OfferedPhysicalProperties}; pub fn generate_physical_asap_memo_candidates( logical: &LogicalASAPMemoCandidates, data: &DataWorkload, - capabilities: &DeploymentCapabilities, + exclusions: &[DeploymentExclusion], ) -> PhysicalASAPMemoCandidates { let memo = &logical.memo; let eliminated: HashSet = logical @@ -85,7 +88,7 @@ pub fn generate_physical_asap_memo_candidates( ingestion_time_offered[group_index], across_evaluations_offered[group_index], data, - capabilities, + exclusions, ) { let alternative = PhysicalCandidate { logical_candidate_id, diff --git a/crates/stage2-physical-optimization/src/tests.rs b/crates/stage2-physical-optimization/src/tests.rs index 0bf0e2dc6..3b9310837 100644 --- a/crates/stage2-physical-optimization/src/tests.rs +++ b/crates/stage2-physical-optimization/src/tests.rs @@ -24,7 +24,8 @@ fn generate( data: &DataWorkload, capabilities: &DeploymentCapabilities, ) -> PhysicalASAPMemoCandidates { - let physical = generate_physical_asap_memo_candidates(logical, data, capabilities); + let physical = + generate_physical_asap_memo_candidates(logical, data, &capabilities.exclusions()); let count = physical.physical_candidates.len(); let mut consumer_inputs = Vec::new(); for (_, edge) in physical.edges() { diff --git a/crates/stage2-physical-optimization/src/tests/candidates.rs b/crates/stage2-physical-optimization/src/tests/candidates.rs index 02ec2887d..a6b42c52d 100644 --- a/crates/stage2-physical-optimization/src/tests/candidates.rs +++ b/crates/stage2-physical-optimization/src/tests/candidates.rs @@ -2,15 +2,18 @@ //! offered, and the prune rules that remove some of them. use std::collections::BTreeMap; -use asap_types::deployment_capabilities::DeploymentCapabilities; +use asap_types::deployment_capabilities::{ + CandidateExclusion, DeploymentCapabilities, ExclusionSource, SupportedSummary, +}; use asap_types::ir::operator::arguments::{AtModifier, Reduction, Source}; +use asap_types::ir::operator::OperatorKind; use asap_types::ir::properties::ExecutionTiming::QueryTime; use asap_types::ir::scalar::ColumnRef; use asap_types::ir::schema::FieldDataType; use asap_types::ir::{ASAPOp, NonASAPOp, Operator}; use asap_types::stages::{Memo, PhysicalASAPMemoCandidates, PruneReason, ValueSign}; use asap_types::summary_type::{ - EntityIdentity, ExactKind, SketchAlgorithm, SummaryInputExpr, SummaryUpdate, + EntityIdentity, ExactKind, SketchAlgorithm, StatisticKind, SummaryInputExpr, SummaryUpdate, }; use asap_types::test_support::memo_builders::{group, query, scan_group}; use asap_types::test_support::memo_fixtures::{range, shift, state}; @@ -144,7 +147,7 @@ fn without_raw_data_only_ingestion_time_builds_read_the_scan() { pruned(&physical, example.scan), pruned_with( &[QT_NONE, QT_ONE, QT_ACROSS, IT_ACROSS], - PruneReason::RawDataNotRetained + PruneReason::ExcludedByDeployment(ExclusionSource::RawDataNotRetained) ) ); assert_eq!( @@ -170,6 +173,129 @@ fn without_raw_data_only_ingestion_time_builds_read_the_scan() { ); } +/// A summary type the deployment does not build is pruned at every +/// alternative of its builds, so its readout has no producer left; a +/// listed summary type whose readout the deployment does not answer keeps +/// its builds, and only the readout is pruned. (Pass 1 offers every +/// summary the planner can build; this is where the deployment's +/// `supported_summaries` apply.) +#[test] +fn unsupported_summaries_and_readouts_are_pruned() { + let example = example(); + let none_supported = DeploymentCapabilities { + supported_summaries: Some(vec![]), + ..retaining_everything() + }; + let physical = generate(&example.logical, &ingesting(None), &none_supported); + let not_supported = PruneReason::ExcludedByDeployment(ExclusionSource::SummaryNotSupported); + assert_eq!( + pruned(&physical, example.build), + pruned_with(&[QT_NONE, QT_ONE, QT_ACROSS], not_supported) + ); + assert_eq!( + pruned(&physical, example.chain), + pruned_with(&[QT_NONE, QT_ONE, QT_ACROSS, IT_ACROSS], not_supported) + ); + assert_eq!( + pruned(&physical, example.readout), + pruned_with( + &[QT_NONE, QT_ONE, QT_ACROSS], + PruneReason::InputHasNoBuildableProducer + ) + ); + + let kll_total_only = DeploymentCapabilities { + supported_summaries: Some(vec![SupportedSummary { + summary_type: SketchAlgorithm::Kll, + readouts: vec![StatisticKind::Total], + }]), + ..retaining_everything() + }; + let physical = generate(&example.logical, &ingesting(None), &kll_total_only); + assert_eq!( + pruned(&physical, example.readout), + pruned_with( + &[QT_NONE, QT_ONE, QT_ACROSS], + PruneReason::ExcludedByDeployment(ExclusionSource::ReadoutNotSupported) + ) + ); + assert!(pruned(&physical, example.build) + .iter() + .all(|(_, reason)| *reason == PruneReason::ReachesNoQueryOutput)); +} + +/// A candidate the caller excludes is pruned as a capability the +/// deployment lacks would prune it, naming the caller's exclusion by its +/// index; what reads only it loses its producer. Excluding every chain +/// leaves the chain's windows unbuildable, while the build over the last +/// minute is untouched. +#[test] +fn a_caller_exclusion_prunes_like_a_missing_capability() { + let example = example(); + let capabilities = DeploymentCapabilities { + excluded_candidates: vec![CandidateExclusion { + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..Default::default() + }], + ..retaining_everything() + }; + let physical = generate(&example.logical, &ingesting(None), &capabilities); + assert_eq!( + pruned(&physical, example.chain), + pruned_with( + &[QT_NONE, QT_ONE, QT_ACROSS, IT_ACROSS], + PruneReason::ExcludedByDeployment(ExclusionSource::ExcludedCandidate { index: 0 }) + ) + ); + assert_eq!(offered(&physical, example.chain), vec![]); + assert_eq!( + pruned(&physical, example.windows), + pruned_with( + &[QT_NONE, QT_ONE, QT_ACROSS], + PruneReason::InputHasNoBuildableProducer + ) + ); + assert_eq!( + offered(&physical, example.build), + physical_properties_list(&[QT_NONE, QT_ONE, QT_ACROSS]) + ); +} + +/// When a capability's exclusion and the caller's both match, the +/// capability is named: it comes first in `DeploymentCapabilities::exclusions`. +#[test] +fn a_capability_is_named_before_a_caller_exclusion_matching_the_same_candidate() { + let example = example(); + let capabilities = DeploymentCapabilities { + raw_data_retained: false, + excluded_candidates: vec![CandidateExclusion { + operator: Some(OperatorKind::Scan), + ..Default::default() + }], + ..retaining_everything() + }; + let physical = generate(&example.logical, &ingesting(None), &capabilities); + let scan = pruned(&physical, example.scan); + assert_eq!( + scan, + [ + pruned_with( + &[QT_NONE, QT_ONE, QT_ACROSS], + PruneReason::ExcludedByDeployment(ExclusionSource::RawDataNotRetained) + ), + pruned_with( + &[IT_NONE], + PruneReason::ExcludedByDeployment(ExclusionSource::ExcludedCandidate { index: 0 }) + ), + pruned_with( + &[IT_ACROSS], + PruneReason::ExcludedByDeployment(ExclusionSource::RawDataNotRetained) + ), + ] + .concat() + ); +} + /// The default deployment retains no query-time result across /// evaluations: every (QueryTime, AcrossEvaluations) is pruned, and /// `OneEvaluation` stays. @@ -184,7 +310,10 @@ fn query_time_results_across_evaluations_need_the_deployment_to_retain_them() { for candidate in [example.build, example.merge, example.readout] { assert_eq!( pruned(&physical, candidate), - pruned_with(&[QT_ACROSS], PruneReason::QueryTimeResultsNotRetained), + pruned_with( + &[QT_ACROSS], + PruneReason::ExcludedByDeployment(ExclusionSource::QueryTimeResultsNotRetained) + ), "{candidate:?}" ); assert_eq!( diff --git a/crates/stage3-plan-selection/src/cost.rs b/crates/stage3-plan-selection/src/cost.rs index a87cd798c..f85c47770 100644 --- a/crates/stage3-plan-selection/src/cost.rs +++ b/crates/stage3-plan-selection/src/cost.rs @@ -79,6 +79,7 @@ use crate::selectable::{Execution, SelectableExecutions}; /// The objective's coefficients /// (`docs/design_docs/concepts/memo-groups-properties-requirements.md`, /// section 5, "Cost and retention"), per second. +#[cfg_attr(test, derive(Default))] pub(crate) struct ExecutionCosts { /// $\rho_\kappa c_{\kappa,v}$ of each execution, $W^{\mathrm{mat}}_v$ /// of an execution in `Materialized(v)`, by position in diff --git a/crates/stage3-plan-selection/src/lib.rs b/crates/stage3-plan-selection/src/lib.rs index d0ab792a1..d936a81b8 100644 --- a/crates/stage3-plan-selection/src/lib.rs +++ b/crates/stage3-plan-selection/src/lib.rs @@ -39,7 +39,7 @@ use asap_types::workload::{DataWorkload, QueryWorkloadEntry}; use crate::cost::execution_costs; use crate::milp::model::{solve_selection, SelectionInputs, SelectionMilpError}; use crate::plan::plan_of; -use crate::report::{accepted_accuracy, infeasible}; +use crate::report::{accepted_accuracy, excluded_by_deployment, infeasible}; use crate::selectable::{QueryId, SelectableExecutions}; pub use report::{ @@ -55,8 +55,9 @@ pub use report::{ /// `entries[q]` is query `q`'s workload entry; `data` the data workload /// with its bounds. /// -/// Err: invalid or unsupported cost inputs, an infeasible catalog, or a -/// solver failure. +/// Err: invalid or unsupported cost inputs, an infeasible catalog (reported +/// as excluded by the deployment when Stage 2 pruned some candidate as +/// such), or a solver failure. pub fn select_plan( physical: &PhysicalASAPMemoCandidates, entries: &[QueryWorkloadEntry], @@ -103,12 +104,15 @@ pub fn select_plan( physical.physical_candidates[execution.candidate.0].logical_candidate_id, ) }); - if selectable + if let Some((query, _)) = selectable .answering() .iter() - .any(|(_, executions)| executions.is_empty()) + .find(|(_, executions)| executions.is_empty()) { - return Err(infeasible(&costs)); + return Err( + excluded_by_deployment(&physical.pruned_candidates, Some(query.0), &costs) + .unwrap_or_else(|| infeasible(&costs)), + ); } let solved = solve_selection(&SelectionInputs { physical, @@ -117,7 +121,10 @@ pub fn select_plan( costs: &costs, }) .map_err(|error| match error { - SelectionMilpError::Infeasible => infeasible(&costs), + SelectionMilpError::Infeasible => { + excluded_by_deployment(&physical.pruned_candidates, None, &costs) + .unwrap_or_else(|| infeasible(&costs)) + } SelectionMilpError::Solver(reason) => ErrorSelectingPlan::Solver(reason), SelectionMilpError::TargetBelowSolverPrecision { query, diff --git a/crates/stage3-plan-selection/src/report.rs b/crates/stage3-plan-selection/src/report.rs index 1d51173a3..f446486d1 100644 --- a/crates/stage3-plan-selection/src/report.rs +++ b/crates/stage3-plan-selection/src/report.rs @@ -7,12 +7,15 @@ use std::collections::{BTreeSet, HashMap}; use asap_cost::node::analytical::AnalyticalCostError; use asap_cost::{summary_type_name, CostModel}; use asap_types::accuracy::AccuracyMetric; +use asap_types::deployment_capabilities::ExclusionSource; use asap_types::ir::schema::FieldDataType; use asap_types::ir::{ASAPOp, Operator}; use asap_types::plan::physical_asap_dag::{ PhysicalASAPDAG, PhysicalASAPDAGNode, PhysicalASAPNodeId, }; -use asap_types::stages::{PhysicalASAPMemoCandidates, PhysicalCandidate, PrunedCandidate}; +use asap_types::stages::{ + PhysicalASAPMemoCandidates, PhysicalCandidate, PruneReason, PrunedCandidate, +}; use thiserror::Error; use crate::cost::ExecutionCosts; @@ -90,6 +93,19 @@ pub enum RejectionCause { /// catalog's consumer constraints together: the selection MILP is /// infeasible. The reason names a query when it has no plan even alone. Infeasible, + /// No plan is left without the candidates the deployment excludes + /// (`DeploymentCapabilities::exclusions`, which Stage 2 pruned as + /// `ExcludedByDeployment`) beyond the default deployment's own. The + /// reason names the query whose every candidate was excluded, else says + /// the selection MILP is infeasible; then each such exclusion source + /// that pruned a candidate, by its JSON + /// name (`excluded_candidates[i]` for the caller's own), with how many + /// it pruned, e.g. `counter_not_extrapolated (7 candidates)`; and that + /// the workload may be infeasible without these exclusions too (telling + /// would take a second solve); then, as for `Infeasible`, why executions + /// could not be costed. Not a failed check: the excluded + /// candidates were valid. + ExcludedByDeployment, } impl RejectionCause { @@ -224,6 +240,23 @@ pub enum ErrorSelectingPlan { /// The selection MILP is infeasible, with the reasons executions could not /// be costed. pub(crate) fn infeasible(costs: &ExecutionCosts) -> ErrorSelectingPlan { + let reason = format!( + "no plan gives every query output a candidate whose every input has an admissible \ + producer that delivers on its context (the selection MILP is infeasible){}", + costing_failures(costs) + ); + ErrorSelectingPlan::NoValidCandidate(vec![Rejection { + id: "workload".into(), + cause: RejectionCause::Infeasible, + reason, + }]) +} + +/// Why executions could not be costed, each distinct reason once, as a +/// suffix of a rejection's reason: "; executions left out because they +/// could not be costed: no cardinality for m"; empty when every execution +/// was costed. +fn costing_failures(costs: &ExecutionCosts) -> String { let mut reasons: Vec<&str> = Vec::new(); for reason in costs .per_execution @@ -234,21 +267,82 @@ pub(crate) fn infeasible(costs: &ExecutionCosts) -> ErrorSelectingPlan { reasons.push(reason); } } - let mut reason = "no plan gives every query output a candidate whose every input has an \ - admissible producer that delivers on its context (the selection MILP is \ - infeasible)" - .to_string(); - if !reasons.is_empty() { - reason += &format!( - "; executions left out because they could not be costed: {}", - reasons.join("; ") - ); + if reasons.is_empty() { + return String::new(); } - ErrorSelectingPlan::NoValidCandidate(vec![Rejection { + format!( + "; executions left out because they could not be costed: {}", + reasons.join("; ") + ) +} + +/// When Stage 2 pruned some candidate as excluded by the deployment +/// (`PruneReason::ExcludedByDeployment`) for a source the default +/// deployment does not have, why no plan is left: one +/// [`RejectionCause::ExcludedByDeployment`] whose reason names `query`, the +/// first query with no candidate left to answer it (else the infeasible +/// selection MILP), then each exclusion source with how many candidates it +/// pruned, in the order Stage 2 first recorded it. E.g. "query 0 has no +/// candidate left to answer it; excluded by the deployment: +/// counter_not_extrapolated (7 candidates); the workload may be infeasible +/// without these exclusions too", followed by why executions could not be +/// costed, as [`infeasible`] reports it ([`costing_failures`]). `None` when no candidate was excluded +/// beyond the default deployment's exclusions: the selection is infeasible +/// on its own ([`infeasible`]). Telling +/// whether the workload has a plan without the exclusions would take a +/// second solve, so the reason says it may not. +pub(crate) fn excluded_by_deployment( + stage2_pruned_candidates: &[PrunedCandidate], + query: Option, + costs: &ExecutionCosts, +) -> Option { + let mut pruned_per_source: Vec<(ExclusionSource, usize)> = Vec::new(); + for pruned in stage2_pruned_candidates { + let PruneReason::ExcludedByDeployment(source) = pruned.reason else { + continue; + }; + // The default deployment's own exclusions (query-time results not + // kept across evaluations) are planning as it always was, so they + // neither cause this rejection nor appear in it. + if source.in_default_deployment() { + continue; + } + match pruned_per_source + .iter_mut() + .find(|(seen, _)| *seen == source) + { + Some((_, count)) => *count += 1, + None => pruned_per_source.push((source, 1)), + } + } + if pruned_per_source.is_empty() { + return None; + } + let what = match query { + Some(query) => format!("query {query} has no candidate left to answer it"), + None => "no plan is left (the selection MILP is infeasible)".to_string(), + }; + let sources: Vec = pruned_per_source + .iter() + .map(|(source, count)| { + let noun = if *count == 1 { + "candidate" + } else { + "candidates" + }; + format!("{source} ({count} {noun})") + }) + .collect(); + Some(ErrorSelectingPlan::NoValidCandidate(vec![Rejection { id: "workload".into(), - cause: RejectionCause::Infeasible, - reason, - }]) + cause: RejectionCause::ExcludedByDeployment, + reason: format!( + "{what}; excluded by the deployment: {}; the workload may be infeasible without \ + these exclusions too{}", + sources.join(", "), + costing_failures(costs) + ), + }])) } /// Per query, the sketches its output reads in `plan` (each sketch build diff --git a/crates/stage3-plan-selection/src/report/tests.rs b/crates/stage3-plan-selection/src/report/tests.rs index c73f67f71..4136a0111 100644 --- a/crates/stage3-plan-selection/src/report/tests.rs +++ b/crates/stage3-plan-selection/src/report/tests.rs @@ -28,3 +28,99 @@ fn a_very_large_peak_memory_is_warned_about_only_without_a_declared_capacity() { }); assert_eq!(large_peak_memory_warning(1_430_000_000_000, &cluster), None); } + +/// Stage 2's alternatives pruned as `reason`, one per entry, all of the +/// same (query-time, None) candidate: only their reasons are read. +fn pruned_as(reasons: &[PruneReason]) -> Vec> { + use asap_types::ir::properties::ExecutionTiming; + use asap_types::stages::{CandidateForMemoGroupId, Lifetime, MemoGroupId, PhysicalProperties}; + reasons + .iter() + .map(|&reason| PrunedCandidate { + candidate: PhysicalCandidate { + logical_candidate_id: CandidateForMemoGroupId { + group: MemoGroupId(0), + index_in_group: 0, + }, + physical_properties: PhysicalProperties::new( + ExecutionTiming::QueryTime, + Lifetime::None, + ) + .unwrap(), + }, + reason, + }) + .collect() +} + +/// A rejection is "excluded by the deployment" only when a source the +/// default deployment lacks pruned something: the default's own exclusion +/// (no query-time result kept across evaluations) leaves today's +/// `Infeasible`. Otherwise the reason counts each such source, the +/// caller's own by index, and names the query. +#[test] +fn only_exclusions_beyond_the_default_deployments_make_the_rejection() { + let no_costing_failure = ExecutionCosts::default(); + let default_only = pruned_as(&[ + PruneReason::ExcludedByDeployment(ExclusionSource::QueryTimeResultsNotRetained), + PruneReason::NoIngestionPipeline, + ]); + assert!(excluded_by_deployment(&default_only, Some(0), &no_costing_failure).is_none()); + assert!(excluded_by_deployment(&[], None, &no_costing_failure).is_none()); + + let restricted = pruned_as(&[ + PruneReason::ExcludedByDeployment(ExclusionSource::QueryTimeResultsNotRetained), + PruneReason::ExcludedByDeployment(ExclusionSource::CounterNotExtrapolated), + PruneReason::ExcludedByDeployment(ExclusionSource::ExcludedCandidate { index: 1 }), + PruneReason::ExcludedByDeployment(ExclusionSource::CounterNotExtrapolated), + ]); + let Some(ErrorSelectingPlan::NoValidCandidate(rejections)) = + excluded_by_deployment(&restricted, Some(0), &no_costing_failure) + else { + panic!("expected a rejection"); + }; + assert_eq!(rejections.len(), 1); + assert_eq!(rejections[0].cause, RejectionCause::ExcludedByDeployment); + assert_eq!( + rejections[0].reason, + "query 0 has no candidate left to answer it; excluded by the deployment: \ + counter_not_extrapolated (2 candidates), excluded_candidates[1] (1 candidate); \ + the workload may be infeasible without these exclusions too" + ); +} + +/// The rejection keeps why executions could not be costed, as +/// `Infeasible` does: an exclusion that pruned something elsewhere does not +/// hide the costing diagnostics of the query that failed. +#[test] +fn the_exclusion_rejection_keeps_the_costing_failures() { + let costs = ExecutionCosts { + per_execution: vec![ + Ok(1.0), + Err("no cardinality for m".to_string()), + Err("no cardinality for m".to_string()), + ], + ..ExecutionCosts::default() + }; + let restricted = pruned_as(&[PruneReason::ExcludedByDeployment( + ExclusionSource::RawDataNotRetained, + )]); + let Some(ErrorSelectingPlan::NoValidCandidate(rejections)) = + excluded_by_deployment(&restricted, None, &costs) + else { + panic!("expected a rejection"); + }; + assert_eq!( + rejections[0].reason, + "no plan is left (the selection MILP is infeasible); excluded by the deployment: \ + raw_data_not_retained (1 candidate); the workload may be infeasible without these \ + exclusions too; executions left out because they could not be costed: no \ + cardinality for m" + ); + let ErrorSelectingPlan::NoValidCandidate(infeasible) = infeasible(&costs) else { + panic!("expected a rejection"); + }; + assert!(infeasible[0] + .reason + .ends_with("; executions left out because they could not be costed: no cardinality for m")); +} diff --git a/crates/types/src/deployment_capabilities.rs b/crates/types/src/deployment_capabilities.rs deleted file mode 100644 index 35ee3aa02..000000000 --- a/crates/types/src/deployment_capabilities.rs +++ /dev/null @@ -1,143 +0,0 @@ -//! What the deployment's executor can run and keep (the third -//! deployment input, beside the cost and accuracy models). -//! -//! [`DeploymentCapabilities`] says three things: -//! -//! * which sketch summary types the executor supports, and which readouts -//! it supports for each. A summary type is supported when the executor can build -//! its state, and a readout of it when the executor can answer that -//! statistic ([`StatisticKind`]) from the state. Stage 1 (Pass 1) offers -//! no summary candidate whose summary type or readout is unsupported, so no -//! Pass 2 candidate has one either (Pass 2 rules share, split into tumbling windows -//! or reuse existing builds; none adds a summary type or a readout). Exact -//! accumulators and plain exact execution are always supported; -//! * whether raw data samples are retained. If they are, Stage 3 counts them on -//! disk once per source, at the longest window a query-time scan of it -//! reads. If they are not, raw data samples are not retained after they arrive, so -//! a candidate that scans raw data at query time is invalid (the -//! rejection lists every such scan): only ingestion-time work reads raw -//! rows. Stored data (at rest or mixed) with no raw data retained is a -//! contradiction, refused as bad input ([`DeploymentCapabilities::validate`]); -//! * whether query-time results are retained across evaluations. If they -//! are, Stage 2 also offers a tumbling-window chain whose queries evaluate -//! together at its tumbling-window width as query-time `AcrossEvaluations`: each -//! evaluation builds one new tumbling window and keeps the others for the next ones, -//! covering the queries' longest look-back. A chain two or more queries -//! read keeps its `OneEvaluation` option too (shared within one evaluation), -//! and Stage 3 picks the cheaper. If they are not, a query-time result is -//! reused only within one evaluation. -//! -//! The default supports everything the planner can build, retains raw data -//! and keeps no query-time result across evaluations, which is the -//! planner's behavior without deployment inputs. - -// The executor lists the summary types it builds as `SupportedSummary`s, so the -// type lives with the readout vocabulary in `asap-types`. -pub use crate::summary_type::SupportedSummary; -use crate::summary_type::{SketchAlgorithm, StatisticKind}; -use crate::workload::{DataArrival, DataWorkload}; -use serde::{Deserialize, Serialize}; -use thiserror::Error; - -/// What the deployment's executor can run and keep. Planning reads it in -/// Stage 1 (`supported_summaries`), Stage 2 (`query_time_results_retained`) -/// and Stage 3 (`raw_data_retained`). It is data only; `asap_planner` reads it from -/// `--deployment-capabilities ` and shows it in the stage document. -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] -#[serde(default, deny_unknown_fields)] -pub struct DeploymentCapabilities { - /// The sketch summary types the executor can build, each with the - /// readouts it can answer from one; `None` (the default) supports every summary type - /// and readout the planner can build. - pub supported_summaries: Option>, - /// Whether raw data samples are retained for query-time scans; default `true`. - pub raw_data_retained: bool, - /// Whether a query-time result may be materialized across evaluations - /// (query-time `AcrossEvaluations`); default `false`. - pub query_time_results_retained: bool, -} - -impl Default for DeploymentCapabilities { - fn default() -> Self { - Self { - supported_summaries: None, - raw_data_retained: true, - query_time_results_retained: false, - } - } -} - -impl DeploymentCapabilities { - /// Whether the executor can build `summary_type` and answer `readout` from it. - pub fn supports(&self, summary_type: &SketchAlgorithm, readout: StatisticKind) -> bool { - summary_supported(self.supported_summaries.as_deref(), summary_type, readout) - } - - /// Checks these capabilities against the data workload: stored data - /// (at rest, or mixed) is raw data the deployment keeps, so it - /// contradicts `raw_data_retained: false`. Plan selection refuses such - /// inputs before measuring any candidate. - pub fn validate(&self, data: &DataWorkload) -> Result<(), DeploymentCapabilitiesError> { - match &data.arrival { - DataArrival::AtRest | DataArrival::Mixed { .. } if !self.raw_data_retained => { - Err(DeploymentCapabilitiesError::StoredDataNotRetained { - arrival: data.arrival, - }) - } - _ => Ok(()), - } - } -} - -/// Whether an executor that builds `supported_summaries` (`None`: every -/// summary type and readout the planner can build) can build -/// `summary_type` and answer `readout` from it. Pass 1 reads only this -/// field of [`DeploymentCapabilities`]. -pub fn summary_supported( - supported_summaries: Option<&[SupportedSummary]>, - summary_type: &SketchAlgorithm, - readout: StatisticKind, -) -> bool { - supported_summaries.is_none_or(|supported| { - supported - .iter() - .any(|s| s.summary_type == *summary_type && s.readouts.contains(&readout)) - }) -} - -/// Deployment capabilities that contradict the other planning inputs -/// ([`DeploymentCapabilities::validate`]); always bad input. -#[derive(Debug, Clone, PartialEq, Error)] -pub enum DeploymentCapabilitiesError { - /// Bad input: the data workload declares stored raw data (`AtRest` or - /// `Mixed`), but the deployment says it retains none. - #[error("the data is stored ({arrival:?}), but the deployment does not retain raw data")] - StoredDataNotRetained { - /// The declared arrival that stores raw data. - arrival: DataArrival, - }, -} - -#[cfg(test)] -mod tests { - use super::*; - - /// The default supports every summary type and readout, retains raw data and - /// keeps no query-time result across evaluations; a JSON object with - /// only some fields keeps the defaults for the rest. - #[test] - fn default_supports_everything_and_json_fills_the_rest() { - let default = DeploymentCapabilities::default(); - assert!(default.supports(&SketchAlgorithm::Bloom, StatisticKind::TopK)); - assert!(default.raw_data_retained && !default.query_time_results_retained); - let parsed: DeploymentCapabilities = serde_json::from_str( - r#"{"supported_summaries": [{"summary_type": "Kll", "readouts": ["Quantile"]}]}"#, - ) - .unwrap(); - assert!(parsed.supports(&SketchAlgorithm::Kll, StatisticKind::Quantile)); - assert!(!parsed.supports(&SketchAlgorithm::Kll, StatisticKind::Total)); - assert!(!parsed.supports(&SketchAlgorithm::DDSketch, StatisticKind::Quantile)); - assert!(parsed.raw_data_retained && !parsed.query_time_results_retained); - assert!(serde_json::from_str::(r#"{"raw_data": false}"#).is_err()); - } -} diff --git a/crates/types/src/deployment_capabilities/exclusion.rs b/crates/types/src/deployment_capabilities/exclusion.rs new file mode 100644 index 000000000..36dce3955 --- /dev/null +++ b/crates/types/src/deployment_capabilities/exclusion.rs @@ -0,0 +1,290 @@ +//! Which physical candidates a deployment rules out: a +//! [`CandidateExclusion`] matches a candidate's operator, θ, timing and +//! lifetime ([`CandidateDescription`]). Every field that is set must match +//! (AND); a field left unset matches anything; the exclusions of one +//! deployment are combined with OR. +//! +//! The fields that read a state's family (`summary_family`, +//! `sketch_parameter_range`) match the operators that build state (`SummaryAgg`, `SummaryTumblingWindowChain`) only: a merge, +//! estimate or finalization over an excluded build has no producer left, +//! so it is pruned as unbuildable without guessing its family from its +//! output schema. + +use serde::{Deserialize, Serialize}; + +use crate::ir::operator::arguments::Reduction; +use crate::ir::operator::asap::summary_type_of_operator; +use crate::ir::operator::{AggIntent, OperatorKind}; +use crate::ir::properties::ExecutionTiming; +use crate::ir::schema::FieldDataType; +use crate::ir::{ASAPOp, NonASAPOp, Operator}; +use crate::stages::PhysicalProperties; +use crate::summary_type::{ + SketchAlgorithm, SketchParameterRange, SketchParams, StatisticKind, SummaryFamily, +}; + +/// Physical candidates whose description matches every field that is set. +/// Example: `{"timing": "query_time", "operator": "Scan"}` excludes every +/// query-time scan of raw data. JSON: an object; an omitted field is +/// unset, an unknown one is refused. +#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] +#[serde(default, deny_unknown_fields)] +pub struct CandidateExclusion { + /// Matches a candidate run at this timing. + #[serde(skip_serializing_if = "Option::is_none")] + pub timing: Option, + /// `Some(true)` matches a candidate whose output is kept across + /// evaluations (lifetime `AcrossEvaluations`), `Some(false)` one whose + /// output is not. + #[serde(skip_serializing_if = "Option::is_none")] + pub kept_across_evaluations: Option, + /// Matches a candidate whose operator is of this kind. + #[serde(skip_serializing_if = "Option::is_none")] + pub operator: Option, + /// Matches an operator with a `Reduction` (`Aggregate`, `SummaryAgg`, + /// `SummaryTumblingWindowChain`): `Some(true)` per entity, `Some(false)` + /// grouped. An operator without one never matches. + #[serde(skip_serializing_if = "Option::is_none")] + pub per_entity_reduction: Option, + /// Matches an `Aggregate` operator one of whose measures is of this + /// kind, named as an `AggIntent`'s `kind` in JSON, e.g. `"rate"` or + /// `"i_rate"`. It matches the `Aggregate` only, never a state build: + /// `{"aggregate_measure": "rate", "timing": "query_time"}` excludes an + /// `Aggregate[rate]` over raw rows, but a query-time rate computed + /// from raw rows by a `SummaryAgg` of a `Rate` state is still offered. + /// To rule out that state too, add `{"summary_family": {"exact": + /// "Rate"}}`. + #[serde(skip_serializing_if = "Option::is_none")] + pub aggregate_measure: Option, + /// Matches a state build of this family. + #[serde(skip_serializing_if = "Option::is_none")] + pub summary_family: Option, + /// Matches a state build whose θ is in this range. + #[serde(skip_serializing_if = "Option::is_none")] + pub sketch_parameter_range: Option, + /// Matches a `SummaryEstimate` reading this statistic from a state of + /// this sketch algorithm. + #[serde(skip_serializing_if = "Option::is_none")] + pub readout: Option, +} + +/// A statistic read from a sketch algorithm's state, e.g. a quantile from +/// a KLL. JSON: `{"summary_type": "Kll", "statistic": "Quantile"}`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct SketchReadout { + pub summary_type: SketchAlgorithm, + pub statistic: StatisticKind, +} + +/// One physical candidate as an exclusion matches it: its operator, θ and +/// physical properties, and, for a `SummaryEstimate`, the summary type of +/// the state it reads. `C` is how the operator names its inputs: memo +/// groups in Stage 2, plan node ids when a test checks a selected plan. +#[derive(Debug, Clone, Copy)] +pub struct CandidateDescription<'a, C> { + pub operator: &'a Operator, + /// θ: the candidate's `LogicalProperties::parameters`. + pub parameters: Option<&'a SketchParams>, + pub physical_properties: PhysicalProperties, + /// For a `SummaryEstimate`: the summary type of the state it reads. + /// `None` otherwise. + pub read_summary_type: Option<&'a FieldDataType>, +} + +/// The state builds: the operators the family and θ fields match. +const STATE_BUILDS: &[OperatorKind] = &[ + OperatorKind::SummaryAgg, + OperatorKind::SummaryTumblingWindowChain, +]; + +/// An `Aggregate` or a state build: the operators with a reduction +/// (`per_entity_reduction`). +const AGGREGATE_OR_STATE_BUILD: &[OperatorKind] = &[ + OperatorKind::Aggregate, + OperatorKind::SummaryAgg, + OperatorKind::SummaryTumblingWindowChain, +]; + +impl CandidateExclusion { + /// Whether `candidate` matches every field that is set. + pub fn matches(&self, candidate: &CandidateDescription<'_, C>) -> bool { + let operator = candidate.operator; + let properties = candidate.physical_properties; + let build = summary_type_of_operator(operator); + // Each field that is set, as a test of `candidate`; an unset field + // passes. + let passes = |field: Option| field.is_none_or(|matched| matched); + passes(self.timing.map(|timing| properties.timing() == timing)) + && passes( + self.kept_across_evaluations + .map(|kept| properties.is_across_evaluations() == kept), + ) + && passes(self.operator.map(|kind| OperatorKind::of(operator) == kind)) + && passes(self.per_entity_reduction.map(|per_entity| { + reduction_of(operator) + .is_some_and(|reduction| (*reduction == Reduction::PerEntity) == per_entity) + })) + && passes(self.aggregate_measure.as_deref().map(|name| { + aggregate_measures(operator).any(|measure| measure.kind_name() == name) + })) + && passes(self.summary_family.map(|family| { + build.is_some_and(|summary_type| SummaryFamily::of(summary_type) == Some(family)) + })) + && passes(self.sketch_parameter_range.map(|range| { + build.is_some() + && candidate + .parameters + .is_some_and(|parameters| range.contains(parameters)) + })) + && passes(self.readout.map(|readout| match operator { + Operator::ASAP(ASAPOp::SummaryEstimate { query, .. }) => { + query.kind() == readout.statistic + && candidate.read_summary_type + == Some(&FieldDataType::Sketch(readout.summary_type)) + } + _ => false, + })) + } + + /// The family this exclusion rules out outright, when it sets + /// `summary_family` and no other field: every state of the family, as + /// `supported_summaries` does for an algorithm it does not list. Pass 1 + /// offers no way to compute through such a family. `None` for any + /// narrower exclusion, e.g. KLL tumbling-window chains only. + pub fn family_excluded_outright(&self) -> Option { + let family = self.summary_family?; + let family_only = Self { + summary_family: Some(family), + ..Self::default() + }; + (*self == family_only).then_some(family) + } + + /// The readout this exclusion rules out outright, when it sets + /// `readout` and no other field: every estimate of that statistic from + /// that algorithm's state, as `supported_summaries` does for a readout + /// it does not list. Pass 1 offers no build of that algorithm for a + /// measure that reads only that statistic, e.g. no KLL for a quantile + /// when KLL's `Quantile` readout is excluded. `None` for any narrower + /// exclusion. + pub fn readout_excluded_outright(&self) -> Option { + let readout = self.readout?; + let readout_only = Self { + readout: Some(readout), + ..Self::default() + }; + (*self == readout_only).then_some(readout) + } + + /// Why this exclusion is bad input, or `None` when it can be applied: + /// it sets no field (so it would exclude every candidate), two of its + /// fields match no operator in common (`{"operator": "SummaryMerge", + /// "summary_family": {"exact": "Rate"}}` matches nothing, since a + /// family matches state builds only), its θ range is invalid + /// ([`SketchParameterRange::invalid_reason`]) or ranges over another + /// algorithm than its `summary_family` (a KLL `k` range of a DDSketch + /// family matches nothing), or its `aggregate_measure` is no measure's + /// kind (`"rte"`). + pub fn invalid_reason(&self) -> Option { + if *self == Self::default() { + return Some("it sets no field, so it would exclude every candidate".to_string()); + } + let fields = self.operators_each_field_matches(); + for (index, (first, first_operators)) in fields.iter().enumerate() { + for (second, second_operators) in &fields[index + 1..] { + if !first_operators + .iter() + .any(|operator| second_operators.contains(operator)) + { + return Some(format!( + "its {first} matches {first_operators:?} only and its {second} \ + {second_operators:?} only, so it matches no candidate" + )); + } + } + } + if let Some(range) = &self.sketch_parameter_range { + if let Some(reason) = range.invalid_reason() { + return Some(reason); + } + if let Some(family) = self.summary_family { + if family != SummaryFamily::Sketch(range.algorithm()) { + return Some(format!( + "its sketch_parameter_range ranges over {:?}, which is not its summary_family {family:?}", + range.algorithm() + )); + } + } + } + if let Some(name) = &self.aggregate_measure { + if !AggIntent::is_kind_name(name) { + return Some(format!("aggregate_measure {name:?} is no measure's kind")); + } + } + None + } + + /// Each field that is set and matches only some operators, by its JSON + /// name, with those operators, as [`Self::matches`] tests them. E.g. + /// `{"operator": "SummaryMerge", "summary_family": {"exact": "Rate"}}` + /// gives `[("operator", [SummaryMerge]), ("summary_family", + /// [SummaryAgg, SummaryTumblingWindowChain])]`. + fn operators_each_field_matches(&self) -> Vec<(&'static str, &[OperatorKind])> { + let set = |field_is_set: bool, operators| field_is_set.then_some(operators); + [ + ("operator", self.operator.as_ref().map(std::slice::from_ref)), + ( + "per_entity_reduction", + set( + self.per_entity_reduction.is_some(), + AGGREGATE_OR_STATE_BUILD, + ), + ), + ( + "aggregate_measure", + set( + self.aggregate_measure.is_some(), + &[OperatorKind::Aggregate][..], + ), + ), + ( + "summary_family", + set(self.summary_family.is_some(), STATE_BUILDS), + ), + ( + "sketch_parameter_range", + set(self.sketch_parameter_range.is_some(), STATE_BUILDS), + ), + ( + "readout", + set(self.readout.is_some(), &[OperatorKind::SummaryEstimate][..]), + ), + ] + .into_iter() + .filter_map(|(field, operators)| Some((field, operators?))) + .collect() + } +} + +/// The reduction of an operator that has one: `Aggregate`, `SummaryAgg`, +/// `SummaryTumblingWindowChain`. +fn reduction_of(operator: &Operator) -> Option<&Reduction> { + match operator { + Operator::NonASAP(NonASAPOp::Aggregate { reduction, .. }) + | Operator::ASAP( + ASAPOp::SummaryAgg { reduction, .. } + | ASAPOp::SummaryTumblingWindowChain { reduction, .. }, + ) => Some(reduction), + _ => None, + } +} + +/// The measures of an `Aggregate`; none for any other operator. +fn aggregate_measures(operator: &Operator) -> impl Iterator { + let measures: &[AggIntent] = match operator { + Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) => measures, + _ => &[], + }; + measures.iter() +} diff --git a/crates/types/src/deployment_capabilities/mod.rs b/crates/types/src/deployment_capabilities/mod.rs new file mode 100644 index 000000000..912b29362 --- /dev/null +++ b/crates/types/src/deployment_capabilities/mod.rs @@ -0,0 +1,409 @@ +//! What the deployment's executor can run and keep (the third +//! deployment input, beside the cost and accuracy models). +//! +//! [`DeploymentCapabilities`] says six things: +//! +//! * which sketch summary types the executor supports, and which readouts +//! it supports for each. A summary type is supported when the executor can build +//! its state, and a readout of it when the executor can answer that +//! statistic ([`StatisticKind`](crate::summary_type::StatisticKind)) from +//! the state. Stage 2 prunes every build of an unsupported summary type +//! and every readout the executor does not answer; what reads only them +//! loses its producer. Exact accumulators and plain exact execution are +//! always supported; +//! * whether raw data samples are retained. If they are, Stage 3 counts them on +//! disk once per source, at the longest window a query-time scan of it +//! reads. If they are not, raw data samples are not retained after they arrive, so +//! Stage 2 prunes every scan of raw data at query time or kept across +//! evaluations: only ingestion-time work reads raw +//! rows. Stored data (at rest or mixed) with no raw data retained is a +//! contradiction, refused as bad input ([`DeploymentCapabilities::validate`]); +//! * whether query-time results are retained across evaluations. If they +//! are, Stage 2 also offers a tumbling-window chain whose queries evaluate +//! together at its tumbling-window width as query-time `AcrossEvaluations`: each +//! evaluation builds one new tumbling window and keeps the others for the next ones, +//! covering the queries' longest look-back. A chain two or more queries +//! read keeps its `OneEvaluation` option too (shared within one evaluation), +//! and Stage 3 picks the cheaper. If they are not, a query-time result is +//! reused only within one evaluation; +//! * what the executor's counter functions do (`counter_semantics`): +//! whether they handle counter resets and extrapolate to the range's ends. +//! One it lacks rules out the counter functions and counter states that +//! need it; +//! * which state families it cannot merge across windows +//! (`state_not_mergeable_across_windows`): it builds and finalizes their +//! state within one evaluation only, so their tumbling-window chains and +//! builds kept across evaluations are ruled out; +//! * further candidates the caller rules out directly +//! (`excluded_candidates`), e.g. a benchmark arm that must not scan raw +//! data at query time. +//! +//! Every capability a deployment lacks expands into [`CandidateExclusion`]s +//! ([`DeploymentCapabilities::exclusions`]), each with the capability it +//! comes from ([`ExclusionSource`]). The planner facade expands them once +//! and hands the list to Pass 1 (which skips the summaries they rule out +//! outright) and Stage 2, which applies them as one filter: +//! a physical candidate one of them matches is pruned with +//! `PruneReason::ExcludedByDeployment`, and its consumers lose it as an +//! input. +//! +//! The default supports everything the planner can build, retains raw data +//! and keeps no query-time result across evaluations, which is the +//! planner's behavior without deployment inputs: its only exclusion is the +//! one for query-time results kept across evaluations. + +// The executor lists the summary types it builds as `SupportedSummary`s, so the +// type lives with the readout vocabulary in `asap-types`. +use crate::ir::operator::AggIntent; +use crate::ir::operator::OperatorKind; +use crate::ir::properties::ExecutionTiming; +use crate::ir::schema::FieldDataType; +pub use crate::summary_type::SupportedSummary; +use crate::summary_type::{ExactKind, SketchAlgorithm, SummaryFamily, SummaryTypeCapability}; +use crate::workload::{DataArrival, DataWorkload}; +use serde::{Deserialize, Serialize}; +use std::fmt; +use thiserror::Error; + +mod exclusion; +#[cfg(test)] +mod tests; + +pub use exclusion::{CandidateDescription, CandidateExclusion, SketchReadout}; + +/// What the deployment's executor can run and keep. Planning reads it in +/// Pass 1 and Stage 2, as the exclusions it expands into +/// ([`DeploymentCapabilities::exclusions`]). It is data only; `asap_planner` reads it from +/// `--deployment-capabilities ` and shows it in the stage document. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(default, deny_unknown_fields)] +pub struct DeploymentCapabilities { + /// The sketch summary types the executor can build, each with the + /// readouts it can answer from one; `None` (the default) supports every summary type + /// and readout the planner can build. + pub supported_summaries: Option>, + /// Whether raw data samples are retained for query-time scans; default `true`. + pub raw_data_retained: bool, + /// Whether a query-time result may be materialized across evaluations + /// (query-time `AcrossEvaluations`); default `false`. + pub query_time_results_retained: bool, + /// What the executor's counter functions do; default: they handle + /// counter resets and extrapolate, as PromQL's do. + pub counter_semantics: CounterSemanticsSupport, + /// The state families the executor cannot merge across windows: it + /// builds and finalizes their state within one evaluation only, so no + /// tumbling-window chain or state kept across evaluations of them is + /// offered. E.g. a target without mergeable rate state lists + /// `{"exact": "Rate"}`. Default: none. + pub state_not_mergeable_across_windows: Vec, + /// Candidates the caller rules out directly, beyond what the fields + /// above imply; default none. E.g. `[{"timing": "query_time", + /// "operator": "Scan"}]` leaves only plans that read stored state. + pub excluded_candidates: Vec, +} + +impl Default for DeploymentCapabilities { + fn default() -> Self { + Self { + supported_summaries: None, + raw_data_retained: true, + query_time_results_retained: false, + counter_semantics: CounterSemanticsSupport::default(), + state_not_mergeable_across_windows: Vec::new(), + excluded_candidates: Vec::new(), + } + } +} + +/// What a deployment's counter functions (`rate`, `increase`, `irate`, +/// `resets`, and `delta`'s extrapolation) do. JSON: an object; an omitted +/// field is `true`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default, deny_unknown_fields)] +pub struct CounterSemanticsSupport { + /// A counter that drops to a lower value is taken to have reset, and + /// the drop is added back (`rate`, `increase`, `irate`, `resets`). + pub reset_handling: bool, + /// The increase over the samples is extrapolated to the range's ends + /// (`rate`, `increase`, `delta`). + pub extrapolation: bool, +} + +impl Default for CounterSemanticsSupport { + fn default() -> Self { + Self { + reset_handling: true, + extrapolation: true, + } + } +} + +/// Which capability an exclusion comes from: the reason Stage 2 records +/// for a candidate it matches (`PruneReason::ExcludedByDeployment`). +/// JSON: the snake_case variant name, e.g. `"raw_data_not_retained"`, or +/// `{"excluded_candidate": {"index": 0}}`. Printed (`Display`) as the +/// capabilities' JSON names it: `raw_data_not_retained`, or +/// `excluded_candidates[0]`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ExclusionSource { + /// `supported_summaries` does not list the sketch algorithm. + SummaryNotSupported, + /// `supported_summaries` lists the sketch algorithm, but not this + /// readout of it. + ReadoutNotSupported, + /// `raw_data_retained` is false: no query-time scan of raw data, and no + /// raw rows kept across evaluations. + RawDataNotRetained, + /// `query_time_results_retained` is false: no query-time result kept + /// across evaluations. + QueryTimeResultsNotRetained, + /// `counter_semantics.reset_handling` is false. + CounterResetsNotHandled, + /// `counter_semantics.extrapolation` is false. + CounterNotExtrapolated, + /// `state_not_mergeable_across_windows` lists the state's family. + StateNotMergeableAcrossWindows, + /// The caller's `excluded_candidates[index]`. + ExcludedCandidate { index: usize }, +} + +impl ExclusionSource { + /// Whether the default deployment ([`DeploymentCapabilities::default`]) + /// has this source too: only `QueryTimeResultsNotRetained`, which is + /// planning as it is without deployment inputs. A rejection blames the + /// deployment only for the other sources. + pub fn in_default_deployment(self) -> bool { + matches!(self, Self::QueryTimeResultsNotRetained) + } +} + +impl fmt::Display for ExclusionSource { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let name = match self { + Self::SummaryNotSupported => "summary_not_supported", + Self::ReadoutNotSupported => "readout_not_supported", + Self::RawDataNotRetained => "raw_data_not_retained", + Self::QueryTimeResultsNotRetained => "query_time_results_not_retained", + Self::CounterResetsNotHandled => "counter_resets_not_handled", + Self::CounterNotExtrapolated => "counter_not_extrapolated", + Self::StateNotMergeableAcrossWindows => "state_not_mergeable_across_windows", + Self::ExcludedCandidate { index } => { + return write!(f, "excluded_candidates[{index}]"); + } + }; + f.write_str(name) + } +} + +/// One exclusion a deployment's capabilities expand into, with the +/// capability it comes from. +#[derive(Debug, Clone, PartialEq)] +pub struct DeploymentExclusion { + pub source: ExclusionSource, + pub exclusion: CandidateExclusion, +} + +impl DeploymentCapabilities { + /// The exclusions these capabilities expand into, the caller's + /// `excluded_candidates` last (in their order): the one list Pass 1 and + /// Stage 2 read. A capability the deployment has expands into nothing, + /// so the default's only exclusion is `{timing: query_time, + /// kept_across_evaluations: true}` from `query_time_results_retained: + /// false`. E.g. `raw_data_retained: false` expands into `{timing: + /// query_time, operator: Scan}` and `{operator: Scan, + /// kept_across_evaluations: true}`, and `counter_semantics.extrapolation: + /// false` into one exclusion each for the measures `rate`, `increase` and + /// `delta` and the `Rate` and `Increase` states. A new capability is a + /// field, its expansion here and its [`ExclusionSource`]. + pub fn exclusions(&self) -> Vec { + let mut exclusions = Vec::new(); + let mut exclude = |source, exclusion| { + exclusions.push(DeploymentExclusion { source, exclusion }); + }; + if let Some(supported) = &self.supported_summaries { + // A sketch algorithm not listed: none of its states is built. + for &algorithm in SketchAlgorithm::ALL { + if !supported.iter().any(|s| s.summary_type == algorithm) { + exclude( + ExclusionSource::SummaryNotSupported, + CandidateExclusion { + summary_family: Some(SummaryFamily::Sketch(algorithm)), + ..Default::default() + }, + ); + } + } + // A listed algorithm: each statistic its state answers (its + // capability table row) that the executor does not read from it. + for listed in supported { + let answered = + SummaryTypeCapability::of(&FieldDataType::Sketch(listed.summary_type)).readouts; + for &(statistic, _) in answered { + if !listed.readouts.contains(&statistic) { + exclude( + ExclusionSource::ReadoutNotSupported, + CandidateExclusion { + readout: Some(SketchReadout { + summary_type: listed.summary_type, + statistic, + }), + ..Default::default() + }, + ); + } + } + } + } + if !self.raw_data_retained { + exclude( + ExclusionSource::RawDataNotRetained, + CandidateExclusion { + timing: Some(ExecutionTiming::QueryTime), + operator: Some(OperatorKind::Scan), + ..Default::default() + }, + ); + exclude( + ExclusionSource::RawDataNotRetained, + CandidateExclusion { + operator: Some(OperatorKind::Scan), + kept_across_evaluations: Some(true), + ..Default::default() + }, + ); + } + if !self.query_time_results_retained { + exclude( + ExclusionSource::QueryTimeResultsNotRetained, + CandidateExclusion { + timing: Some(ExecutionTiming::QueryTime), + kept_across_evaluations: Some(true), + ..Default::default() + }, + ); + } + // A counter semantics left out: the counter functions (`Aggregate` + // measures) and counter states that need it. + let counters = [ + ( + self.counter_semantics.reset_handling, + ExclusionSource::CounterResetsNotHandled, + [ + AggIntent::Rate, + AggIntent::Increase, + AggIntent::IRate, + AggIntent::Resets, + ] + .as_slice(), + [ExactKind::Rate, ExactKind::Increase, ExactKind::IRate].as_slice(), + ), + ( + self.counter_semantics.extrapolation, + ExclusionSource::CounterNotExtrapolated, + [AggIntent::Rate, AggIntent::Increase, AggIntent::Delta].as_slice(), + [ExactKind::Rate, ExactKind::Increase].as_slice(), + ), + ]; + for (supported, source, functions, states) in counters { + if supported { + continue; + } + for function in functions { + exclude( + source, + CandidateExclusion { + aggregate_measure: Some(function.kind_name()), + ..Default::default() + }, + ); + } + for &kind in states { + exclude( + source, + CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(kind)), + ..Default::default() + }, + ); + } + } + // A family not mergeable across windows: its tumbling-window chains + // (a `SummaryMerge` combines their windows) and its builds kept + // across evaluations (each evaluation merges in the rows that + // arrived since). + for &family in &self.state_not_mergeable_across_windows { + exclude( + ExclusionSource::StateNotMergeableAcrossWindows, + CandidateExclusion { + summary_family: Some(family), + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..Default::default() + }, + ); + exclude( + ExclusionSource::StateNotMergeableAcrossWindows, + CandidateExclusion { + summary_family: Some(family), + kept_across_evaluations: Some(true), + ..Default::default() + }, + ); + } + for (index, exclusion) in self.excluded_candidates.iter().enumerate() { + exclude( + ExclusionSource::ExcludedCandidate { index }, + exclusion.clone(), + ); + } + exclusions + } + + /// Checks these capabilities against the data workload: stored data + /// (at rest, or mixed) is raw data the deployment keeps, so it + /// contradicts `raw_data_retained: false`. Plan selection refuses such + /// inputs before measuring any candidate. An exclusion of + /// `excluded_candidates` that sets no field (it would exclude every + /// candidate), two of whose fields match no operator in common (a + /// `readout` with an `operator: SummaryAgg`), whose range is empty or + /// names an α outside (0, 1), whose `summary_family` its + /// `sketch_parameter_range` contradicts, or whose `aggregate_measure` names no + /// aggregate is bad input too + /// ([`DeploymentCapabilitiesError::InvalidExclusion`]). + pub fn validate(&self, data: &DataWorkload) -> Result<(), DeploymentCapabilitiesError> { + if let DataArrival::AtRest | DataArrival::Mixed { .. } = &data.arrival { + if !self.raw_data_retained { + return Err(DeploymentCapabilitiesError::StoredDataNotRetained { + arrival: data.arrival, + }); + } + } + for (index, exclusion) in self.excluded_candidates.iter().enumerate() { + if let Some(reason) = exclusion.invalid_reason() { + return Err(DeploymentCapabilitiesError::InvalidExclusion { index, reason }); + } + } + Ok(()) + } +} + +/// Deployment capabilities that contradict the other planning inputs +/// ([`DeploymentCapabilities::validate`]); always bad input. +#[derive(Debug, Clone, PartialEq, Error)] +pub enum DeploymentCapabilitiesError { + /// Bad input: the data workload declares stored raw data (`AtRest` or + /// `Mixed`), but the deployment says it retains none. + #[error("the data is stored ({arrival:?}), but the deployment does not retain raw data")] + StoredDataNotRetained { + /// The declared arrival that stores raw data. + arrival: DataArrival, + }, + /// Bad input: `excluded_candidates[index]` cannot be applied. + #[error("excluded candidate {index}: {reason}")] + InvalidExclusion { + /// Its index in `excluded_candidates`. + index: usize, + /// Why, e.g. "it sets no field, so it would exclude every candidate". + reason: String, + }, +} diff --git a/crates/types/src/deployment_capabilities/tests.rs b/crates/types/src/deployment_capabilities/tests.rs new file mode 100644 index 000000000..2c672b798 --- /dev/null +++ b/crates/types/src/deployment_capabilities/tests.rs @@ -0,0 +1,1064 @@ +//! Deployment capabilities: what each one left out expands into, how an +//! exclusion matches a physical candidate, and the JSON a caller writes. + +use super::*; +use crate::ir::operator::arguments::{Reduction, Source}; +use crate::ir::operator::AggIntent; +use crate::ir::operator::OperatorKind; +use crate::ir::properties::ExecutionTiming::{self, IngestionTime, QueryTime}; +use crate::ir::scalar::ColumnRef; +use crate::ir::schema::{FieldDataType, Schema}; +use crate::ir::{ASAPOp, NonASAPOp, Operator}; +use crate::stages::{Lifetime, PhysicalProperties, StorageMedium}; +use crate::summary_type::{ + ExactKind, ExactParams, SketchParameterRange, SketchParams, SketchStatistic, StatisticKind, + SummaryFamily, SummaryTypeCapability, SummaryUpdate, +}; + +// --------------------------------------------------------------------------- +// Fixtures: operators over child ids `usize`, and the five (τ, ℓ) Stage 2 +// offers. + +fn properties(timing: ExecutionTiming, lifetime: Lifetime) -> PhysicalProperties { + PhysicalProperties::new(timing, lifetime).unwrap() +} +fn qt_none() -> PhysicalProperties { + properties(QueryTime, Lifetime::None) +} +fn qt_one() -> PhysicalProperties { + properties(QueryTime, Lifetime::OneEvaluation(StorageMedium::Memory)) +} +fn qt_across() -> PhysicalProperties { + properties( + QueryTime, + Lifetime::AcrossEvaluations(StorageMedium::Memory), + ) +} +fn it_none() -> PhysicalProperties { + properties(IngestionTime, Lifetime::None) +} +fn it_across() -> PhysicalProperties { + properties( + IngestionTime, + Lifetime::AcrossEvaluations(StorageMedium::Memory), + ) +} + +/// A scan of the metric `m`. +fn scan() -> Operator { + Operator::NonASAP(NonASAPOp::Scan { + source: Source::TimeSeries { + metric: "m".to_string(), + }, + predicates: vec![], + schema: Schema::default(), + }) +} + +/// An `Aggregate` of `measures` with `reduction` over child 0. +fn aggregate(reduction: Reduction, measures: Vec) -> Operator { + Operator::NonASAP(NonASAPOp::Aggregate { + reduction, + output_names: vec![String::new(); measures.len()], + measures, + filters: vec![], + having: None, + child: 0, + }) +} + +/// A per-series `Aggregate` of the one `measure`. +fn per_series(measure: AggIntent) -> Operator { + aggregate(Reduction::PerEntity, vec![measure]) +} + +/// A per-series `SummaryAgg` of `summary_type` over the sample value. +fn build(summary_type: FieldDataType) -> Operator { + Operator::ASAP(ASAPOp::SummaryAgg { + child: 0, + summary_type, + input: SummaryUpdate::column(ColumnRef::SampleValue), + reduction: Reduction::PerEntity, + filter: None, + }) +} + +/// A per-series tumbling-window chain of `summary_type`, 60 s windows. +fn chain(summary_type: FieldDataType) -> Operator { + Operator::ASAP(ASAPOp::SummaryTumblingWindowChain { + child: 0, + summary_type, + input: SummaryUpdate::column(ColumnRef::SampleValue), + reduction: Reduction::PerEntity, + filter: None, + tumbling_window_width_ms: 60_000, + }) +} + +/// A merge of child 0's states, keeping its groups. +fn merge() -> Operator { + Operator::ASAP(ASAPOp::SummaryMerge { + children: vec![0], + group_by: None, + }) +} + +/// A readout of `statistic` from child 0's state. +fn estimate(statistic: SketchStatistic) -> Operator { + Operator::ASAP(ASAPOp::SummaryEstimate { + summary_input: 0, + query: statistic, + }) +} + +fn exact(kind: ExactKind) -> FieldDataType { + FieldDataType::exact(kind) +} +fn kll() -> FieldDataType { + FieldDataType::Sketch(SketchAlgorithm::Kll) +} + +/// `operator` as a candidate at `physical_properties`, with θ `parameters`. +fn described<'a>( + operator: &'a Operator, + parameters: Option<&'a SketchParams>, + physical_properties: PhysicalProperties, +) -> CandidateDescription<'a, usize> { + CandidateDescription { + operator, + parameters, + physical_properties, + read_summary_type: None, + } +} + +/// Whether `exclusion` matches `operator` at `physical_properties`, no θ. +fn matches( + exclusion: &CandidateExclusion, + operator: &Operator, + physical_properties: PhysicalProperties, +) -> bool { + exclusion.matches(&described(operator, None, physical_properties)) +} + +fn total() -> SketchStatistic { + SketchStatistic::PointCount { + key: ColumnRef::SampleValue, + value: None, + } +} + +// --------------------------------------------------------------------------- +// Matching. + +/// Timing and operator together: only the query-time scan matches. +#[test] +fn an_exclusion_matches_on_timing_and_operator() { + let exclusion = CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::Scan), + ..Default::default() + }; + assert!(matches(&exclusion, &scan(), qt_none())); + assert!(!matches(&exclusion, &scan(), it_none())); + assert!(!matches( + &exclusion, + &per_series(AggIntent::Max { col: None }), + qt_none() + )); +} + +/// A field left unset matches any value: with no timing, both scans match. +#[test] +fn an_unset_field_matches_any_value() { + let exclusion = CandidateExclusion { + operator: Some(OperatorKind::Scan), + ..Default::default() + }; + assert!(matches(&exclusion, &scan(), qt_none())); + assert!(matches(&exclusion, &scan(), it_none())); +} + +/// `kept_across_evaluations` reads the lifetime, whatever the timing: the +/// raw-data and query-time-result capabilities expand into it. +#[test] +fn kept_across_evaluations_matches_the_lifetime() { + let kept = CandidateExclusion { + kept_across_evaluations: Some(true), + ..Default::default() + }; + assert!(matches(&kept, &scan(), it_across())); + assert!(matches(&kept, &scan(), qt_across())); + assert!(!matches(&kept, &scan(), qt_one())); + assert!(!matches(&kept, &scan(), it_none())); + let not_kept = CandidateExclusion { + kept_across_evaluations: Some(false), + ..Default::default() + }; + assert!(matches(¬_kept, &scan(), qt_one())); + assert!(!matches(¬_kept, &scan(), it_across())); +} + +/// `per_entity_reduction` matches only operators that carry a +/// `Reduction`; a scan has none, so it never matches `Some(_)`. +#[test] +fn per_entity_reduction_matches_only_operators_with_a_reduction() { + let max_over_time = per_series(AggIntent::Max { col: None }); + let by_job = aggregate(Reduction::by(vec![1]), vec![AggIntent::Sum { col: None }]); + let per_entity_aggregate = CandidateExclusion { + operator: Some(OperatorKind::Aggregate), + per_entity_reduction: Some(true), + ..Default::default() + }; + assert!(matches(&per_entity_aggregate, &max_over_time, qt_none())); + assert!(!matches(&per_entity_aggregate, &by_job, qt_none())); + let per_entity = CandidateExclusion { + per_entity_reduction: Some(true), + ..Default::default() + }; + assert!(matches(&per_entity, &build(kll()), qt_one())); + assert!(!matches(&per_entity, &scan(), qt_none())); + let grouped = CandidateExclusion { + per_entity_reduction: Some(false), + ..Default::default() + }; + assert!(matches(&grouped, &by_job, qt_none())); +} + +/// A family and a θ range match the operators that build state only: the +/// `SummaryAgg` and the chain, never a merge, although the merge over a +/// KLL chain also carries the chain's θ (as the selected plans of a KLL +/// quantile do, on their `TimeRange` and `SummaryMerge`). +#[test] +fn summary_family_and_parameter_range_match_state_builds_only() { + let k547 = SketchParams::Kll { k: 547 }; + let k1404 = SketchParams::Kll { k: 1404 }; + let kll_build = build(kll()); + let kll_chain = chain(kll()); + let kll_merge = merge(); + let nodes = [ + described(&kll_build, Some(&k547), qt_one()), + described(&kll_build, Some(&k1404), qt_one()), + described(&kll_chain, Some(&k547), it_across()), + described(&kll_merge, Some(&k547), qt_one()), + ]; + let family = CandidateExclusion { + summary_family: Some(SummaryFamily::Sketch(SketchAlgorithm::Kll)), + ..Default::default() + }; + assert_eq!( + nodes.map(|node| family.matches(&node)), + [true, true, true, false] + ); + let below_1404 = CandidateExclusion { + sketch_parameter_range: Some(SketchParameterRange::KllK { + at_least: None, + at_most: Some(1403), + }), + ..Default::default() + }; + assert_eq!( + nodes.map(|node| below_1404.matches(&node)), + [true, false, true, false] + ); + let exact_sum = build(FieldDataType::ExactAggregate( + ExactKind::Sum, + ExactParams::Sum, + )); + let exclusions_of = |exclusion: CandidateExclusion| matches(&exclusion, &exact_sum, qt_one()); + assert!(exclusions_of(CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(ExactKind::Sum)), + ..Default::default() + })); + assert!(!exclusions_of(CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(ExactKind::Count)), + ..Default::default() + })); + assert!(!exclusions_of(below_1404)); +} + +/// An aggregate's measure matches an `Aggregate` one of whose measures is +/// of that kind, so a target whose query-time `rate` is excluded is not +/// given an `Aggregate[rate]` instead; a state build of a `Rate` state is +/// not an aggregate. +#[test] +fn aggregate_measure_matches_an_aggregate_computing_it() { + let query_time_rate = CandidateExclusion { + timing: Some(QueryTime), + aggregate_measure: Some("rate".to_string()), + ..Default::default() + }; + assert!(matches( + &query_time_rate, + &per_series(AggIntent::Rate), + qt_none() + )); + assert!(matches( + &query_time_rate, + &aggregate( + Reduction::PerEntity, + vec![AggIntent::Sum { col: None }, AggIntent::Rate] + ), + qt_none() + )); + assert!(!matches( + &query_time_rate, + &per_series(AggIntent::Sum { col: None }), + qt_none() + )); + assert!(!matches( + &query_time_rate, + &per_series(AggIntent::Rate), + it_none() + )); + assert!(!matches( + &query_time_rate, + &build(exact(ExactKind::Rate)), + qt_one() + )); + // A measure with arguments is named by its kind alone. + let quantile = CandidateExclusion { + aggregate_measure: Some("quantile".to_string()), + ..Default::default() + }; + assert!(matches( + &quantile, + &per_series(AggIntent::Quantile { col: None, q: 0.99 }), + qt_none() + )); +} + +/// Whether one of the exclusions `capabilities` expand into matches +/// `operator` at `physical_properties`, no θ: what Stage 2 prunes it for. +fn excluded_by( + capabilities: &DeploymentCapabilities, + operator: &Operator, + physical_properties: PhysicalProperties, +) -> bool { + capabilities + .exclusions() + .iter() + .any(|e| matches(&e.exclusion, operator, physical_properties)) +} + +/// A family not mergeable across windows expands into its tumbling-window +/// chains (whose windows a `SummaryMerge` combines) and its builds kept +/// across evaluations (each evaluation merges in the rows that arrived +/// since). Together they rule out a rate state merged across windows, at +/// either timing, and keep a query-time rate build within one evaluation. +#[test] +fn a_family_not_mergeable_across_windows_expands_into_its_chains_and_kept_builds() { + let not_mergeable = DeploymentCapabilities { + state_not_mergeable_across_windows: vec![SummaryFamily::Exact(ExactKind::Rate)], + query_time_results_retained: true, + ..Default::default() + }; + let rate = Some(SummaryFamily::Exact(ExactKind::Rate)); + let exclusion = |exclusion| DeploymentExclusion { + source: ExclusionSource::StateNotMergeableAcrossWindows, + exclusion, + }; + assert_eq!( + not_mergeable.exclusions(), + vec![ + exclusion(CandidateExclusion { + summary_family: rate, + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..Default::default() + }), + exclusion(CandidateExclusion { + summary_family: rate, + kept_across_evaluations: Some(true), + ..Default::default() + }), + ] + ); + let rate_build = build(exact(ExactKind::Rate)); + let rate_chain = chain(exact(ExactKind::Rate)); + let excluded = + |operator: &Operator, properties| excluded_by(¬_mergeable, operator, properties); + assert!(excluded(&rate_chain, it_across())); + assert!(excluded(&rate_chain, qt_across())); + assert!(excluded(&rate_build, qt_across())); + assert!(excluded(&rate_build, it_across())); + assert!(!excluded(&rate_build, qt_one())); + assert!(!excluded(&rate_build, qt_none())); + assert!(!excluded(&chain(exact(ExactKind::Sum)), it_across())); + assert!(!excluded(&per_series(AggIntent::Rate), qt_none())); +} + +/// The counter semantics a deployment lacks expand into the counter +/// functions (by their JSON `kind`) and counter states that need them: +/// without extrapolation `rate`, `increase`, `delta` and the `Rate` and +/// `Increase` states; without reset handling `rate`, `increase`, `irate` +/// (`"i_rate"`), `resets` and the `Rate`, `Increase` and `IRate` states. +/// `irate` does not extrapolate, so only reset handling rules it out. +#[test] +fn counter_semantics_left_out_expand_into_the_functions_and_states_that_need_them() { + for (measure, name) in [ + (AggIntent::Rate, "rate"), + (AggIntent::Increase, "increase"), + (AggIntent::Delta, "delta"), + (AggIntent::IRate, "i_rate"), + (AggIntent::Resets, "resets"), + ] { + assert_eq!(measure.kind_name(), name); + } + let without = |reset_handling, extrapolation| DeploymentCapabilities { + counter_semantics: CounterSemanticsSupport { + reset_handling, + extrapolation, + }, + query_time_results_retained: true, + ..Default::default() + }; + let measure = |source, name: &str| DeploymentExclusion { + source, + exclusion: CandidateExclusion { + aggregate_measure: Some(name.to_string()), + ..Default::default() + }, + }; + let state = |source, kind| DeploymentExclusion { + source, + exclusion: CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(kind)), + ..Default::default() + }, + }; + let not_extrapolated = ExclusionSource::CounterNotExtrapolated; + assert_eq!( + without(true, false).exclusions(), + vec![ + measure(not_extrapolated, "rate"), + measure(not_extrapolated, "increase"), + measure(not_extrapolated, "delta"), + state(not_extrapolated, ExactKind::Rate), + state(not_extrapolated, ExactKind::Increase), + ] + ); + let resets_not_handled = ExclusionSource::CounterResetsNotHandled; + assert_eq!( + without(false, true).exclusions(), + vec![ + measure(resets_not_handled, "rate"), + measure(resets_not_handled, "increase"), + measure(resets_not_handled, "i_rate"), + measure(resets_not_handled, "resets"), + state(resets_not_handled, ExactKind::Rate), + state(resets_not_handled, ExactKind::Increase), + state(resets_not_handled, ExactKind::IRate), + ] + ); + + // What each expansion rules out, function by function. + let functions = [ + per_series(AggIntent::Rate), + per_series(AggIntent::Increase), + per_series(AggIntent::Delta), + per_series(AggIntent::IRate), + per_series(AggIntent::Resets), + per_series(AggIntent::Sum { col: None }), + build(exact(ExactKind::Rate)), + chain(exact(ExactKind::Increase)), + build(exact(ExactKind::IRate)), + build(exact(ExactKind::Sum)), + scan(), + ]; + let ruled_out = |capabilities: &DeploymentCapabilities| { + functions + .iter() + .map(|f| excluded_by(capabilities, f, qt_one())) + .collect::>() + }; + assert_eq!( + ruled_out(&without(true, false)), + [true, true, true, false, false, false, true, true, false, false, false] + ); + assert_eq!( + ruled_out(&without(false, true)), + [true, true, false, true, true, false, true, true, true, false, false] + ); +} + +/// A readout matches a `SummaryEstimate` of that statistic reading a state +/// of that algorithm, and nothing else. +#[test] +fn readout_matches_an_estimate_by_statistic_and_the_state_it_reads() { + let kll_total = CandidateExclusion { + readout: Some(SketchReadout { + summary_type: SketchAlgorithm::Kll, + statistic: StatisticKind::Total, + }), + ..Default::default() + }; + let total_readout = estimate(total()); + let quantile_readout = estimate(SketchStatistic::Quantile { q: 0.99 }); + let cms = FieldDataType::Sketch(SketchAlgorithm::Cms); + let reading = |operator, state| CandidateDescription { + read_summary_type: state, + ..described(operator, None, qt_none()) + }; + let kll_state = kll(); + assert!(kll_total.matches(&reading(&total_readout, Some(&kll_state)))); + assert!(!kll_total.matches(&reading(&quantile_readout, Some(&kll_state)))); + assert!(!kll_total.matches(&reading(&total_readout, Some(&cms)))); + assert!(!kll_total.matches(&reading(&total_readout, None))); + assert!(!matches(&kll_total, &build(kll()), qt_one())); +} + +// --------------------------------------------------------------------------- +// Expansion. + +/// The query-time-results exclusion of the default, the one Stage 2 applies +/// today as `QueryTimeResultsNotRetained`. +fn query_time_results_exclusion() -> DeploymentExclusion { + DeploymentExclusion { + source: ExclusionSource::QueryTimeResultsNotRetained, + exclusion: CandidateExclusion { + timing: Some(QueryTime), + kept_across_evaluations: Some(true), + ..Default::default() + }, + } +} + +/// The default allows everything the planner builds: its only exclusion is +/// the query-time results kept across evaluations it does not retain, so +/// planning with the defaults prunes what it prunes today. +#[test] +fn default_capabilities_expand_into_the_query_time_results_exclusion_only() { + assert_eq!( + DeploymentCapabilities::default().exclusions(), + vec![query_time_results_exclusion()] + ); + let retaining_everything = DeploymentCapabilities { + query_time_results_retained: true, + ..Default::default() + }; + assert_eq!(retaining_everything.exclusions(), vec![]); +} + +/// Each capability left out expands into its exclusions, in the +/// documented order, and the caller's own exclusions come last with their +/// index. +#[test] +fn each_capability_left_out_expands_into_its_exclusions() { + let stored_only = CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::Scan), + ..Default::default() + }; + let capabilities = DeploymentCapabilities { + raw_data_retained: false, + query_time_results_retained: false, + counter_semantics: CounterSemanticsSupport { + reset_handling: false, + extrapolation: false, + }, + state_not_mergeable_across_windows: vec![SummaryFamily::Exact(ExactKind::Rate)], + excluded_candidates: vec![stored_only.clone()], + ..Default::default() + }; + let exclusion = |source, exclusion| DeploymentExclusion { source, exclusion }; + // The counter and mergeability expansions, item by item, are their own + // tests; here only their place in the order. + let sources: Vec = + capabilities.exclusions().iter().map(|e| e.source).collect(); + let mut expected_sources = vec![ + ExclusionSource::RawDataNotRetained, + ExclusionSource::RawDataNotRetained, + ExclusionSource::QueryTimeResultsNotRetained, + ]; + expected_sources.extend([ExclusionSource::CounterResetsNotHandled; 7]); + expected_sources.extend([ExclusionSource::CounterNotExtrapolated; 5]); + expected_sources.extend([ExclusionSource::StateNotMergeableAcrossWindows; 2]); + expected_sources.push(ExclusionSource::ExcludedCandidate { index: 0 }); + assert_eq!(sources, expected_sources); + let exclusions = capabilities.exclusions(); + let first_three_and_last: Vec = exclusions[..3] + .iter() + .chain(exclusions.last()) + .cloned() + .collect(); + assert_eq!( + first_three_and_last, + vec![ + exclusion( + ExclusionSource::RawDataNotRetained, + CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::Scan), + ..Default::default() + } + ), + exclusion( + ExclusionSource::RawDataNotRetained, + CandidateExclusion { + operator: Some(OperatorKind::Scan), + kept_across_evaluations: Some(true), + ..Default::default() + } + ), + query_time_results_exclusion(), + exclusion(ExclusionSource::ExcludedCandidate { index: 0 }, stored_only), + ] + ); +} + +/// `supported_summaries` expands into one family exclusion per sketch +/// algorithm it does not list, and one readout exclusion per statistic a +/// listed algorithm answers (its capability table row) but the deployment +/// does not. +#[test] +fn supported_summaries_expand_into_family_and_readout_exclusions() { + let capabilities = DeploymentCapabilities { + supported_summaries: Some(vec![SupportedSummary { + summary_type: SketchAlgorithm::Kll, + readouts: vec![StatisticKind::Quantile], + }]), + query_time_results_retained: true, + ..Default::default() + }; + let exclusions = capabilities.exclusions(); + let family = |algorithm| DeploymentExclusion { + source: ExclusionSource::SummaryNotSupported, + exclusion: CandidateExclusion { + summary_family: Some(SummaryFamily::Sketch(algorithm)), + ..Default::default() + }, + }; + let readout = |statistic| DeploymentExclusion { + source: ExclusionSource::ReadoutNotSupported, + exclusion: CandidateExclusion { + readout: Some(SketchReadout { + summary_type: SketchAlgorithm::Kll, + statistic, + }), + ..Default::default() + }, + }; + let unlisted: Vec<_> = SketchAlgorithm::ALL + .iter() + .filter(|&&algorithm| algorithm != SketchAlgorithm::Kll) + .map(|&algorithm| family(algorithm)) + .collect(); + let unsupported_readouts: Vec<_> = SummaryTypeCapability::of(&kll()) + .readouts() + .iter() + .map(|&(statistic, _)| statistic) + .filter(|&statistic| statistic != StatisticKind::Quantile) + .map(readout) + .collect(); + for expected in unlisted.iter().chain(&unsupported_readouts) { + assert!(exclusions.contains(expected), "missing {expected:?}"); + } + assert!(!exclusions.contains(&family(SketchAlgorithm::Kll))); + assert!(!exclusions.contains(&readout(StatisticKind::Quantile))); + assert_eq!( + exclusions.len(), + unlisted.len() + unsupported_readouts.len() + ); +} + +// --------------------------------------------------------------------------- +// Validation and JSON. + +/// An exclusion that cannot be applied is bad input, named by its index: +/// one that sets no field (it would exclude every candidate), an empty +/// range, an α that is not a number in (0, 1), a family its θ range +/// contradicts, or a measure no aggregate has. +#[test] +fn invalid_excluded_candidates_are_rejected() { + let data = crate::workload::DataWorkload::default(); + let valid = CandidateExclusion { + operator: Some(OperatorKind::Scan), + ..Default::default() + }; + let with = |bad: CandidateExclusion| DeploymentCapabilities { + excluded_candidates: vec![valid.clone(), bad], + ..Default::default() + }; + let range = |range| CandidateExclusion { + sketch_parameter_range: Some(range), + ..Default::default() + }; + let invalid = [ + CandidateExclusion::default(), + range(SketchParameterRange::KllK { + at_least: Some(1404), + at_most: Some(547), + }), + range(SketchParameterRange::DDSketchAlpha { + at_least: Some(f64::NAN), + at_most: None, + }), + range(SketchParameterRange::DDSketchAlpha { + at_least: None, + at_most: Some(1.0), + }), + CandidateExclusion { + summary_family: Some(SummaryFamily::Sketch(SketchAlgorithm::DDSketch)), + sketch_parameter_range: Some(SketchParameterRange::KllK { + at_least: None, + at_most: Some(1403), + }), + ..Default::default() + }, + CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(ExactKind::Sum)), + sketch_parameter_range: Some(SketchParameterRange::KmvK { + at_least: Some(4323), + at_most: None, + }), + ..Default::default() + }, + CandidateExclusion { + aggregate_measure: Some("rte".to_string()), + ..Default::default() + }, + ]; + for bad in invalid { + let result = with(bad.clone()).validate(&data); + assert!( + matches!( + result, + Err(DeploymentCapabilitiesError::InvalidExclusion { index: 1, .. }) + ), + "{bad:?}: {result:?}" + ); + } + assert_eq!(DeploymentCapabilities::default().validate(&data), Ok(())); + let valid_only = DeploymentCapabilities { + excluded_candidates: vec![valid], + ..Default::default() + }; + assert_eq!(valid_only.validate(&data), Ok(())); +} + +/// An exclusion whose fields match no operator in common contradicts +/// itself and matches nothing, so it is bad input: a state family, θ range +/// (state builds only) with another operator, an +/// `aggregate_measure` (an `Aggregate` only) with another operator, a +/// `readout` (a `SummaryEstimate` only) with another operator or with a +/// build-only field, and `per_entity_reduction` with an operator that has +/// no reduction. Fields that do share an operator are accepted. +#[test] +fn self_contradicting_exclusions_are_rejected() { + let data = crate::workload::DataWorkload::default(); + let kll_readout = SketchReadout { + summary_type: SketchAlgorithm::Kll, + statistic: StatisticKind::Quantile, + }; + let with_operator = |operator, exclusion: CandidateExclusion| CandidateExclusion { + operator: Some(operator), + ..exclusion + }; + let family = CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(ExactKind::Rate)), + ..Default::default() + }; + let parameters = CandidateExclusion { + sketch_parameter_range: Some(SketchParameterRange::KllK { + at_least: None, + at_most: Some(1403), + }), + ..Default::default() + }; + let measure = CandidateExclusion { + aggregate_measure: Some("rate".to_string()), + ..Default::default() + }; + let readout = CandidateExclusion { + readout: Some(kll_readout), + ..Default::default() + }; + let per_entity = CandidateExclusion { + per_entity_reduction: Some(true), + ..Default::default() + }; + let contradicting = [ + // The review's repro: `{"operator": "SummaryMerge", "summary_family": + // {"exact": "Rate"}}`. + with_operator(OperatorKind::SummaryMerge, family.clone()), + with_operator(OperatorKind::SummaryEstimate, parameters.clone()), + with_operator(OperatorKind::SummaryAgg, measure.clone()), + with_operator(OperatorKind::SummaryAgg, readout.clone()), + CandidateExclusion { + readout: Some(kll_readout), + ..family.clone() + }, + CandidateExclusion { + readout: Some(kll_readout), + ..parameters.clone() + }, + with_operator(OperatorKind::Scan, per_entity.clone()), + ]; + for bad in contradicting { + let capabilities = DeploymentCapabilities { + excluded_candidates: vec![bad.clone()], + ..Default::default() + }; + let result = capabilities.validate(&data); + assert!( + matches!( + result, + Err(DeploymentCapabilitiesError::InvalidExclusion { index: 0, .. }) + ), + "{bad:?}: {result:?}" + ); + } + let consistent = [ + with_operator(OperatorKind::SummaryTumblingWindowChain, family.clone()), + with_operator(OperatorKind::SummaryAgg, parameters), + with_operator(OperatorKind::Aggregate, measure.clone()), + with_operator(OperatorKind::SummaryEstimate, readout), + with_operator(OperatorKind::SummaryAgg, per_entity.clone()), + CandidateExclusion { + per_entity_reduction: Some(true), + ..measure + }, + CandidateExclusion { + per_entity_reduction: Some(true), + ..family + }, + ]; + for good in consistent { + let capabilities = DeploymentCapabilities { + excluded_candidates: vec![good.clone()], + ..Default::default() + }; + assert_eq!(capabilities.validate(&data), Ok(()), "{good:?}"); + } +} + +/// Only an exclusion that sets `summary_family` and nothing else rules a +/// family out outright, as `supported_summaries` does for an algorithm it +/// does not list; any further field narrows it. +#[test] +fn a_family_is_excluded_outright_only_by_a_family_only_exclusion() { + let kll = SummaryFamily::Sketch(SketchAlgorithm::Kll); + let family_only = CandidateExclusion { + summary_family: Some(kll), + ..Default::default() + }; + assert_eq!(family_only.family_excluded_outright(), Some(kll)); + let narrower = CandidateExclusion { + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..family_only + }; + assert_eq!(narrower.family_excluded_outright(), None); + let scans = CandidateExclusion { + operator: Some(OperatorKind::Scan), + ..Default::default() + }; + assert_eq!(scans.family_excluded_outright(), None); + let exact_only = DeploymentCapabilities { + supported_summaries: Some(vec![]), + ..Default::default() + }; + let outright: Vec = exact_only + .exclusions() + .iter() + .filter_map(|e| e.exclusion.family_excluded_outright()) + .collect(); + let every_sketch: Vec = SketchAlgorithm::ALL + .iter() + .map(|&algorithm| SummaryFamily::Sketch(algorithm)) + .collect(); + assert_eq!(outright, every_sketch); +} + +/// The exclusions of an arm with no query-time scan, written as the caller +/// writes them, plus a KLL size range: they load field by field and +/// round-trip; a misspelled or removed field is refused; `{}` is the +/// default; and the new capabilities fill their defaults field by field. +#[test] +fn excluded_candidates_json_loads_field_by_field() { + let json = r#"{"excluded_candidates": [ + {"timing": "query_time", "operator": "Scan"}, + {"operator": "Aggregate", "per_entity_reduction": true}, + {"timing": "query_time", "operator": "SummaryAgg"}, + {"timing": "query_time", "operator": "SummaryTumblingWindowChain"}, + {"summary_family": {"sketch": "Kll"}, "sketch_parameter_range": {"kll_k": {"at_most": 1403}}}, + {"timing": "query_time", "aggregate_measure": "rate"}, + {"summary_family": {"exact": "Rate"}, "operator": "SummaryTumblingWindowChain"}, + {"readout": {"summary_type": "Kll", "statistic": "Total"}}, + {"operator": "Scan", "kept_across_evaluations": true}]}"#; + let loaded: DeploymentCapabilities = serde_json::from_str(json).unwrap(); + let exclusion = |exclusion: CandidateExclusion| exclusion; + assert_eq!( + loaded.excluded_candidates, + vec![ + exclusion(CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::Scan), + ..Default::default() + }), + exclusion(CandidateExclusion { + operator: Some(OperatorKind::Aggregate), + per_entity_reduction: Some(true), + ..Default::default() + }), + exclusion(CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::SummaryAgg), + ..Default::default() + }), + exclusion(CandidateExclusion { + timing: Some(QueryTime), + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..Default::default() + }), + exclusion(CandidateExclusion { + summary_family: Some(SummaryFamily::Sketch(SketchAlgorithm::Kll)), + sketch_parameter_range: Some(SketchParameterRange::KllK { + at_least: None, + at_most: Some(1403), + }), + ..Default::default() + }), + exclusion(CandidateExclusion { + timing: Some(QueryTime), + aggregate_measure: Some("rate".to_string()), + ..Default::default() + }), + exclusion(CandidateExclusion { + summary_family: Some(SummaryFamily::Exact(ExactKind::Rate)), + operator: Some(OperatorKind::SummaryTumblingWindowChain), + ..Default::default() + }), + exclusion(CandidateExclusion { + readout: Some(SketchReadout { + summary_type: SketchAlgorithm::Kll, + statistic: StatisticKind::Total, + }), + ..Default::default() + }), + exclusion(CandidateExclusion { + operator: Some(OperatorKind::Scan), + kept_across_evaluations: Some(true), + ..Default::default() + }), + ] + ); + let written = serde_json::to_string(&loaded).unwrap(); + assert_eq!( + serde_json::from_str::(&written).unwrap(), + loaded + ); + for refused in [ + r#"{"excluded_candidates": [{"timing": "query_time", "operater": "Scan"}]}"#, + // Counter semantics and mergeability are capabilities, not + // exclusion fields; θ ranges are `sketch_parameter_range`. + r#"{"excluded_candidates": [{"counter_semantics": "extrapolation"}]}"#, + r#"{"excluded_candidates": [{"summary_family": {"exact": "Rate"}, "merged_across_windows": true}]}"#, + r#"{"excluded_candidates": [{"sketch_parameters": {"kll_k": {"at_most": 1403}}}]}"#, + ] { + assert!( + serde_json::from_str::(refused).is_err(), + "{refused}" + ); + } + assert_eq!( + serde_json::from_str::("{}").unwrap(), + DeploymentCapabilities::default() + ); + let counters: DeploymentCapabilities = serde_json::from_str( + r#"{"counter_semantics": {"extrapolation": false}, + "state_not_mergeable_across_windows": [{"exact": "Rate"}]}"#, + ) + .unwrap(); + assert_eq!( + counters.counter_semantics, + CounterSemanticsSupport { + reset_handling: true, + extrapolation: false, + } + ); + assert_eq!( + counters.state_not_mergeable_across_windows, + vec![SummaryFamily::Exact(ExactKind::Rate)] + ); + assert!(serde_json::from_str::( + r#"{"counter_semantics": {"extrapolates": false}}"# + ) + .is_err()); +} + +/// The default retains raw data and keeps no query-time result across +/// evaluations; a JSON object with only some fields keeps the defaults for +/// the rest, and an unknown field is refused. +#[test] +fn default_capabilities_and_json_fill_the_rest() { + let default = DeploymentCapabilities::default(); + assert!(default.raw_data_retained && !default.query_time_results_retained); + assert_eq!(default.supported_summaries, None); + let parsed: DeploymentCapabilities = serde_json::from_str( + r#"{"supported_summaries": [{"summary_type": "Kll", "readouts": ["Quantile"]}]}"#, + ) + .unwrap(); + assert_eq!( + parsed.supported_summaries, + Some(vec![SupportedSummary { + summary_type: SketchAlgorithm::Kll, + readouts: vec![StatisticKind::Quantile], + }]) + ); + assert!(parsed.raw_data_retained && !parsed.query_time_results_retained); + assert!(serde_json::from_str::(r#"{"raw_data": false}"#).is_err()); +} + +/// A source prints as the capabilities' JSON names it, the caller's own +/// exclusion by its index; only the default deployment's own source (no +/// query-time result kept across evaluations) is in the default +/// deployment. +#[test] +fn exclusion_sources_print_as_their_json_names() { + let every_source = [ + ExclusionSource::SummaryNotSupported, + ExclusionSource::ReadoutNotSupported, + ExclusionSource::RawDataNotRetained, + ExclusionSource::QueryTimeResultsNotRetained, + ExclusionSource::CounterResetsNotHandled, + ExclusionSource::CounterNotExtrapolated, + ExclusionSource::StateNotMergeableAcrossWindows, + ExclusionSource::ExcludedCandidate { index: 2 }, + ]; + for source in every_source { + let printed = source.to_string(); + match source { + ExclusionSource::ExcludedCandidate { .. } => { + assert_eq!(printed, "excluded_candidates[2]") + } + _ => assert_eq!(serde_json::to_value(source).unwrap(), printed.as_str()), + } + } + assert_eq!( + ExclusionSource::CounterNotExtrapolated.to_string(), + "counter_not_extrapolated" + ); + let default_sources: Vec = DeploymentCapabilities::default() + .exclusions() + .iter() + .map(|e| e.source) + .collect(); + for source in every_source { + assert_eq!( + source.in_default_deployment(), + default_sources.contains(&source), + "{source}" + ); + } +} + +/// The error names the exclusion once; the planner adds the +/// "deployment capabilities" context. +#[test] +fn an_invalid_exclusion_error_names_its_index_once() { + let error = DeploymentCapabilitiesError::InvalidExclusion { + index: 0, + reason: "it sets no field".to_string(), + }; + assert_eq!(error.to_string(), "excluded candidate 0: it sets no field"); +} diff --git a/crates/types/src/ir/operator/agg_intent.rs b/crates/types/src/ir/operator/agg_intent.rs index 2a432b764..03de55d09 100644 --- a/crates/types/src/ir/operator/agg_intent.rs +++ b/crates/types/src/ir/operator/agg_intent.rs @@ -372,6 +372,29 @@ pub enum MathFunc { // `asap_frontend_promql::promql::reduction_for`) — so they stay generic // alongside `input_col`, in one `impl` block. impl AggIntent { + /// The measure's kind as its JSON `kind` names it, without its + /// arguments: `"rate"` for `Rate`, `"quantile"` for `Quantile { q: 0.99, + /// .. }`. Measured operation costs and deployment exclusions name + /// measures by it. + pub fn kind_name(&self) -> String { + serde_json::to_value(self) + .ok() + .and_then(|value| value.get("kind")?.as_str().map(str::to_owned)) + .unwrap_or_else(|| format!("{self:?}")) + } + + /// Whether `name` is the JSON `kind` of some measure: `"rate"` is, + /// `"rte"` is not. A kind whose measure has arguments (`"quantile"`) + /// counts, although `{"kind": "quantile"}` alone is not a measure. + pub fn is_kind_name(name: &str) -> bool { + match serde_json::from_value::(serde_json::json!({ "kind": name })) { + Ok(_) => true, + // Serde names an unknown tag `unknown variant`; any other error + // is a known kind missing its arguments. + Err(error) => !error.to_string().starts_with("unknown variant"), + } + } + /// This intent with every column renumbered by `column`: the value /// columns of [`input_cols`](AggIntent::input_cols) and /// `histogram_quantile`'s `le`. `Sum { col: Some(1) }` under a renumbering diff --git a/crates/types/src/ir/operator/asap.rs b/crates/types/src/ir/operator/asap.rs index 4376a0553..f13f57d4f 100644 --- a/crates/types/src/ir/operator/asap.rs +++ b/crates/types/src/ir/operator/asap.rs @@ -262,14 +262,9 @@ impl ASAPOp { summary_type: family, .. } => Some(family), - ASAPOp::SummaryMerge { children, .. } => children.first().and_then(|child| { - child - .schema() - .fields - .iter() - .find(|field| !field.is_plain()) - .map(|field| &field.dtype) - }), + ASAPOp::SummaryMerge { children, .. } => children + .first() + .and_then(|child| child.schema().summary_state_type()), _ => None, } } diff --git a/crates/types/src/ir/operator/kind.rs b/crates/types/src/ir/operator/kind.rs new file mode 100644 index 000000000..74ab2b665 --- /dev/null +++ b/crates/types/src/ir/operator/kind.rs @@ -0,0 +1,92 @@ +//! The kind of an operator without its arguments: the name every operator +//! has in a physical plan DAG. Measured operation costs are keyed by it, +//! and deployment exclusions match on it. + +use serde::{Deserialize, Serialize}; + +use super::asap::ASAPOp; +use super::node::Operator; +use super::non_asap::NonASAPOp; + +/// An operator without its arguments: every physical operator a physical +/// plan DAG can contain, by the name it has there, e.g. `Scan` or +/// `SummaryTumblingWindowChain`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub enum OperatorKind { + Scan, + Values, + Filter, + Project, + Aggregate, + Join, + SetOp, + Concat, + Dedup, + Sort, + Limit, + BinaryOp, + SQLWindowFunc, + TimeRange, + TimeShift, + PromqlVectorFromScalar, + PromqlRelabel, + PromqlInfoEnrich, + PromqlSeriesSample, + PromqlSubquery, + SummaryAgg, + SummaryEstimate, + FinalizeExactAccumulator, + MaintainPopulation, + EvaluatePopulation, + SummaryMerge, + // Formerly named `PaneChain`; old JSON still loads. + #[serde(alias = "PaneChain")] + SummaryTumblingWindowChain, + SummarySubtract, + SummaryDelete, + SummaryJoin, + Extension, +} + +impl OperatorKind { + /// The kind of `operator`, e.g. `Scan` for a `NonASAPOp::Scan`. + pub fn of(operator: &Operator) -> Self { + match operator { + Operator::NonASAP(op) => match op { + NonASAPOp::Scan { .. } => Self::Scan, + NonASAPOp::Values { .. } => Self::Values, + NonASAPOp::Filter { .. } => Self::Filter, + NonASAPOp::Project { .. } => Self::Project, + NonASAPOp::Aggregate { .. } => Self::Aggregate, + NonASAPOp::Join { .. } => Self::Join, + NonASAPOp::SetOp { .. } => Self::SetOp, + NonASAPOp::Concat { .. } => Self::Concat, + NonASAPOp::Dedup { .. } => Self::Dedup, + NonASAPOp::Sort { .. } => Self::Sort, + NonASAPOp::Limit { .. } => Self::Limit, + NonASAPOp::BinaryOp { .. } => Self::BinaryOp, + NonASAPOp::SQLWindowFunc { .. } => Self::SQLWindowFunc, + NonASAPOp::TimeRange { .. } => Self::TimeRange, + NonASAPOp::TimeShift { .. } => Self::TimeShift, + NonASAPOp::PromqlVectorFromScalar(_) => Self::PromqlVectorFromScalar, + NonASAPOp::PromqlRelabel { .. } => Self::PromqlRelabel, + NonASAPOp::PromqlInfoEnrich { .. } => Self::PromqlInfoEnrich, + NonASAPOp::PromqlSeriesSample { .. } => Self::PromqlSeriesSample, + NonASAPOp::PromqlSubquery { .. } => Self::PromqlSubquery, + }, + Operator::ASAP(op) => match op { + ASAPOp::SummaryAgg { .. } => Self::SummaryAgg, + ASAPOp::SummaryEstimate { .. } => Self::SummaryEstimate, + ASAPOp::FinalizeExactAccumulator { .. } => Self::FinalizeExactAccumulator, + ASAPOp::MaintainPopulation { .. } => Self::MaintainPopulation, + ASAPOp::EvaluatePopulation { .. } => Self::EvaluatePopulation, + ASAPOp::SummaryMerge { .. } => Self::SummaryMerge, + ASAPOp::SummaryTumblingWindowChain { .. } => Self::SummaryTumblingWindowChain, + ASAPOp::SummarySubtract { .. } => Self::SummarySubtract, + ASAPOp::SummaryDelete { .. } => Self::SummaryDelete, + ASAPOp::SummaryJoin { .. } => Self::SummaryJoin, + ASAPOp::Extension { .. } => Self::Extension, + }, + } + } +} diff --git a/crates/types/src/ir/operator/mod.rs b/crates/types/src/ir/operator/mod.rs index 5da385dc3..b4cf9948e 100644 --- a/crates/types/src/ir/operator/mod.rs +++ b/crates/types/src/ir/operator/mod.rs @@ -9,6 +9,7 @@ //! - [`arguments`] — operator argument types ([`GroupKeys`], //! [`Reduction`], [`Source`], …). //! - [`agg_intent`] — the aggregation-intent vocabulary ([`AggIntent`]). +//! - [`kind`] — an operator's kind without its arguments ([`OperatorKind`]). //! - [`maintained_population`] — maintained populations and their evaluations. //! - [`tumbling_window_chain`] — what a tumbling-window chain computes. //! - [`query`] — a query root: an operator result or a standalone scalar. @@ -16,6 +17,7 @@ pub mod agg_intent; pub mod arguments; pub mod asap; pub mod input; +pub mod kind; pub mod maintained_population; pub mod node; pub mod non_asap; @@ -32,3 +34,4 @@ pub use arguments::{ VectorGrouping, VectorMatch, VectorMatchKind, WindowFrame, WindowFrameBound, WindowFrameOffset, WindowFrameUnits, WindowFuncKind, }; +pub use kind::OperatorKind; diff --git a/crates/types/src/ir/schema/mod.rs b/crates/types/src/ir/schema/mod.rs index 47ed0bbd8..4cb5b9039 100644 --- a/crates/types/src/ir/schema/mod.rs +++ b/crates/types/src/ir/schema/mod.rs @@ -289,6 +289,16 @@ pub fn is_label_set_column(field: &Field) -> bool { } impl Schema { + /// The type of the summary state this schema carries: its first field + /// that is not a plain value, e.g. `Sketch(Kll)` for a KLL state keyed + /// by series; `None` for rows of plain values. + pub fn summary_state_type(&self) -> Option<&FieldDataType> { + self.fields + .iter() + .find(|field| !field.is_plain()) + .map(|field| &field.dtype) + } + pub fn has_promql_series_identity(&self) -> bool { self.closed && self.fields.iter().any(|field| { diff --git a/crates/types/src/stages/pruning.rs b/crates/types/src/stages/pruning.rs index 003a8d45c..f4f9f026b 100644 --- a/crates/types/src/stages/pruning.rs +++ b/crates/types/src/stages/pruning.rs @@ -11,6 +11,7 @@ //! type, so no reason names it. use crate::accuracy::AccuracyMetric; +use crate::deployment_capabilities::ExclusionSource; use crate::stages::{CandidateForMemoGroupId, PhysicalCandidateId, RequiredAccuracy}; /// A candidate eliminated by Pass 2. @@ -113,22 +114,14 @@ pub struct PrunedCandidate { /// Why a stage removed a candidate: first Stage 2's (the physical candidate /// cannot be built, run or read by a query output), then Stage 3's, before /// its selection MILP. JSON: the snake_case variant name, e.g. -/// `"raw_data_not_retained"`, or `{"dominated_by": 3}`. +/// `"no_ingestion_pipeline"`, `{"excluded_by_deployment": +/// "raw_data_not_retained"}` or `{"dominated_by": 3}`. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize)] #[serde(rename_all = "snake_case")] pub enum PruneReason { /// Stage 2: it runs at ingestion time, and the source has no ingestion /// pipeline (its data is at rest or its arrival unknown). NoIngestionPipeline, - /// Stage 2: it scans raw data at query time, or retains the raw rows it - /// scans across evaluations, and the deployment does not retain raw - /// data, so no window of it is there to scan or keep. - RawDataNotRetained, - /// Stage 2: it is a query-time result materialized across evaluations - /// (`AcrossEvaluations`), and the deployment retains no query-time - /// result across evaluations - /// (`DeploymentCapabilities::query_time_results_retained`). - QueryTimeResultsNotRetained, /// Stage 2: one of its inputs has no producer candidate that can be /// built: none is left, or every one depends, directly or through a /// cycle, on an input that cannot be built. @@ -140,6 +133,12 @@ pub enum PruneReason { /// weight column's `column_signs` is not `NonNegative`: its estimates are /// bounds only for non-negative weights. CountMinWeightsNotProvenNonNegative, + /// Stage 2: the deployment's capabilities exclude it + /// (`DeploymentCapabilities::exclusions`): the executor cannot run it, + /// or the caller ruled it out. Names the capability the matching + /// exclusion comes from, e.g. `RawDataNotRetained` for a query-time + /// scan when raw data is not retained. + ExcludedByDeployment(ExclusionSource), /// Stage 3: the candidate it names, in the same memo group with the /// same producers and consumers, is at least as good in every respect /// (guarantee, usage, latency, output, held state), so no optimal plan diff --git a/crates/types/src/summary_type/family.rs b/crates/types/src/summary_type/family.rs new file mode 100644 index 000000000..348fe9129 --- /dev/null +++ b/crates/types/src/summary_type/family.rs @@ -0,0 +1,64 @@ +//! A summary state's family without its parameters: the vocabulary +//! deployment exclusions (and a later calibration filter) match on. + +use serde::{Deserialize, Serialize}; + +use super::{ExactKind, SketchAlgorithm}; +use crate::ir::schema::FieldDataType; + +/// The family of a summary state without its parameters: a sketch +/// algorithm or an exact accumulator kind. JSON: `{"sketch": "Kll"}`, +/// `{"exact": "Sum"}`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SummaryFamily { + Sketch(SketchAlgorithm), + Exact(ExactKind), +} + +impl SummaryFamily { + /// `Sketch(Kll)` for `FieldDataType::Sketch(Kll)`, `Exact(Sum)` for + /// `ExactAggregate(Sum, _)`, `None` for any other field type. + pub fn of(summary_type: &FieldDataType) -> Option { + match summary_type { + FieldDataType::Sketch(algorithm) => Some(Self::Sketch(*algorithm)), + FieldDataType::ExactAggregate(kind, _) => Some(Self::Exact(*kind)), + _ => None, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::ir::schema::DataType; + use crate::summary_type::ExactParams; + + /// A sketch state is its algorithm, an exact accumulator its kind, and + /// a plain value has no family. + #[test] + fn summary_family_of_a_field_type() { + assert_eq!( + SummaryFamily::of(&FieldDataType::Sketch(SketchAlgorithm::Kll)), + Some(SummaryFamily::Sketch(SketchAlgorithm::Kll)) + ); + assert_eq!( + SummaryFamily::of(&FieldDataType::ExactAggregate( + ExactKind::Sum, + ExactParams::Sum + )), + Some(SummaryFamily::Exact(ExactKind::Sum)) + ); + assert_eq!( + SummaryFamily::of(&FieldDataType::ExactAggregate( + ExactKind::Rate, + ExactParams::Rate + )), + Some(SummaryFamily::Exact(ExactKind::Rate)) + ); + assert_eq!( + SummaryFamily::of(&FieldDataType::Plain(DataType::Float64)), + None + ); + } +} diff --git a/crates/types/src/summary_type/mod.rs b/crates/types/src/summary_type/mod.rs index 9cc98adb5..293a70718 100644 --- a/crates/types/src/summary_type/mod.rs +++ b/crates/types/src/summary_type/mod.rs @@ -3,6 +3,7 @@ //! statistics read from it, and each summary type's capabilities. mod capability; +mod family; mod parameter_lists; mod parameters; mod statistic; @@ -17,10 +18,12 @@ pub use asap_sketchlib::SketchAlgorithm; pub use capability::{ MergeInputRule, MergedError, StatisticKind, SummaryTypeCapability, SupportedSummary, }; +pub use family::SummaryFamily; pub use parameter_lists::parameter_list; pub use parameters::{ - ExactKind, ExactParams, HydraParams, SamplingKind, SamplingParams, SketchParams, StatModelKind, - StatModelParams, WaveletKind, WaveletParams, EXACT_ACCUMULATOR_STATE_BYTES, KLL_MAX_K, + ExactKind, ExactParams, HydraParams, SamplingKind, SamplingParams, SketchParameterRange, + SketchParams, StatModelKind, StatModelParams, WaveletKind, WaveletParams, + EXACT_ACCUMULATOR_STATE_BYTES, KLL_MAX_K, }; pub use statistic::SketchStatistic; pub use update::{EntityIdentity, SummaryInputExpr, SummaryUpdate}; diff --git a/crates/types/src/summary_type/parameters.rs b/crates/types/src/summary_type/parameters.rs index 21cce4b0b..b4e1ca31d 100644 --- a/crates/types/src/summary_type/parameters.rs +++ b/crates/types/src/summary_type/parameters.rs @@ -268,3 +268,148 @@ impl HydraParams { } } } + +/// An inclusive range of one sketch parameter; an unset bound is open. +/// JSON: `{"kll_k": {"at_most": 1403}}`, +/// `{"ddsketch_alpha": {"at_least": 0.01}}`. +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case", deny_unknown_fields)] +pub enum SketchParameterRange { + KllK { + #[serde(default, skip_serializing_if = "Option::is_none")] + at_least: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + at_most: Option, + }, + KmvK { + #[serde(default, skip_serializing_if = "Option::is_none")] + at_least: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + at_most: Option, + }, + #[serde(rename = "ddsketch_alpha")] + DDSketchAlpha { + #[serde(default, skip_serializing_if = "Option::is_none")] + at_least: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + at_most: Option, + }, +} + +impl SketchParameterRange { + /// The algorithm whose parameter it ranges over (`Kll`, `Kmv`, + /// `DDSketch`). + pub fn algorithm(&self) -> super::SketchAlgorithm { + use super::SketchAlgorithm; + match self { + Self::KllK { .. } => SketchAlgorithm::Kll, + Self::KmvK { .. } => SketchAlgorithm::Kmv, + Self::DDSketchAlpha { .. } => SketchAlgorithm::DDSketch, + } + } + + /// Whether `parameters` are that algorithm's and the parameter is in + /// range, both ends included: `KllK { at_most: Some(547) }` contains + /// `Kll { k: 547 }`, not `Kll { k: 1404 }` nor any `Kmv`. + pub fn contains(&self, parameters: &SketchParams) -> bool { + fn within(value: T, at_least: Option, at_most: Option) -> bool { + at_least.is_none_or(|low| value >= low) && at_most.is_none_or(|high| value <= high) + } + match (*self, parameters) { + (Self::KllK { at_least, at_most }, SketchParams::Kll { k }) + | (Self::KmvK { at_least, at_most }, SketchParams::Kmv { k }) => { + within(*k, at_least, at_most) + } + (Self::DDSketchAlpha { at_least, at_most }, SketchParams::DDSketch { alpha }) => { + within(*alpha, at_least, at_most) + } + _ => false, + } + } + + /// Why the range is bad input, or `None` when it is valid: `at_least` + /// is above `at_most`, so it contains no value (`KllK { at_least: 1404, + /// at_most: 547 }`), or a DDSketch α bound is not a number in (0, 1). + pub fn invalid_reason(&self) -> Option { + let (at_least, at_most) = match *self { + Self::KllK { at_least, at_most } | Self::KmvK { at_least, at_most } => { + (at_least.map(f64::from), at_most.map(f64::from)) + } + Self::DDSketchAlpha { at_least, at_most } => { + if let Some(alpha) = [at_least, at_most] + .into_iter() + .flatten() + .find(|alpha| !(*alpha > 0.0 && *alpha < 1.0)) + { + return Some(format!("a DDSketch alpha of {alpha} is not in (0, 1)")); + } + (at_least, at_most) + } + }; + match (at_least, at_most) { + (Some(low), Some(high)) if low > high => Some(format!( + "the range is empty: at_least {low} is above at_most {high}" + )), + _ => None, + } + } +} + +#[cfg(test)] +mod sketch_parameter_range_tests { + use super::*; + use crate::summary_type::SketchAlgorithm; + + /// Both ends of a `k` range are included, an unset end is open, and a + /// range over KLL's `k` never contains another algorithm's parameters. + #[test] + fn kll_k_range_bounds_are_inclusive() { + let k547 = SketchParams::Kll { k: 547 }; + let k1404 = SketchParams::Kll { k: 1404 }; + let at_most_547 = SketchParameterRange::KllK { + at_least: None, + at_most: Some(547), + }; + assert!(at_most_547.contains(&k547)); + assert!(!at_most_547.contains(&k1404)); + let at_least_1404 = SketchParameterRange::KllK { + at_least: Some(1404), + at_most: None, + }; + assert!(at_least_1404.contains(&k1404)); + assert!(!at_least_1404.contains(&k547)); + let at_most_2863 = SketchParameterRange::KllK { + at_least: None, + at_most: Some(2863), + }; + assert_eq!(at_most_2863.algorithm(), SketchAlgorithm::Kll); + assert!(!at_most_2863.contains(&SketchParams::Kmv { k: 547 })); + assert!(!at_most_2863.contains(&SketchParams::DDSketch { alpha: 0.01 })); + } + + /// A KMV `k` range and a DDSketch α range each select their own + /// algorithm's listed sizes (`parameter_list`), both ends included. + #[test] + fn kmv_k_and_ddsketch_alpha_ranges_select_their_own_parameter() { + let kmv = SketchParameterRange::KmvK { + at_least: Some(4323), + at_most: None, + }; + assert_eq!(kmv.algorithm(), SketchAlgorithm::Kmv); + let kmv_contained: Vec = [1_118, 4_323, 26_656, 106_263] + .into_iter() + .map(|k| kmv.contains(&SketchParams::Kmv { k })) + .collect(); + assert_eq!(kmv_contained, [false, true, true, true]); + let ddsketch = SketchParameterRange::DDSketchAlpha { + at_least: Some(0.01), + at_most: Some(0.05), + }; + assert_eq!(ddsketch.algorithm(), SketchAlgorithm::DDSketch); + let ddsketch_contained: Vec = [0.1, 0.05, 0.01, 0.005] + .into_iter() + .map(|alpha| ddsketch.contains(&SketchParams::DDSketch { alpha })) + .collect(); + assert_eq!(ddsketch_contained, [false, true, true, false]); + } +} diff --git a/docs/design_docs/architecture/input-output-workflow.md b/docs/design_docs/architecture/input-output-workflow.md index 9cd8b9ee1..29416fe3c 100644 --- a/docs/design_docs/architecture/input-output-workflow.md +++ b/docs/design_docs/architecture/input-output-workflow.md @@ -264,7 +264,7 @@ latter cannot be fabricated by one. | Accuracy evidence | `PlanningModels` (`AccuracyEvidence`; none by default) | Measured guarantees per summary configuration, read before the theoretical guarantee. Missing measurements leave the theoretical guarantee. | | Cost model | `CostInputs.cost_model` (cost model 1 by default) | Turns each valid candidate's resource usage into a choice. The illustrative unit costs are not a measured deployment cost. | | Measured cost evidence | `CostInputs.measured_operation_costs` | Measured CPU time per unit of each operator kind, at ingestion or query time, replaces the formulas for the nodes it prices (a sketch interpolated between measured sizes); the other nodes' formulas are scaled by one calibration factor fitted from the measured ones. | -| Runtime capabilities | `DeploymentCapabilities` (`supported_summaries`, `raw_data_retained`, `query_time_results_retained`) | Prevents choosing a summary, raw-data scan or kept state the intended executor cannot provide. | +| Runtime capabilities | `DeploymentCapabilities` (`supported_summaries`, `raw_data_retained`, `query_time_results_retained`, `counter_semantics`, `state_not_mergeable_across_windows`, `excluded_candidates`) | Prevents choosing a summary, raw-data scan, kept state, counter function or state merge the intended executor cannot provide, or a candidate the caller excludes. | For example, the query `quantile_over_time(0.9, data[5m]) / quantile_over_time(0.5, data[5m])` does not tell Planner whether the windows diff --git a/docs/design_docs/concepts/glossary.md b/docs/design_docs/concepts/glossary.md index 784667f82..4079c5cbc 100644 --- a/docs/design_docs/concepts/glossary.md +++ b/docs/design_docs/concepts/glossary.md @@ -32,6 +32,10 @@ The memo groups (the distinct logical sub-expressions of the workload), each que Maintained state, exact or approximate, that can answer some query intent more efficiently than raw data. A sketch is one kind of approximate summary. +## Summary family + +A summary state's kind without its parameters: a sketch algorithm (KLL) or an exact accumulator kind (`Sum`). Code: `SummaryFamily` (`asap_types::summary_type`), which deployment exclusions match on. Not `StateFamily` (`asap_cost`), which keeps the sketch's parameters (KLL with k = 200) to pick a node's measured cost entry. + ## Physical plan A concrete execution and deployment choice: runtime topology of data lifecycle stages, placement of computation, transmission, storage. Physical plans are owned by downstream systems. diff --git a/docs/design_docs/proposals/planner-layering.md b/docs/design_docs/proposals/planner-layering.md index a112954eb..d1603bb35 100644 --- a/docs/design_docs/proposals/planner-layering.md +++ b/docs/design_docs/proposals/planner-layering.md @@ -508,7 +508,7 @@ candidates is in `crates/stage3-plan-selection/src/` (`lib.rs`, `selectable.rs`, | Step | Entry point | Path | |---|---|---| | Stage 0 | `memo_of_queries` → `Memo` (without candidates), `MemoGroup`, `MemoGroupId` | `stage0-memo/src/lib.rs` (the types: `asap_types::stages`); hash-consing is `Memo::find_or_add_group` in `types/src/stages/logical/memo/mod.rs`, its expression equality in `memo/hash_consing/mod.rs` | -| Pass 1 | `pass1_memo` → `Memo`, the one entry: inside it, the computation targets (walking the memo groups, less the summaries the deployment does not support; `ComputationTarget` is Pass 1's private working type), then each target's ways to compute added as candidates of the groups, a summary with one build per configuration of its `parameter_list` | `stage1-pass1-per-computation-candidates/src/lib.rs`; `computation_targets.rs`; `candidates/` (`mod.rs`, `pending.rs`, `measure_output.rs`); `summary_realization.rs` builds the summary inputs (the sketch algorithms that serve an intent, each row's update) | +| Pass 1 | `pass1_memo` → `Memo`, the one entry: inside it, the computation targets (walking the memo groups, less the summaries the deployment's exclusions rule out outright: an unsupported sketch algorithm, or a readout the measure needs that the deployment does not answer; `ComputationTarget` is Pass 1's private working type), then each target's ways to compute added as candidates of the groups, a summary with one build per configuration of its `parameter_list` | `stage1-pass1-per-computation-candidates/src/lib.rs`; `computation_targets.rs`; `candidates/` (`mod.rs`, `pending.rs`, `measure_output.rs`); `summary_realization.rs` builds the summary inputs (the sketch algorithms that serve an intent, each row's update) | | Memo types | `Memo`, `MemoGroup`, `CandidateForMemoGroup`, `OriginOfCandidateForMemoGroup`, `LogicalASAPMemoCandidates`, `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. rollup from the finest common group; 2. top-k reuse; 3. reach, caps and readout requirements; 4. dead-candidate elimination; 5. chain groups; 6. the logical edges; then each group's evaluation grid and the groups each query may read only exactly | `stage1-pass2-reuse-candidates/src/` (`lib.rs`, `rules/{candidates.rs,rollup/,topk.rs,chains.rs}`, `readout_requirements.rs`, `dead_candidates.rs`, `edges.rs`, `evaluation_grids.rs`; the readout levels: `asap_accuracy::readout_levels`; the groups each query may read only exactly: `asap_accuracy::ErrorMetricsOfMemo::exact_only_groups_of_query`; `LogicalASAPMemoCandidates` itself: `asap_types::stages`) | | Production memo build and search | The facade's `run_planning` builds Stage 0's memo (`memo_of_queries`) 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 executions and edges it may select (`selectable.rs`), their costs (`cost.rs`) and the selection MILP over execution contexts (`milp/`: `model/`, `retention.rs` for $h_v$ and (R), `exact_only.rs` for each query's exact-only reads $a_{q,e}$ and (X), `dominance.rs` for executions their `OneEvaluation` twin dominates, `equivalent_contexts.rs` for the copies of an equivalent evaluation context, which share the original's variables, `graph.rs`, `upper_bound.rs`) | `crates/planner/src/run.rs`; `crates/stage3-plan-selection/src/lib.rs` | @@ -548,9 +548,9 @@ The sections below describe each stage. | Stage | Prunes (`PruneReason`) | Recorded in | `candidate` | |---|---|---|---| | 0. Frontends | nothing: a query that cannot be lowered fails planning with an error | — | — | -| 1, Pass 1 | nothing is recorded: a way the measure or the deployment cannot compute is not offered (the exact accumulator of an `avg` over a nullable input, a count sketch over relational rows, a summary the deployment does not support, a quantile summary outside [0, 1], a top-k heap over one row per item), nor a way Pass 1 cannot build | — | — | +| 1, Pass 1 | nothing is recorded: a way the measure or the deployment cannot compute is not offered (the exact accumulator of an `avg` over a nullable input, a count sketch over relational rows, a summary of a sketch algorithm the deployment excludes outright, a quantile summary outside [0, 1], a top-k heap over one row per item), nor a way Pass 1 cannot build | — | — | | 1, Pass 2 | nothing: it only adds candidates | — | — | -| 2 | what cannot be built or materialized: `NoIngestionPipeline`, `RawDataNotRetained` (a scan of raw data the deployment does not keep, at query time or materialized across evaluations), `QueryTimeResultsNotRetained`, `CountMinWeightsNotProvenNonNegative`, `InputHasNoBuildableProducer`, `ReachesNoQueryOutput`; the planner does not check executor support | `PhysicalASAPMemoCandidates::pruned_candidates` | the `PhysicalCandidate` it would have been | +| 2 | what cannot be built or materialized: `NoIngestionPipeline`, `CountMinWeightsNotProvenNonNegative`, `ExcludedByDeployment` (what the deployment's capabilities exclude: an unsupported summary or readout, a scan of raw data it does not keep, a query-time result kept across evaluations, counter semantics or state merges it lacks, a candidate the caller excludes), `InputHasNoBuildableProducer`, `ReachesNoQueryOutput` | `PhysicalASAPMemoCandidates::pruned_candidates` | the `PhysicalCandidate` it would have been | | 3 | valid candidates that lose, and the checks only a whole plan can make (accuracy; latency and cluster capacity later) | its own `RejectionCause` | — | Stage 2 records a pruned candidate as the `PhysicalCandidate` it would @@ -576,9 +576,9 @@ the memo path's entry points. | Stage | Whole-workload candidates: input → output | Memo: input → output | Entry point (memo path) | |---|---|---|---| | 0. Frontends | Query text, language → one logical root per query, carrying its accuracy target | Same: a `QueryRoot` per query | `lower_promql_query_workload`, `lower_sql_dialect` (`asap-frontend-*`); `plan_installable` (`asap_planner`) runs the frontends and Stages 1–3 on the user input | -| 1, Pass 1 | Logical roots; the deployment's supported summaries → the Pass 1 inventory, every computation's candidates (no longer in the code) | Logical roots → Stage 0's `Memo` (hash-consed `MemoGroup`s); with the Pass 1 inventory, less the summaries the deployment does not support → the same `Memo` with each group's `CandidateForMemoGroup`s (a summary with one build per configuration of its `parameter_list`) | `memo_of_queries`, `pass1_memo` | +| 1, Pass 1 | Logical roots; the deployment's exclusions → the Pass 1 inventory, every computation's candidates (no longer in the code) | Logical roots → Stage 0's `Memo` (hash-consed `MemoGroup`s); with the Pass 1 inventory, less the summaries the deployment's exclusions rule out outright (an unsupported sketch algorithm, or the readout the measure needs) → the same `Memo` with each group's `CandidateForMemoGroup`s (a summary with one build per configuration of its `parameter_list`) | `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 → `LogicalASAPMemoCandidates`: the same memo with the rules' groups and candidates added (rollup, top-k reuse, chain groups), each readout's required accuracy, the logical edges between the surviving candidates, the pruned candidates and, per query, the groups it may read only exactly | `generate_logical_asap_memo_candidates` (`asap_stage1_pass2_reuse_candidates`) | -| 2 | One whole-workload logical candidate; entries (recurrence, predictability), `DataWorkload`, query-time retention → its physical candidates, one per physical properties assignment | `LogicalASAPMemoCandidates` (with each group's evaluation grid); `DataWorkload` (arrival), `DeploymentCapabilities` (raw-data and query-time retention) → `PhysicalASAPMemoCandidates`: every logical candidate Pass 2 kept with each offered timing and lifetime (one physical candidate each, no copies), every logical edge expanded into physical edges with $\alpha^{\log}$ and $\alpha^{\mathrm{phys}}$, and the pruned alternatives (`PrunedCandidate`) | `generate_physical_asap_memo_candidates` (`asap_stage2_physical_optimization`) | +| 2 | One whole-workload logical candidate; entries (recurrence, predictability), `DataWorkload`, the deployment's exclusions → its physical candidates, one per physical properties assignment | `LogicalASAPMemoCandidates` (with each group's evaluation grid); `DataWorkload` (arrival), the deployment's exclusions (`DeploymentCapabilities::exclusions`) → `PhysicalASAPMemoCandidates`: every logical candidate Pass 2 kept with each offered timing and lifetime (one physical candidate each, no copies), every logical edge expanded into physical edges with $\alpha^{\log}$ and $\alpha^{\mathrm{phys}}$, and the pruned alternatives (`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` | @@ -1270,13 +1270,13 @@ On the memo, Stage 2 prunes per physical alternative (a logical candidate with one timing and lifetime) and records each pruned alternative in `PhysicalASAPMemoCandidates::pruned_candidates` ([Pruning by stage](#pruning-by-stage)). It does not generate a configuration the deployment cannot run: an ingestion-time alternative -without an ingestion pipeline (`NoIngestionPipeline`), a scan of raw data -the deployment does not retain, at query time or materialized across -evaluations (`RawDataNotRetained`), a -query-time result materialized across evaluations the deployment does not -retain (`QueryTimeResultsNotRetained`), and a Count-Min build whose weights -are not proven non-negative (`CountMinWeightsNotProvenNonNegative`). It does -not check executor support. It +without an ingestion pipeline (`NoIngestionPipeline`), a Count-Min build +whose weights are not proven non-negative +(`CountMinWeightsNotProvenNonNegative`), and an alternative one of the +deployment's exclusions matches (`ExcludedByDeployment`, naming the +capability it comes from: e.g. a scan of raw data the deployment does not +retain, at query time or materialized across evaluations, is +`ExcludedByDeployment(RawDataNotRetained)`). It then removes the candidates no buildable input or query output can use (`InputHasNoBuildableProducer`, `ReachesNoQueryOutput`), repeating until nothing more is removed. Stage 2 makes no execution-scope diff --git a/docs/develop_docs/asap-aware-mapping-architecture.md b/docs/develop_docs/asap-aware-mapping-architecture.md index 3f9b6aac8..4565186bb 100644 --- a/docs/develop_docs/asap-aware-mapping-architecture.md +++ b/docs/develop_docs/asap-aware-mapping-architecture.md @@ -82,7 +82,7 @@ same pipeline behind the `OptimizationPass` trait. | The analytical per-operator resource model Stage 3 measures with | `asap-cost`, `node/analytical.rs` and `node/operator_statistics.rs` | | The accuracy rules: per-family guarantees, each operator's error contract, the metric rule, each readout's required accuracy, α^log of a logical edge | `asap-accuracy` (`AccuracyEvidence`, `theoretical_guarantee`, `guarantee/`, `evidence.rs`, `error_contract/`, `metric_rule/`, `readout_caps/`, `logical_edge/`) | | The statistic a summary is read for an aggregation intent (`SketchStatistic::for_intent`) | `asap-types`, `summary_type/statistic.rs` | -| 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`; Stage 3 reads none of it | +| What the executor supports (`DeploymentCapabilities`) | `asap-types`, `deployment_capabilities/`; Stage 2 reads it as the one list of exclusions it expands into (`DeploymentCapabilities::exclusions`); Pass 1 reads the same list only to skip a summary whose sketch algorithm one exclusion rules out outright (a `summary_family`-only exclusion); 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 @@ -128,7 +128,7 @@ No stage caps the candidates it plans, and neither does `asap_planner`. Pass 1. - `crates/integration-tests/tests/planner_layering_example{1,2,3,4}.rs` pin the design document's examples through every stage; - `reuse_rules.rs`, `deployment_capabilities.rs`, `physical_properties_e2e.rs` + `reuse_rules.rs`, `deployment_exclusions.rs`, `physical_properties_e2e.rs` and `pass1_candidates.rs` cover single rules end to end. - `crates/devtools/tests/asap_planner.rs` checks the stage document and the committed viewer examples; `asap_planner_acceptance.rs` checks diff --git a/docs/develop_docs/asap-aware-mapping-contracts.md b/docs/develop_docs/asap-aware-mapping-contracts.md index 3031b3595..7c5ea1b00 100644 --- a/docs/develop_docs/asap-aware-mapping-contracts.md +++ b/docs/develop_docs/asap-aware-mapping-contracts.md @@ -95,15 +95,17 @@ asap-stage1-pass2-reuse-candidates -p asap-stage2-physical-optimization -p asap- `PhysicalASAPMemoCandidates::pruned_candidates` as `PrunedCandidate` with a `PruneReason`: an ingestion-time alternative without an ingestion pipeline - (`NoIngestionPipeline`); a scan of raw data the deployment does not - retain, at query time or materialized across evaluations - (`RawDataNotRetained`); a query-time result materialized across - evaluations the deployment does not retain - (`QueryTimeResultsNotRetained`); a Count-Min build whose weights are not - proven non-negative (`CountMinWeightsNotProvenNonNegative`); then an - alternative no buildable input or query output can use - (`InputHasNoBuildableProducer`, `ReachesNoQueryOutput`). The planner does - not check executor support. Stage 2 makes no execution-scope copies. + (`NoIngestionPipeline`); a Count-Min build whose weights are not + proven non-negative (`CountMinWeightsNotProvenNonNegative`); an + alternative one of the deployment's exclusions matches + (`ExcludedByDeployment(source)`, from + `DeploymentCapabilities::exclusions`: an unsupported summary type or + readout, a scan of raw data the deployment does not retain, a query-time + result kept across evaluations it does not retain, a counter semantics + or a state merge its executor lacks, or a candidate the caller excludes); + then an alternative no buildable input or query output can use + (`InputHasNoBuildableProducer`, `ReachesNoQueryOutput`). Stage 2 makes no + execution-scope copies. ## 5. Stage 3 diff --git a/docs/develop_docs/extend-asap-aware-mapping.md b/docs/develop_docs/extend-asap-aware-mapping.md index 6944df2ff..bb22d06fd 100644 --- a/docs/develop_docs/extend-asap-aware-mapping.md +++ b/docs/develop_docs/extend-asap-aware-mapping.md @@ -104,9 +104,16 @@ tests in `planner_layering_example4.rs`. as bad input). - A new pricing input goes in `CostInputs` (validated in its `validate`); a new statement about the executor goes in - `DeploymentCapabilities`. Both reach the stages through `PlanningModels`; - a stage function takes only the field it reads (Stage 2 takes - `query_time_results_retained: bool`, not the whole struct). + `DeploymentCapabilities`. Both reach the stages through `PlanningModels`. + A new deployment capability is three pieces: its field in + `DeploymentCapabilities` (with a default that changes no plan), its + expansion into `CandidateExclusion`s in + `DeploymentCapabilities::exclusions`, and the `ExclusionSource` variant + those exclusions carry. The facade expands the exclusions once and hands + the list to Pass 1 and Stage 2; no stage reads the struct itself. When no + `CandidateExclusion` field can say what the capability rules out, add the + field to `CandidateExclusion` (with its `matches` test and the operators + it applies to in `invalid_reason`). - Expose it in `asap_planner` and in the [Plan Viewer guide](../user_guide_docs/plan-viewer.md). diff --git a/docs/develop_docs/library-api.md b/docs/develop_docs/library-api.md index 281cf84c2..39f98ece6 100644 --- a/docs/develop_docs/library-api.md +++ b/docs/develop_docs/library-api.md @@ -196,7 +196,7 @@ asap_stage3_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_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) | +| `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), `raw_data_retained` (default `true`; when `false`, stored data is refused with `asap_planner::SelectionError::InvalidDeploymentCapabilities`), `query_time_results_retained` (default `false`; when `true`, Stage 2 offers query-time `AcrossEvaluations` for tumbling-window chains), `counter_semantics` (default: resets handled and extrapolated), `state_not_mergeable_across_windows` (default none) and `excluded_candidates` (`CandidateExclusion`s, default none). Every capability left out expands into exclusions (`DeploymentCapabilities::exclusions`, expanded once by the facade): Pass 1 skips the summaries they rule out outright, and Stage 2 applies them as one filter, pruning each matched candidate with `PruneReason::ExcludedByDeployment(source)`; with no plan left, Stage 3's rejection is `RejectionCause::ExcludedByDeployment` | | `CostInputs` (`asap_cost`) | `cost_model`, `resource_speed` (`ms_per_cpu_op`, `ms_per_scanned_byte`, `raw_batch_width_ms`: the time one batch of raw rows covers in the data store, default 10,000, an assumed value), `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 | @@ -378,6 +378,6 @@ cargo doc -p asap-stage0-memo -p asap-stage1-pass1-per-computation-candidates \ - [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/stage3-plan-selection/src/lib.rs) -- [Deployment capabilities](../../crates/types/src/deployment_capabilities.rs) +- [Deployment capabilities](../../crates/types/src/deployment_capabilities/mod.rs) - [Workload types](../../crates/types/src/workload/mod.rs) - [Planner-runtime contract](../design_docs/architecture/planner-runtime-contract.md) diff --git a/docs/user_guide_docs/asap-planner.md b/docs/user_guide_docs/asap-planner.md index d84ca3118..3ccd5bbb9 100644 --- a/docs/user_guide_docs/asap-planner.md +++ b/docs/user_guide_docs/asap-planner.md @@ -48,7 +48,7 @@ asap_planner (--workload )... --run-until stage0|stage1_pass1|stage1_pass2 | `--out ` | Write to this file instead of standard output. | | `--sql-catalog-table ` | One SQL table a SQL workload reads, as `{"name", "columns": [{"name", "type", "nullable"}], "time_index"}`. Repeat it per table. | | `--cost-inputs ` | The cost model and its costs (`CostInputs` JSON). The files in `tools/dag-viewer/cost-inputs/` are ready to use. Without it, the built-in usage-over-time model is used. Stage 3 costs only usage-over-time models (`aws-fargate-us-east-1.json` is one); a provisioned- or cluster-capacity model ends Stage 3 with an `UnsupportedCostModel` error. | -| `--deployment-capabilities ` | What the deployment can do, e.g. `{"raw_data_retained": true, "query_time_results_retained": false}`. Set it to match your deployment. | +| `--deployment-capabilities ` | What the deployment can do, e.g. `{"raw_data_retained": true, "query_time_results_retained": false}`. Set it to match your deployment; see [Deployment capabilities](#deployment-capabilities). | | `--ignore-accuracy-guarantees` | Accept candidates without an accuracy guarantee. By default each query's accuracy requirement is enforced. | Any other option, or a missing required one, is a usage error (exit @@ -57,6 +57,50 @@ run in which a stage failed (for example, Pass 1 rejected a query, or no plan meets the requirements): the output is still written, with the error under the stage that failed. +## Deployment capabilities + +The `--deployment-capabilities` file is a `DeploymentCapabilities` JSON +object; an omitted field keeps its default. Besides +`supported_summaries`, `raw_data_retained` and +`query_time_results_retained`, three fields say what the executor cannot +do or what the caller rules out: + +```json +{ + "counter_semantics": {"reset_handling": true, "extrapolation": false}, + "state_not_mergeable_across_windows": [{"exact": "Rate"}, {"sketch": "Kll"}], + "excluded_candidates": [ + {"timing": "query_time", "operator": "Scan"}, + {"summary_family": {"sketch": "Kll"}, "sketch_parameter_range": {"kll_k": {"at_most": 1403}}}, + {"timing": "query_time", "aggregate_measure": "rate"} + ] +} +``` + +- `counter_semantics` (default: both `true`): without `extrapolation`, no + `rate`, `increase` or `delta` and no `Rate` or `Increase` state is + planned; without `reset_handling`, no `rate`, `increase`, `irate` or + `resets` and no `Rate`, `Increase` or `IRate` state. +- `state_not_mergeable_across_windows` (default none): for each family + listed, no tumbling-window chain and no state kept across evaluations; + its state is built and finalized within one evaluation. +- `excluded_candidates` (default none): each entry is a + `CandidateExclusion` that rules out every physical candidate matching all + the fields it sets: `timing`, `kept_across_evaluations`, `operator`, + `per_entity_reduction`, `aggregate_measure` (an `Aggregate` measure's + JSON `kind`, e.g. `"rate"` or `"i_rate"`), `summary_family`, + `sketch_parameter_range` and `readout` (`{"summary_type": "Kll", + "statistic": "Quantile"}`). `aggregate_measure` matches the `Aggregate` + only: to rule out a `Rate` state as well, add `{"summary_family": + {"exact": "Rate"}}`. An entry that sets no field, or whose fields match + no operator in common, is refused. + +Stage 2 prints each candidate a capability rules out as +`ExcludedByDeployment()`, e.g. +`ExcludedByDeployment(counter_not_extrapolated)`, or +`ExcludedByDeployment(excluded_candidates[0])` for the first entry of +`excluded_candidates`. When no plan is left, Stage 3 names those sources. + ## Stages | `--run-until` | Prints, after the stages before it | diff --git a/tools/dag-viewer/memo.test.mjs b/tools/dag-viewer/memo.test.mjs index 5e3d2efad..bae31b04a 100644 --- a/tools/dag-viewer/memo.test.mjs +++ b/tools/dag-viewer/memo.test.mjs @@ -298,7 +298,7 @@ test('the pruned candidates of a group: Pass 2 with its root causes, Stage 2 and const pruned = call('memoPrunedLines', doc, 4); assert.equal(pruned.pass2.length, 4); assert.match(pruned.pass2[0], /^#0: the producer's guarantee exceeds Rank ≤ 0\.01 \(δ 0\.00001\)$/); - assert.ok(pruned.stage2.includes('#4 (query_time, AcrossEvaluations(Memory)): query time results not retained'), pruned.stage2.join('\n')); + assert.ok(pruned.stage2.includes('#4 (query_time, AcrossEvaluations(Memory)): excluded by the deployment: query time results not retained'), pruned.stage2.join('\n')); assert.ok(pruned.stage2.includes('#4 (query_time, None): input has no buildable producer'), pruned.stage2.join('\n')); assert.deepEqual(pruned.stage3, []); // A cause traced through eliminated consumers names them; a Stage 3 diff --git a/tools/dag-viewer/stages.js b/tools/dag-viewer/stages.js index 8e3ee3810..3d332059b 100644 --- a/tools/dag-viewer/stages.js +++ b/tools/dag-viewer/stages.js @@ -174,10 +174,19 @@ const isPlainObject = (value) => !!value && typeof value === 'object' && !Array. // A pruning reason of Stage 2 or Stage 3 (a serialized `PruneReason`): a // snake_case string, e.g. "usage_not_costable" as "usage not costable", or // `{"dominated_by": id}` as "dominated by C", the physical candidate -// that dominates it. +// that dominates it, or `{"excluded_by_deployment": source}` as "excluded by +// the deployment: raw data not retained" (the caller's own exclusion `i` as +// "excluded_candidates[i]"). function prunedReasonText(reason) { if (typeof reason === 'string') return reason.replace(/_/g, ' '); if (isPlainObject(reason) && 'dominated_by' in reason) return `dominated by C${reason.dominated_by}`; + if (isPlainObject(reason) && 'excluded_by_deployment' in reason) { + const source = reason.excluded_by_deployment; + const named = typeof source === 'string' ? source.replace(/_/g, ' ') + : isPlainObject(source) && isPlainObject(source.excluded_candidate) ? `excluded_candidates[${source.excluded_candidate.index}]` + : compactWire(source); + return `excluded by the deployment: ${named}`; + } return compactWire(reason); } @@ -732,10 +741,31 @@ function settingsRows(doc) { ['summaries', Array.isArray(c.supported_summaries) ? c.supported_summaries.map((x) => `${x.summary_type} (${(x.readouts || []).join(', ')})`).join(', ') : 'every summary the planner builds'], ] : [['deployment', 'not recorded']]; + const limits = capabilityLimitsText(c); + if (limits) rows.push(['left out', limits]); rows.push(['accuracy guarantees', { ignored: 'ignored: every output accepted, candidates compared on cost alone', enforced: 'enforced' }[doc.accuracy_guarantees] || 'not recorded']); rows.push(['cost model', cost && cost.source ? cost.source : 'not recorded (no plan was costed)']); return rows; } + +// The capabilities a deployment leaves out and the caller's exclusions, as +// one line, e.g. "counter extrapolation not supported · not mergeable across +// windows: exact Rate · excluded candidates: 2"; empty for the defaults. +function capabilityLimitsText(capabilities) { + if (!capabilities || typeof capabilities !== 'object') return ''; + const parts = []; + const counters = capabilities.counter_semantics || {}; + if (counters.reset_handling === false) parts.push('counter resets not handled'); + if (counters.extrapolation === false) parts.push('counter extrapolation not supported'); + const unmergeable = capabilities.state_not_mergeable_across_windows || []; + if (unmergeable.length) { + const family = (f) => Object.entries(f || {}).map(([kind, name]) => `${kind} ${name}`).join(''); + parts.push(`not mergeable across windows: ${unmergeable.map(family).join(', ')}`); + } + const excluded = capabilities.excluded_candidates || []; + if (excluded.length) parts.push(`excluded candidates: ${excluded.length}`); + return parts.join(' · '); +} // The queries of a `PlanningWorkload` JSON, batch then repeating (the // planner's entry order): each query's text, how often it runs and its // accuracy target as text. diff --git a/tools/dag-viewer/stages.test.mjs b/tools/dag-viewer/stages.test.mjs index 34426bc15..a8787a83d 100644 --- a/tools/dag-viewer/stages.test.mjs +++ b/tools/dag-viewer/stages.test.mjs @@ -114,8 +114,12 @@ test('queries show a fixed interval and its phase', () => { }); test('Stage 2 and Stage 3 pruning reasons read as words; dominated_by names its physical candidate', () => { - assert.equal(call('prunedReasonText', 'query_time_results_not_retained'), 'query time results not retained'); + assert.equal(call('prunedReasonText', 'no_ingestion_pipeline'), 'no ingestion pipeline'); assert.equal(call('prunedReasonText', { dominated_by: 7 }), 'dominated by C7'); + assert.equal(call('prunedReasonText', { excluded_by_deployment: 'raw_data_not_retained' }), + 'excluded by the deployment: raw data not retained'); + assert.equal(call('prunedReasonText', { excluded_by_deployment: { excluded_candidate: { index: 2 } } }), + 'excluded by the deployment: excluded_candidates[2]'); }); test('a materialized view row names its plan node, kind, refresh, inputs, cost and the queries reading it', () => { @@ -188,3 +192,28 @@ test('a node shared by several queries says so; a query keeps its own nodes and assert.ok(root.has(chain.data.id) && !root.has(`n${plan.roots[1]}`)); assert.equal(cytoscape(elements).nodes().length, nodesOf(elements).length); }); + +test('the deployment settings name each capability left out and the caller exclusions', () => { + const text = call('capabilityLimitsText', { + raw_data_retained: true, + query_time_results_retained: false, + counter_semantics: { reset_handling: true, extrapolation: false }, + state_not_mergeable_across_windows: [{ exact: 'Rate' }], + excluded_candidates: [ + { timing: 'query_time', operator: 'Scan' }, + { operator: 'Aggregate', per_entity_reduction: true }, + ], + }); + assert.match(text, /counter extrapolation not supported/); + assert.doesNotMatch(text, /counter resets not handled/); + assert.match(text, /not mergeable across windows: exact Rate/); + assert.match(text, /excluded candidates: 2/); + // Each supported summary by its wire field `summary_type`. + const kllOnly = call('settingsRows', { + deployment_capabilities: { supported_summaries: [{ summary_type: 'Kll', readouts: ['Quantile'] }] }, + }); + assert.deepEqual(kllOnly.find(([name]) => name === 'summaries'), ['summaries', 'Kll (Quantile)']); + // The defaults leave nothing out, so the line names none of them. + const defaults = call('capabilityLimitsText', { raw_data_retained: true, query_time_results_retained: false }); + assert.equal(defaults, ''); +}); diff --git a/tools/dag-viewer/test-fixtures/p90-kll.json b/tools/dag-viewer/test-fixtures/p90-kll.json index a1700358b..7b63a0aef 100644 --- a/tools/dag-viewer/test-fixtures/p90-kll.json +++ b/tools/dag-viewer/test-fixtures/p90-kll.json @@ -1,8 +1,14 @@ { "accuracy_guarantees": "enforced", "deployment_capabilities": { + "counter_semantics": { + "extrapolation": true, + "reset_handling": true + }, + "excluded_candidates": [], "query_time_results_retained": false, "raw_data_retained": false, + "state_not_mergeable_across_windows": [], "supported_summaries": [ { "readouts": [ @@ -3407,7 +3413,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 0, @@ -3438,7 +3446,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 1, @@ -3449,7 +3459,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 1, @@ -3478,7 +3490,9 @@ "lifetime": "None", "timing": "query_time" }, - "reason": "raw_data_not_retained" + "reason": { + "excluded_by_deployment": "raw_data_not_retained" + } }, { "group": 2, @@ -3489,7 +3503,9 @@ }, "timing": "query_time" }, - "reason": "raw_data_not_retained" + "reason": { + "excluded_by_deployment": "raw_data_not_retained" + } }, { "group": 2, @@ -3500,7 +3516,9 @@ }, "timing": "query_time" }, - "reason": "raw_data_not_retained" + "reason": { + "excluded_by_deployment": "raw_data_not_retained" + } }, { "group": 2, @@ -3511,7 +3529,9 @@ }, "timing": "ingestion_time" }, - "reason": "raw_data_not_retained" + "reason": { + "excluded_by_deployment": "raw_data_not_retained" + } }, { "group": 3, @@ -3522,7 +3542,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 4, @@ -3533,7 +3555,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 4, @@ -3564,7 +3588,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 4, @@ -3595,7 +3621,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 4, @@ -3626,7 +3654,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 4, @@ -3637,7 +3667,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 4, @@ -3648,7 +3680,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 5, @@ -3659,7 +3693,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 5, @@ -3670,7 +3706,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 5, @@ -3681,7 +3719,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 6, @@ -3692,7 +3732,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 6, @@ -3723,7 +3765,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 6, @@ -3754,7 +3798,9 @@ }, "timing": "query_time" }, - "reason": "query_time_results_not_retained" + "reason": { + "excluded_by_deployment": "query_time_results_not_retained" + } }, { "group": 6, diff --git a/tools/dag-viewer/test_viewer.py b/tools/dag-viewer/test_viewer.py index 25214f3ee..f60d85c20 100644 --- a/tools/dag-viewer/test_viewer.py +++ b/tools/dag-viewer/test_viewer.py @@ -965,7 +965,7 @@ def test_tapping_a_group_lists_its_candidates_and_pruned_candidates(self): self.assertIn("#0 SummaryAgg Kll · θ Kll(k=26) · pruned by Pass 2", details) self.assertIn("pruned by Pass 24", details) self.assertIn("#0: the producer", details) - self.assertIn("#4 (query_time, AcrossEvaluations(Memory)): query time results not retained", details) + self.assertIn("#4 (query_time, AcrossEvaluations(Memory)): excluded by the deployment: query time results not retained", details) self.assertIn("#8 (query_time, None): dominated by C5", details) def test_highlighting_a_query_dims_the_memo_groups_it_does_not_reach(self):