diff --git a/Cargo.lock b/Cargo.lock index 6b77c8a73..afe947361 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -332,8 +332,6 @@ dependencies = [ "asap-executor", "asap-frontend-promql", "asap-planner", - "asap-stage0-memo", - "asap-stage1-pass1-per-computation-candidates", "asap-types", "asap_sketchlib", "chrono", diff --git a/crates/accuracy/Cargo.toml b/crates/accuracy/Cargo.toml index 03965917f..940cd9c02 100644 --- a/crates/accuracy/Cargo.toml +++ b/crates/accuracy/Cargo.toml @@ -13,10 +13,5 @@ asap_sketchlib = { workspace = true } asap-types = { path = "../types" } serde_json = "1" -[features] -# Exposes `test_support`: estimator, sizing, composition and propagation -# helpers other crates' tests call. -test-support = [] - [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } diff --git a/crates/accuracy/src/guarantee/cardinality.rs b/crates/accuracy/src/guarantee/cardinality.rs index 5e03bd0b6..620d93742 100644 --- a/crates/accuracy/src/guarantee/cardinality.rs +++ b/crates/accuracy/src/guarantee/cardinality.rs @@ -25,16 +25,14 @@ //! //! Neither bound depends on `N`, so no distinct bound is needed: the //! failure probability ([`kmv_failure_probability`]) is their sum, per -//! output row (each group's estimate). Sizing ([`kmv_k`]) takes the -//! smallest `k` with that sum at most `δ`, about +//! output row (each group's estimate). Sizing (test-only +//! `sizing_oracle::kmv_k`) takes the smallest `k` with that sum at most +//! `δ`, about //! `1 + (1+ε)(2+ε)·ln(2/δ)/ε²` (below `3·ln(2/δ)/ε² + 1` for `ε ≤ 1`). use super::*; /// The smallest `k` `asap_sketchlib`'s KMV estimate `(k-1)/U` is defined for. -const KMV_MIN_K: u32 = 2; -/// The largest `k` sizing returns. -#[cfg(test)] -const KMV_MAX_K: u32 = 1 << 26; +pub(super) const KMV_MIN_K: u32 = 2; pub(super) fn guarantee( algorithm: &SketchAlgorithm, @@ -79,38 +77,6 @@ pub(crate) fn kmv_failure_probability(k: u32, eps: f64) -> f64 { ((over + under) * (1.0 + 1e-12)).min(1.0) } -/// The smallest `k` whose KMV failure probability at relative error `eps` -/// is at most `delta` ([`kmv_failure_probability`]), up to `2^26`; a -/// degenerate `eps` or `delta` saturates to `2^26`. -#[cfg(test)] -pub(crate) fn kmv_k(eps: f64, delta: f64) -> u32 { - if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) { - return KMV_MAX_K; - } - // The overestimate term alone at most `δ` bounds `k` below; both terms - // at most `δ/2` bound it above. - let k_at = |ln_inverse: f64| { - saturating_ceil( - 1.0 + (1.0 + eps) * (2.0 + eps) * ln_inverse / (eps * eps), - KMV_MIN_K, - KMV_MAX_K, - ) - }; - let (mut lo, mut hi) = (k_at((1.0 / delta).ln()), k_at((2.0 / delta).ln())); - if kmv_failure_probability(hi, eps) > delta { - return KMV_MAX_K; - } - while lo < hi { - let mid = lo + (hi - lo) / 2; - if kmv_failure_probability(mid, eps) <= delta { - hi = mid; - } else { - lo = mid + 1; - } - } - hi -} - #[cfg(test)] mod tests { use super::*; diff --git a/crates/accuracy/src/guarantee/cms.rs b/crates/accuracy/src/guarantee/cms.rs index ad48f58c2..7333ea698 100644 --- a/crates/accuracy/src/guarantee/cms.rs +++ b/crates/accuracy/src/guarantee/cms.rs @@ -1,4 +1,4 @@ -//! Count-Min Sketch L1 frequency error and parameter sizing. +//! Count-Min Sketch L1 frequency error. use super::*; pub(super) fn guarantee( @@ -24,25 +24,13 @@ pub(super) fn guarantee( )) } -/// CMS: over-count ≤ ε·N with width `w = ⌈e/ε⌉` columns. -#[cfg(test)] -pub(crate) fn cms_width(eps: f64) -> u32 { - saturating_ceil(std::f64::consts::E / eps, 2, 1 << 26) -} - -/// CMS: failure probability ≤ δ with depth `d = ⌈ln(1/δ)⌉` rows. -/// δ = 0.01 → depth 5. -pub(crate) fn cms_depth(delta: f64) -> u32 { - saturating_ceil((1.0 / delta).ln(), 1, 32) -} - #[cfg(test)] mod tests { use super::*; #[test] fn local_guarantee_inverts_frequency_sizing() { - use crate::guarantee::size_params; + use crate::guarantee::sizing_oracle::size_params; let c = asap_types::ir::operator::agg_intent::default_cardinality(); let params = size_params(SketchAlgorithm::Cms, &c, 0.01, 0.001); let g = sketch_guarantee( @@ -76,19 +64,4 @@ mod tests { AccuracyMetric::ABSOLUTE_STREAM_L1 ); } - - /// A top-k heap holds `max(k, ⌈1/ε⌉)` entries over a CMS sized as for counts. - #[test] - fn topk_heap_capacity_respects_accuracy_and_output_count() { - use crate::guarantee::size_params; - let intent = AggIntent::TopK { k: 25 }; - assert_eq!( - size_params(SketchAlgorithm::CmsWithHeap, &intent, 0.01, 0.01), - SketchParams::CmsWithHeap { - width: 272, // ⌈e/0.01⌉ - depth: 5, - heap_size: 100, - } - ); - } } diff --git a/crates/accuracy/src/guarantee/count_sketch.rs b/crates/accuracy/src/guarantee/count_sketch.rs index 52d6e4b7c..9c6ec7011 100644 --- a/crates/accuracy/src/guarantee/count_sketch.rs +++ b/crates/accuracy/src/guarantee/count_sketch.rs @@ -28,7 +28,7 @@ pub(super) fn guarantee( /// probability at most `q/ε² = q w/3` (Chebyshev, `Var ≤ q F2`), with `q` /// the column collision probability ([`column_collision`]): `1/3` to /// within `w/(3 · 2^32)`. -fn row_failure_probability(width: u32) -> f64 { +pub(super) fn row_failure_probability(width: u32) -> f64 { column_collision(width) * f64::from(width.max(1)) / 3.0 } @@ -45,7 +45,7 @@ fn column_collision(cols: u32) -> f64 { /// The median of an odd `depth` of independent rows misses only when at /// least `(depth + 1)/2` rows miss: `P(Binomial(depth, p) ≥ (depth+1)/2)`. -fn count_sketch_failure_probability(width: u32, depth: u32) -> Option { +pub(super) fn count_sketch_failure_probability(width: u32, depth: u32) -> Option { if depth == 0 || depth.is_multiple_of(2) { return None; } @@ -56,47 +56,10 @@ fn count_sketch_failure_probability(width: u32, depth: u32) -> Option { )) } -/// CountSketch `L2` point-query width: ε = sqrt(3/w). -#[cfg(test)] -pub(crate) fn count_sketch_width(eps: f64) -> u32 { - saturating_ceil(3.0 / (eps * eps), 2, 1 << 26) -} - -/// The smallest positive odd depth whose binomial median failure -/// probability at `width` is at most `delta`, capped at 255. -#[cfg(test)] -pub(crate) fn count_sketch_depth(width: u32, delta: f64) -> u32 { - if !(delta.is_finite() && delta > 0.0 && delta < 1.0) { - return 255; - } - (1..=255) - .step_by(2) - .find(|&depth| { - count_sketch_failure_probability(width, depth).is_some_and(|tail| tail <= delta) - }) - .unwrap_or(255) -} - #[cfg(test)] mod tests { use super::*; - /// The executor's `CountSketch<_, RegularPath>` takes a column as the - /// low 32 hash bits modulo the width, so a row fails with probability - /// `1/3` (to within `2^-32`) at any width, not `3/8` off powers of two: - /// ε = 0.05 (width 1200) needs depth 47 at δ = 0.01, 81 at 1e-3 and - /// 117 at 1e-4, not 85, 149 and 215. - #[test] - fn depth_follows_the_libraries_modulo_column_hash() { - let width = count_sketch_width(0.05); - assert_eq!(width, 1200); - assert!((row_failure_probability(width) - 1.0 / 3.0).abs() < 1e-6); - assert_eq!( - [0.01, 1e-3, 1e-4].map(|delta| count_sketch_depth(width, delta)), - [47, 81, 117] - ); - } - /// Measured on the library's own `CountSketch<_, RegularPath>`: two /// keys share a column of a 1536-wide row about `1/1536` of the time. /// A `⌈log2 w⌉`-bit hash slice modulo `w` would give `1.125/1536`, 6 @@ -124,6 +87,7 @@ mod tests { /// most a δ share of keys missing. #[test] fn sized_sketch_meets_its_guarantee_on_a_seeded_stream() { + use crate::guarantee::sizing_oracle::{count_sketch_depth, count_sketch_width}; use asap_sketchlib::{CountSketch, DataInput, RegularPath, Vector2D}; let (eps, delta) = (0.05, 0.01); let width = count_sketch_width(eps); @@ -157,7 +121,7 @@ mod tests { #[test] fn count_sketch_uses_an_l2_guarantee() { - use crate::guarantee::size_params; + use crate::guarantee::sizing_oracle::size_params; use asap_types::ir::operator::agg_intent::default_cardinality; let intent = default_cardinality(); let count_sketch = size_params(SketchAlgorithm::CountSketch, &intent, 0.01, 0.01); @@ -176,33 +140,4 @@ mod tests { ); assert!(meets(&guarantee, 0.01, Some(0.01))); } - - /// The depth is the smallest odd one whose binomial tail meets δ. Each - /// is at most Hoeffding's `ln(1/δ) / (2 (1/2 − p)²)` at the row's - /// failure probability `p ≈ 1/3`: `18 ln(1/δ)` at any width. - #[test] - fn count_sketch_depth_is_the_smallest_meeting_the_binomial_tail() { - for width in [1024, 3000, 30_000] { - let hoeffding = 18.0 * (1.0 + 1e-4); - for delta in [0.1, 0.01, 0.001] { - let depth = count_sketch_depth(width, delta); - assert!(depth % 2 == 1); - assert!(count_sketch_failure_probability(width, depth).unwrap() <= delta); - if depth > 1 { - assert!(count_sketch_failure_probability(width, depth - 2).unwrap() > delta); - } - assert!( - f64::from(depth) <= hoeffding * (1.0 / delta).ln(), - "{width} {delta}" - ); - } - } - // Any width fails a row with probability 1/3 (to within 2^-32 w/3): - // P(Bin(3, 1/3) ≥ 2) = 7/27. - for width in [1024, 1000] { - let tail = count_sketch_failure_probability(width, 3).unwrap(); - assert!((tail - 7.0 / 27.0).abs() < 1e-6, "{width}"); - } - assert_eq!(count_sketch_failure_probability(1000, 4), None); - } } diff --git a/crates/accuracy/src/guarantee/ddsketch.rs b/crates/accuracy/src/guarantee/ddsketch.rs index 5f1a7310c..9184de771 100644 --- a/crates/accuracy/src/guarantee/ddsketch.rs +++ b/crates/accuracy/src/guarantee/ddsketch.rs @@ -19,8 +19,3 @@ pub(super) fn guarantee( "ddsketch_relative_error_alpha_v1", )) } - -#[cfg(test)] -pub(super) fn size_params(epsilon: f64) -> SketchParams { - SketchParams::DDSketch { alpha: epsilon } -} diff --git a/crates/accuracy/src/guarantee/hll.rs b/crates/accuracy/src/guarantee/hll.rs index ea463ff96..fc483ec2b 100644 --- a/crates/accuracy/src/guarantee/hll.rs +++ b/crates/accuracy/src/guarantee/hll.rs @@ -77,7 +77,7 @@ pub fn parse_classic_failure_statistic(statistic: &str) -> Option<(u8, f64, &str /// (one instance per group, over the source's scan at most behind filters /// and windows): relative error at most the one its precision was sized for /// ([`classic_relative_error`]), with a failure probability -/// ([`ClassicHllConfidence`]) at that error left symbolic in the source's +/// (`ClassicHllConfidence`) at that error left symbolic in the source's /// distinct bound ([`classic_failure_statistic`]). The failure probability /// is per output row: each group's estimate fails with at most it. `None` /// for a precision outside the contract's. @@ -117,7 +117,12 @@ pub(crate) fn classic_guarantee( /// (`classic_failure_statistic`) names, given the /// source's distinct bound: `1` (no certificate) when the bound is outside /// the contract's range for this precision and relative error. -pub fn classic_failure_probability(precision: u8, relative_error: f64, max_distinct: u64) -> f64 { +#[cfg(test)] +pub(crate) fn classic_failure_probability( + precision: u8, + relative_error: f64, + max_distinct: u64, +) -> f64 { u32::try_from(max_distinct) .ok() .and_then(|n| ClassicHllConfidence::new(n, relative_error)) @@ -132,18 +137,21 @@ const CLASSIC_CONTRACT: &str = "classic_hll_linear_counting_collision_bound_v1"; /// The largest distinct bound the contract supports at any precision: /// `m/2` at precision 18. Evaluating a bound is O(bound). -const MAX_CONTRACT_DISTINCT: u32 = 1 << 17; +#[cfg(test)] +pub(super) const MAX_CONTRACT_DISTINCT: u32 = 1 << 17; /// A finite-population contract for `m * ln(m / zero_registers)` with the /// classic HLL small-range switch. Hashing is assumed independent and uniform. /// The deployment must establish the population bound; observations alone do /// not establish it. Unsupported precisions/populations return no certificate. +#[cfg(test)] #[derive(Debug, Clone, Copy)] pub(crate) struct ClassicHllConfidence { max_distinct: u32, relative_error: f64, } +#[cfg(test)] impl ClassicHllConfidence { pub(crate) fn new(max_distinct: u32, relative_error: f64) -> Option { (max_distinct > 0 @@ -156,35 +164,6 @@ impl ClassicHllConfidence { }) } - #[cfg(test)] - pub(crate) fn guarantee(&self, precision: u8) -> Option { - let delta = self.failure_probability(precision)?; - Some(AccuracyGuarantee::new( - AccuracyMetric::Relative, - BoundExpr::Constant { - value: self.relative_error, - }, - ProbabilityExpr::Constant { value: delta }, - vec![GuaranteeSource::SketchEvaluation { - algorithm: "Hll".into(), - contract: CLASSIC_CONTRACT.into(), - params: serde_json::json!({"precision": precision, - "max_distinct": self.max_distinct, "relative_error": self.relative_error, - "hash_assumption": "independent_uniform_buckets", - "population_scope": "complete_evaluation_including_merged_tumbling_windows"}), - query: "Cardinality".into(), - }], - )) - } - - #[cfg(test)] - pub(crate) fn precision(&self, delta: f64) -> Option { - if !delta.is_finite() || !(0.0..1.0).contains(&delta) || delta == 0.0 { - return None; - } - (4..=18).find(|&p| self.failure_probability(p).is_some_and(|d| d <= delta)) - } - /// Finite bound, not an asymptotic RSE fit. With N distinct hashes and K /// occupied buckets, C=N-K collision arrivals satisfy /// P(C>=t) <= lambda^t/t!, lambda=N(N-1)/(2m): each arrival's conditional @@ -197,7 +176,7 @@ impl ClassicHllConfidence { /// deterministically; underestimation implies C>epsilon*N. /// We maximize the collision bound over EVERY integer N in the contract, /// not just its upper endpoint (small-cardinality tails matter). - fn failure_probability(&self, precision: u8) -> Option { + pub(super) fn failure_probability(&self, precision: u8) -> Option { if !(4..=MAX_PRECISION).contains(&precision) { return None; } @@ -226,47 +205,6 @@ impl ClassicHllConfidence { } } -/// The smallest precision, at least `at_least`, whose classic failure -/// probability at `relative_error` over a source of at most `max_distinct` -/// distinct items is at most `failure_probability`; `at_least` when none up -/// to 18 is. Pass 1's sizing for a failure probability -/// (`sizing::sized_for_failure_probability`) -/// applies this rule to the source's bound, its sizing for `ε` -/// (`hll_precision`) to a bound of `⌈1/ε⌉`. -pub fn min_precision( - relative_error: f64, - failure_probability: f64, - max_distinct: u64, - at_least: u8, -) -> u8 { - (at_least..=18) - .find(|&p| { - classic_failure_probability(p, relative_error, max_distinct) <= failure_probability - }) - .unwrap_or(at_least) -} - -/// Classic HLL's precision for relative error `eps` with failure -/// probability `delta`, without data (#694). Below `1/ε` distinct items a -/// single bucket collision already exceeds the error, and the chance of -/// one is about `N²/(2m)`; a certificate for any bound of at least `1/ε` -/// therefore needs `m ≥ 1/(2ε²δ)`. This is the smallest such precision at -/// which [`ClassicHllConfidence`] certifies `delta` at `eps` for every -/// bound up to `⌈1/ε⌉` (18 when none up to 18 does). Pass 1 then raises -/// the precision by the same rule ([`min_precision`]) when the source's own -/// bound or a smaller failure probability needs it. -#[cfg(test)] -pub(crate) fn hll_precision(eps: f64, delta: f64) -> u8 { - if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) { - return 18; - } - let start = saturating_ceil((1.0 / (2.0 * eps * eps * delta.min(1.0))).log2(), 4, 18) as u8; - let reference = (1.0 / eps).ceil().min(f64::from(MAX_CONTRACT_DISTINCT)) as u64; - (start..=18) - .find(|&p| classic_failure_probability(p, eps, reference) <= delta) - .unwrap_or(18) -} - #[cfg(test)] mod tests { use super::*; @@ -347,37 +285,6 @@ mod tests { } } - /// A supported estimator contract supplies a probability, unlike generic HLL RSE. - #[test] - fn bounded_classic_hll_has_a_feasible_confidence_target() { - let model = ClassicHllConfidence::new(128, 0.05).unwrap(); - let precision = model.precision(0.01).expect("finite confidence-sized HLL"); - let guarantee = model.guarantee(precision).unwrap(); - assert!(!guarantee.has_unknown()); - assert!(guarantee.spec.failure_probability.evaluate().unwrap() <= 0.01); - assert_eq!(guarantee.spec.error.evaluate(), Some(0.05)); - } - /// Tighter confidence must increase precision or explicitly become unavailable. - #[test] - fn sizing_and_domain_limits_are_consistent() { - let model = ClassicHllConfidence::new(128, 0.05).unwrap(); - assert!(model.precision(0.001).unwrap() > model.precision(0.01).unwrap()); - assert!(model.precision(1e-12).is_none()); - assert!(model.precision(0.0).is_none()); - assert!(model.precision(f64::NAN).is_none()); - assert!(model.guarantee(3).is_none()); - assert!(model.guarantee(19).is_none()); - assert!(model.guarantee(7).is_none()); - for (n, e) in [ - (0, 0.05), - (MAX_CONTRACT_DISTINCT + 1, 0.05), - (128, 0.0), - (128, f64::NAN), - ] { - assert!(ClassicHllConfidence::new(n, e).is_none()); - } - } - /// Exact occupancy probabilities independently check both tails for every N. #[test] fn probability_bound_dominates_exact_occupancy_distribution() { @@ -419,16 +326,7 @@ mod tests { fn native_classic_estimator_and_merged_registers_use_the_same_contract() { use asap_sketchlib::sketches::hll::{Classic, HyperLogLogP16}; let model = ClassicHllConfidence::new(128, 0.05).unwrap(); - assert!( - model - .guarantee(16) - .unwrap() - .spec - .failure_probability - .evaluate() - .unwrap() - < 0.01 - ); + assert!(model.failure_probability(16).unwrap() < 0.01); let mut single = HyperLogLogP16::::new(); let mut left = HyperLogLogP16::::new(); let mut right = HyperLogLogP16::::new(); @@ -456,26 +354,9 @@ mod tests { assert_eq!(left.estimate(), expected); assert!((expected as f64 - 128.0).abs() / 128.0 <= 0.05); } - /// Pass 1 sizes classic HLL from (ε, δ) without data (#694): the - /// smallest precision with `m ≥ 1/(2ε²δ)` that the tail formula - /// certifies at the target ε, which its guarantee states as its error - /// bound. - #[test] - fn precision_is_sized_from_epsilon_and_delta() { - use crate::guarantee::size_params; - use asap_types::ir::operator::agg_intent::default_cardinality; - for (eps, delta, precision) in [(0.05, 0.01, 15), (0.02, 0.01, 17)] { - let params = size_params(SketchAlgorithm::Hll, &default_cardinality(), eps, delta); - let SketchParams::Hll { precision: sized } = params else { - panic!("{params:?}") - }; - assert_eq!(sized, precision); - } - } - #[test] fn generic_rse_sizing_does_not_certify_confidence() { - use crate::guarantee::size_params; + use crate::guarantee::sizing_oracle::size_params; use asap_types::ir::operator::agg_intent::default_cardinality; let c = default_cardinality(); let params = size_params(SketchAlgorithm::Hll, &c, 0.01, 0.01); diff --git a/crates/accuracy/src/guarantee/kll.rs b/crates/accuracy/src/guarantee/kll.rs index c450d4573..0c509da0f 100644 --- a/crates/accuracy/src/guarantee/kll.rs +++ b/crates/accuracy/src/guarantee/kll.rs @@ -48,26 +48,13 @@ pub(crate) fn kll_rank_error_99(k: u32) -> f64 { KLL_RANK_ERROR_COEFFICIENT_99 / f64::from(k).powf(KLL_RANK_ERROR_EXPONENT_99) } -/// Invert Apache DataSketches' empirical 99th-percentile, single-sided KLL -/// normalized rank-error fit: `epsilon = 2.296 / k^0.9723`. Capped at -/// [`KLL_MAX_K`], the largest `k` `asap_sketchlib` builds; an `eps` that -/// needs more gets that `k`, whose guarantee then misses the target. -#[cfg(test)] -pub(crate) fn kll_k(eps: f64) -> u32 { - saturating_ceil( - (KLL_RANK_ERROR_COEFFICIENT_99 / eps).powf(1.0 / KLL_RANK_ERROR_EXPONENT_99), - 8, - KLL_MAX_K, - ) -} - /// How much the rank error at failure probability `delta` exceeds the error /// at the calibrated 0.01, modelling the error as Gaussian: the ratio of the /// two-sided standard normal quantiles, `z(1 − delta/2) / z(1 − 0.01/2)`. /// It grows faster as `delta` shrinks than the KLL bound's /// `sqrt(ln(1/delta))` (1.277 vs 1.225 at `delta` = 0.001), so it is the /// conservative choice. 1 for `delta >= 0.01`; `None` unless `0 < delta < 1`. -fn delta_scale(delta: f64) -> Option { +pub(super) fn delta_scale(delta: f64) -> Option { if !(delta > 0.0 && delta < 1.0) { None } else if delta >= KLL_CALIBRATED_FAILURE_PROBABILITY { @@ -131,26 +118,13 @@ fn normal_quantile(p: f64) -> f64 { } } -/// `k` for rank error `eps` at failure probability `delta`: the empirical -/// 99% calibration for `delta >= 0.01`; below, the calibration at -/// `eps / delta_scale(delta)`, recording `delta` so the guarantee reports it. -#[cfg(test)] -pub(crate) fn size_params(eps: f64, delta: f64) -> SketchParams { - if delta.is_nan() || delta <= 0.0 || delta >= KLL_CALIBRATED_FAILURE_PROBABILITY { - return SketchParams::Kll { k: kll_k(eps) }; - } - SketchParams::Kll { - k: kll_k(eps / delta_scale(delta).unwrap_or(1.0)), - } -} - #[cfg(test)] mod tests { use super::*; #[test] fn local_guarantee_inverts_rank_sizing() { - use crate::guarantee::size_params; + use crate::guarantee::sizing_oracle::size_params; use asap_types::ir::operator::agg_intent::default_quantile; let q = default_quantile(0.99); let params = size_params(SketchAlgorithm::Kll, &q, 0.01, 0.01); @@ -172,14 +146,6 @@ mod tests { ))); } - /// `k` never exceeds the 26 602 `asap_sketchlib` silently caps it at, so - /// a guarantee never claims a larger `k` than runs. - #[test] - fn kll_k_is_capped_at_the_library_maximum() { - assert_eq!(kll_k(1e-6), KLL_MAX_K); - assert_eq!(KLL_MAX_K, 26_602); - } - /// A hand-built `k` above the library's cap gives no guarantee. #[test] fn a_k_above_the_library_cap_gives_no_guarantee() { @@ -198,6 +164,7 @@ mod tests { /// `z(1 − δ/2) / z(1 − 0.01/2)`. #[test] fn delta_scale_is_the_gaussian_quantile_ratio() { + use crate::guarantee::sizing_oracle::{kll_k, kll_params}; assert_eq!(delta_scale(0.01), Some(1.0)); assert_eq!(delta_scale(0.5), Some(1.0)); let ratio = delta_scale(0.001).unwrap(); @@ -213,37 +180,10 @@ mod tests { assert!((scale - expected).abs() < 1e-8, "{delta}: {scale}"); } assert_eq!( - size_params(0.01, 0.001), + kll_params(0.01, 0.001), SketchParams::Kll { k: kll_k(0.01 / ratio), } ); } - - /// KLL `k` inverts the rank-error fit: ε = 0.01 → 269, ε = 0.05 → 52. - #[test] - fn accuracy_target_drives_kll_k() { - use crate::guarantee::size_params; - use asap_types::ir::operator::agg_intent::default_quantile; - let q = default_quantile(0.99); - assert_eq!( - size_params(SketchAlgorithm::Kll, &q, 0.01, 0.01), - SketchParams::Kll { k: 269 } - ); - assert_eq!( - size_params(SketchAlgorithm::Kll, &q, 0.05, 0.01), - SketchParams::Kll { k: 52 } - ); - } - - /// A zero ε saturates KLL `k` to the tightest buildable value. - #[test] - fn degenerate_epsilon_saturates_to_tightest_kll_params() { - use crate::guarantee::size_params; - use asap_types::ir::operator::agg_intent::default_quantile; - assert_eq!( - size_params(SketchAlgorithm::Kll, &default_quantile(0.99), 0.0, 0.01), - SketchParams::Kll { k: 26_602 } - ); - } } diff --git a/crates/accuracy/src/guarantee/mod.rs b/crates/accuracy/src/guarantee/mod.rs index fed1e51d9..60a98efe7 100644 --- a/crates/accuracy/src/guarantee/mod.rs +++ b/crates/accuracy/src/guarantee/mod.rs @@ -7,8 +7,6 @@ use asap_types::summary_type::{SketchAlgorithm, SketchParams, SketchStatistic}; #[cfg(test)] use crate::requirements::meets; -#[cfg(test)] -use asap_types::ir::operator::AggIntent; use asap_types::summary_type::SummaryTypeCapability; pub(crate) mod cardinality; @@ -17,6 +15,8 @@ pub(crate) mod count_sketch; pub(crate) mod ddsketch; pub mod hll; pub(crate) mod kll; +#[cfg(test)] +mod sizing_oracle; pub mod univmon; #[allow(dead_code)] // Read again for the error bound of each listed θ (`parameter_list`), in #1207 PRs 3–4. @@ -88,89 +88,6 @@ pub fn theoretical_guarantee( } } -/// Today's sizing: the parameters of algorithm `kind` for error `eps` at failure -/// probability `delta`. Test-only: the predefined lists (`parameter_list`) -/// are this sizing over an error grid, which a test keeps equal. -#[cfg(test)] -pub(crate) fn size_params( - kind: SketchAlgorithm, - intent: &AggIntent, - eps: f64, - delta: f64, -) -> SketchParams { - match kind { - SketchAlgorithm::UnivMon => univmon::size_params(intent, eps, delta), - SketchAlgorithm::Kll => kll::size_params(eps, delta), - SketchAlgorithm::Cms => SketchParams::Cms { - width: cms::cms_width(eps), - depth: cms::cms_depth(delta), - }, - SketchAlgorithm::Hll => SketchParams::Hll { - precision: hll::hll_precision(eps, delta), - }, - SketchAlgorithm::CmsWithHeap => { - let k = match intent { - AggIntent::TopK { k, .. } => *k, - _ => unreachable!("CmsWithHeap is only a TopK candidate"), - }; - SketchParams::CmsWithHeap { - width: cms::cms_width(eps), - depth: cms::cms_depth(delta), - heap_size: topk_capacity(k, eps), - } - } - // Non-preferred candidates (DDSketch / Kmv / CountSketch / - // CountSketchWithHeap) are only reachable once a cost model picks - // them; sized here so that wiring is local. - SketchAlgorithm::DDSketch => ddsketch::size_params(eps), - SketchAlgorithm::Kmv => SketchParams::Kmv { - k: cardinality::kmv_k(eps, delta), - }, - SketchAlgorithm::CountSketch => { - let width = count_sketch::count_sketch_width(eps); - SketchParams::CountSketch { - width, - depth: count_sketch::count_sketch_depth(width, delta), - } - } - SketchAlgorithm::CountSketchWithHeap => { - let k = match intent { - AggIntent::TopK { k, .. } => *k, - _ => unreachable!("CountSketchWithHeap is only a TopK candidate"), - }; - let width = count_sketch::count_sketch_width(eps); - SketchParams::CountSketchWithHeap { - width, - depth: count_sketch::count_sketch_depth(width, delta), - heap_size: topk_capacity(k, eps), - } - } - // Listed, not `_`: a family `asap_sketchlib` adds fails to compile - // here until the planner sizes it or lists it as not offered. - SketchAlgorithm::CountSketchWithL2Norm - | SketchAlgorithm::CmsWithSpaceSaving - | SketchAlgorithm::CountSketchWithSpaceSaving - | SketchAlgorithm::CmsFold - | SketchAlgorithm::CountSketchFold - | SketchAlgorithm::HllHip - | SketchAlgorithm::KllDynamic - | SketchAlgorithm::SpaceSaving - | SketchAlgorithm::Elastic - | SketchAlgorithm::Coco - | SketchAlgorithm::Bloom - | SketchAlgorithm::SetAggregator - | SketchAlgorithm::UnivMonTwoTier - | SketchAlgorithm::UnivMonQ - | SketchAlgorithm::HydraCms - | SketchAlgorithm::HydraCountSketch - | SketchAlgorithm::HydraKll - | SketchAlgorithm::HydraHll - | SketchAlgorithm::HydraUnivMon => { - unreachable!("Pass 1 offers only the families in FAMILY_PREFERENCE, not {kind:?}") - } - } -} - /// `P(Binomial(n, p) ≥ k)`, summed term by term in log space and rounded /// up by a relative 1e-12 so rounding never certifies a smaller tail. pub(crate) fn binomial_upper_tail(n: u32, p: f64, k: u32) -> f64 { @@ -193,139 +110,3 @@ pub(crate) fn binomial_upper_tail(n: u32, p: f64, k: u32) -> f64 { } (tail * (1.0 + 1e-12)).min(1.0) } - -/// Accuracy-dependent candidate budget, not a completeness theorem. The -/// membership model must still certify the selected set independently. -#[cfg(test)] -pub(crate) fn topk_capacity(k: usize, eps: f64) -> u32 { - u32::try_from(k) - .unwrap_or(u32::MAX) - .max(saturating_ceil(1.0 / eps, 1, 1 << 26)) -} - -/// `⌈x⌉` clamped to `[lo, hi]`; NaN / non-positive x saturate to `hi` -/// (a degenerate ε means "as accurate as this family goes"). -pub(crate) fn saturating_ceil(x: f64, lo: u32, hi: u32) -> u32 { - if !x.is_finite() || x <= 0.0 { - return hi; - } - (x.ceil() as u32).clamp(lo, hi) -} - -#[cfg(test)] -mod tests { - use super::*; - - /// Each algorithm's predefined list (`parameter_list`) is today's sizing - /// over the error grid ε = 0.1 … 0.001 at failure probability 0.01, - /// smallest first, without repeats; KMV's and UnivMon's distinct counts - /// stop at ε = 0.01. Count-Min lists each sized width with depths 5, 7, - /// 10 and 12, Count Sketch with 47, 81, 117 and 155, and a heap variant - /// each of those with - /// every heap size of the 1-2-5 series 10 … 10 000. UnivMon's list also - /// combines each L2 shape with each distinct-count shape (28 entries). - #[test] - fn parameter_list_is_the_sizing_over_the_error_grid() { - use asap_types::ir::operator::agg_intent::{default_cardinality, default_quantile}; - use asap_types::summary_type::parameter_list; - let full_grid = [0.1, 0.05, 0.02, 0.01, 0.005, 0.002, 0.001]; - let distinct_grid = [0.1, 0.05, 0.02, 0.01]; - let cms_depths = [5, 7, 10, 12]; - let count_sketch_depths = [47, 81, 117, 155]; - let heap_sizes = [10, 20, 50, 100, 200, 500, 1_000, 2_000, 5_000, 10_000]; - let l2 = AggIntent::FrequencyL2 { col: None }; - let top_1 = AggIntent::TopK { k: 1 }; - let quantile = default_quantile(0.5); - let distinct = default_cardinality(); - for (algorithm, intents) in [ - (SketchAlgorithm::Kll, vec![&quantile]), - (SketchAlgorithm::DDSketch, vec![&quantile]), - (SketchAlgorithm::Hll, vec![&distinct]), - (SketchAlgorithm::Kmv, vec![&distinct]), - (SketchAlgorithm::Cms, vec![&distinct]), - (SketchAlgorithm::CountSketch, vec![&distinct]), - (SketchAlgorithm::CmsWithHeap, vec![&top_1]), - (SketchAlgorithm::CountSketchWithHeap, vec![&top_1]), - (SketchAlgorithm::UnivMon, vec![&l2, &distinct, &quantile]), - ] { - let mut sized: Vec = Vec::new(); - for intent in intents { - let grid: &[f64] = match (algorithm, intent) { - ( - SketchAlgorithm::Kmv | SketchAlgorithm::UnivMon, - AggIntent::Cardinality { .. }, - ) => &distinct_grid, - _ => &full_grid, - }; - for &eps in grid { - let listed: Vec = match size_params(algorithm, intent, eps, 0.01) - { - SketchParams::Cms { width, .. } => cms_depths - .iter() - .map(|&depth| SketchParams::Cms { width, depth }) - .collect(), - SketchParams::CountSketch { width, .. } => count_sketch_depths - .iter() - .map(|&depth| SketchParams::CountSketch { width, depth }) - .collect(), - SketchParams::CmsWithHeap { width, .. } => cms_depths - .iter() - .flat_map(|&depth| { - heap_sizes - .iter() - .map(move |&heap_size| SketchParams::CmsWithHeap { - width, - depth, - heap_size, - }) - }) - .collect(), - SketchParams::CountSketchWithHeap { width, .. } => count_sketch_depths - .iter() - .flat_map(|&depth| { - heap_sizes.iter().map(move |&heap_size| { - SketchParams::CountSketchWithHeap { - width, - depth, - heap_size, - } - }) - }) - .collect(), - other => vec![other], - }; - for params in listed { - if !sized.contains(¶ms) { - sized.push(params); - } - } - } - } - let list = parameter_list(algorithm); - let (listed_sized, combined): (Vec<_>, Vec<_>) = - list.iter().partition(|params| sized.contains(params)); - assert_eq!( - format!("{listed_sized:?}"), - format!("{:?}", sized.iter().collect::>()), - "{algorithm:?}" - ); - let expected_combined = if algorithm == SketchAlgorithm::UnivMon { - 28 - } else { - 0 - }; - assert_eq!(combined.len(), expected_combined, "{algorithm:?}"); - } - } - - /// Classic HLL's precision grows until its failure probability over the - /// source's distinct bound meets the target, up to 18. - #[test] - fn classic_hll_precision_grows_for_its_failure_probability() { - let p = hll::min_precision(0.05, 0.01, 64, 4); - assert!(p > 4); - assert!(hll::classic_failure_probability(p, 0.05, 64) <= 0.01); - assert!(hll::classic_failure_probability(p - 1, 0.05, 64) > 0.01); - assert_eq!(hll::min_precision(0.05, 1e-30, 4096, 12), 12); - } -} diff --git a/crates/accuracy/src/guarantee/sizing_oracle.rs b/crates/accuracy/src/guarantee/sizing_oracle.rs new file mode 100644 index 000000000..0df88e3cb --- /dev/null +++ b/crates/accuracy/src/guarantee/sizing_oracle.rs @@ -0,0 +1,676 @@ +//! The closed-form sizing per summary type that the predefined parameter +//! lists (`asap_types::summary_type::parameter_list`) are checked against: +//! the parameters of a summary type for error `ε` at failure probability +//! `δ`. Test-only; the planner itself only reads the predefined lists. +use super::*; +use asap_types::ir::operator::AggIntent; +use asap_types::summary_type::KLL_MAX_K; + +/// The parameters of algorithm `kind` for error `eps` at failure +/// probability `delta`. The predefined lists (`parameter_list`) are this +/// sizing over an error grid, which a test keeps equal. +pub(super) fn size_params( + kind: SketchAlgorithm, + intent: &AggIntent, + eps: f64, + delta: f64, +) -> SketchParams { + match kind { + SketchAlgorithm::UnivMon => univmon_params(intent, eps, delta), + SketchAlgorithm::Kll => kll_params(eps, delta), + SketchAlgorithm::Cms => SketchParams::Cms { + width: cms_width(eps), + depth: cms_depth(delta), + }, + SketchAlgorithm::Hll => SketchParams::Hll { + precision: hll_precision(eps, delta), + }, + SketchAlgorithm::CmsWithHeap => { + let k = match intent { + AggIntent::TopK { k, .. } => *k, + _ => unreachable!("CmsWithHeap is only a TopK candidate"), + }; + SketchParams::CmsWithHeap { + width: cms_width(eps), + depth: cms_depth(delta), + heap_size: topk_capacity(k, eps), + } + } + // Non-preferred candidates (DDSketch / Kmv / CountSketch / + // CountSketchWithHeap) are only reachable once a cost model picks + // them; sized here so that wiring is local. + SketchAlgorithm::DDSketch => SketchParams::DDSketch { alpha: eps }, + SketchAlgorithm::Kmv => SketchParams::Kmv { + k: kmv_k(eps, delta), + }, + SketchAlgorithm::CountSketch => { + let width = count_sketch_width(eps); + SketchParams::CountSketch { + width, + depth: count_sketch_depth(width, delta), + } + } + SketchAlgorithm::CountSketchWithHeap => { + let k = match intent { + AggIntent::TopK { k, .. } => *k, + _ => unreachable!("CountSketchWithHeap is only a TopK candidate"), + }; + let width = count_sketch_width(eps); + SketchParams::CountSketchWithHeap { + width, + depth: count_sketch_depth(width, delta), + heap_size: topk_capacity(k, eps), + } + } + // Listed, not `_`: a family `asap_sketchlib` adds fails to compile + // here until the planner sizes it or lists it as not offered. + SketchAlgorithm::CountSketchWithL2Norm + | SketchAlgorithm::CmsWithSpaceSaving + | SketchAlgorithm::CountSketchWithSpaceSaving + | SketchAlgorithm::CmsFold + | SketchAlgorithm::CountSketchFold + | SketchAlgorithm::HllHip + | SketchAlgorithm::KllDynamic + | SketchAlgorithm::SpaceSaving + | SketchAlgorithm::Elastic + | SketchAlgorithm::Coco + | SketchAlgorithm::Bloom + | SketchAlgorithm::SetAggregator + | SketchAlgorithm::UnivMonTwoTier + | SketchAlgorithm::UnivMonQ + | SketchAlgorithm::HydraCms + | SketchAlgorithm::HydraCountSketch + | SketchAlgorithm::HydraKll + | SketchAlgorithm::HydraHll + | SketchAlgorithm::HydraUnivMon => { + unreachable!("Pass 1 offers only the families in ALGORITHM_PREFERENCE, not {kind:?}") + } + } +} + +/// Accuracy-dependent candidate budget, not a completeness theorem. The +/// membership model must still certify the selected set independently. +fn topk_capacity(k: usize, eps: f64) -> u32 { + u32::try_from(k) + .unwrap_or(u32::MAX) + .max(saturating_ceil(1.0 / eps, 1, 1 << 26)) +} + +/// `⌈x⌉` clamped to `[lo, hi]`; NaN / non-positive x saturate to `hi` +/// (a degenerate ε means "as accurate as this family goes"). +fn saturating_ceil(x: f64, lo: u32, hi: u32) -> u32 { + if !x.is_finite() || x <= 0.0 { + return hi; + } + (x.ceil() as u32).clamp(lo, hi) +} + +// Count-Min Sketch. + +/// CMS: over-count ≤ ε·N with width `w = ⌈e/ε⌉` columns. +fn cms_width(eps: f64) -> u32 { + saturating_ceil(std::f64::consts::E / eps, 2, 1 << 26) +} + +/// CMS: failure probability ≤ δ with depth `d = ⌈ln(1/δ)⌉` rows. +/// δ = 0.01 → depth 5. +fn cms_depth(delta: f64) -> u32 { + saturating_ceil((1.0 / delta).ln(), 1, 32) +} + +// Count Sketch. + +/// CountSketch `L2` point-query width: ε = sqrt(3/w). +pub(super) fn count_sketch_width(eps: f64) -> u32 { + saturating_ceil(3.0 / (eps * eps), 2, 1 << 26) +} + +/// The smallest positive odd depth whose binomial median failure +/// probability at `width` is at most `delta`, capped at 255. +pub(super) fn count_sketch_depth(width: u32, delta: f64) -> u32 { + if !(delta.is_finite() && delta > 0.0 && delta < 1.0) { + return 255; + } + (1..=255) + .step_by(2) + .find(|&depth| { + count_sketch::count_sketch_failure_probability(width, depth) + .is_some_and(|tail| tail <= delta) + }) + .unwrap_or(255) +} + +// KMV. + +/// The largest `k` sizing returns. +const KMV_MAX_K: u32 = 1 << 26; + +/// The smallest `k` whose KMV failure probability at relative error `eps` +/// is at most `delta` ([`cardinality::kmv_failure_probability`]), up to +/// `2^26`; a degenerate `eps` or `delta` saturates to `2^26`. +fn kmv_k(eps: f64, delta: f64) -> u32 { + use cardinality::{kmv_failure_probability, KMV_MIN_K}; + if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) { + return KMV_MAX_K; + } + // The overestimate term alone at most `δ` bounds `k` below; both terms + // at most `δ/2` bound it above. + let k_at = |ln_inverse: f64| { + saturating_ceil( + 1.0 + (1.0 + eps) * (2.0 + eps) * ln_inverse / (eps * eps), + KMV_MIN_K, + KMV_MAX_K, + ) + }; + let (mut lo, mut hi) = (k_at((1.0 / delta).ln()), k_at((2.0 / delta).ln())); + if kmv_failure_probability(hi, eps) > delta { + return KMV_MAX_K; + } + while lo < hi { + let mid = lo + (hi - lo) / 2; + if kmv_failure_probability(mid, eps) <= delta { + hi = mid; + } else { + lo = mid + 1; + } + } + hi +} + +// HLL. + +/// Classic HLL's precision for relative error `eps` with failure +/// probability `delta`, without data. Below `1/ε` distinct items a single +/// bucket collision already exceeds the error, and the chance of one is +/// about `N²/(2m)`; a certificate for any bound of at least `1/ε` +/// therefore needs `m ≥ 1/(2ε²δ)`. This is the smallest such precision at +/// which [`hll::ClassicHllConfidence`] certifies `delta` at `eps` for every +/// bound up to `⌈1/ε⌉` (18 when none up to 18 does). +fn hll_precision(eps: f64, delta: f64) -> u8 { + if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) { + return 18; + } + let start = saturating_ceil((1.0 / (2.0 * eps * eps * delta.min(1.0))).log2(), 4, 18) as u8; + let reference = (1.0 / eps) + .ceil() + .min(f64::from(hll::MAX_CONTRACT_DISTINCT)) as u64; + (start..=18) + .find(|&p| hll::classic_failure_probability(p, eps, reference) <= delta) + .unwrap_or(18) +} + +/// The smallest precision, at least `at_least`, whose classic failure +/// probability at `relative_error` over a source of at most `max_distinct` +/// distinct items is at most `failure_probability`; `at_least` when none up +/// to 18 is: [`hll_precision`]'s rule for a source's own distinct bound. +fn min_precision( + relative_error: f64, + failure_probability: f64, + max_distinct: u64, + at_least: u8, +) -> u8 { + (at_least..=18) + .find(|&p| { + hll::classic_failure_probability(p, relative_error, max_distinct) <= failure_probability + }) + .unwrap_or(at_least) +} + +/// The smallest precision at which classic HLL certifies failure +/// probability `delta` at `relative_error` over at most `max_distinct` +/// distinct items ([`hll::ClassicHllConfidence`]); `None` when `delta` is +/// not in (0, 1), the bound or error is outside the contract, or no +/// precision up to 18 certifies it. +fn classic_hll_precision(max_distinct: u32, relative_error: f64, delta: f64) -> Option { + if !(delta.is_finite() && delta > 0.0 && delta < 1.0) { + return None; + } + let model = hll::ClassicHllConfidence::new(max_distinct, relative_error)?; + (4..=hll::MAX_PRECISION).find(|&p| model.failure_probability(p).is_some_and(|d| d <= delta)) +} + +// KLL. + +/// Invert Apache DataSketches' empirical 99th-percentile, single-sided KLL +/// normalized rank-error fit: `epsilon = 2.296 / k^0.9723`. Capped at +/// [`KLL_MAX_K`], the largest `k` `asap_sketchlib` builds; an `eps` that +/// needs more gets that `k`, whose guarantee then misses the target. +pub(super) fn kll_k(eps: f64) -> u32 { + saturating_ceil( + (kll::KLL_RANK_ERROR_COEFFICIENT_99 / eps).powf(1.0 / kll::KLL_RANK_ERROR_EXPONENT_99), + 8, + KLL_MAX_K, + ) +} + +/// `k` for rank error `eps` at failure probability `delta`: the empirical +/// 99% calibration for `delta >= 0.01`; below, the calibration at +/// `eps / delta_scale(delta)`, recording `delta` so the guarantee reports it. +pub(super) fn kll_params(eps: f64, delta: f64) -> SketchParams { + if delta.is_nan() || delta <= 0.0 || delta >= kll::KLL_CALIBRATED_FAILURE_PROBABILITY { + return SketchParams::Kll { k: kll_k(eps) }; + } + SketchParams::Kll { + k: kll_k(eps / kll::delta_scale(delta).unwrap_or(1.0)), + } +} + +// UnivMon. + +/// Layers `asap_sketchlib` builds: layer `i` hashes at seed index `i`, and +/// seed 19 picks the layers a key reaches. +const UNIVMON_MAX_LAYERS: u8 = asap_sketchlib::sketch_framework::univmon::UNIVMON_MAX_LAYERS as u8; +/// The most rows an L2 sketch is sized with: the deepest odd shape within +/// the 20 rows the executor builds ([`univmon::hash_independent`]), so the +/// row median is one row's estimate, and within the hash budget at the +/// more than 20 columns an L2 guarantee needs (5 column bits: +/// 19 · 6 = 114 ≤ 128). +const UNIVMON_MAX_L2_ROWS: u32 = 19; +/// Each row of a layer reads its column and sign bits from one hash. +const UNIVMON_HASH_BITS: u32 = 128; +/// The largest distinct-count heap sizing returns. +const UNIVMON_MAX_HEAP: u32 = 1 << 26; + +/// The shape baseline for readouts without a size model: the total (exact +/// whatever the shape) and entropy (uncertified). +pub(super) const UNIVMON_BASELINE: SketchParams = SketchParams::UnivMon { + heap_size: 256, + sketch_rows: 5, + sketch_cols: 1024, + layers: 16, +}; + +/// The smallest rows and columns whose L2 guarantee meets `(eps, delta)`, +/// clamped to the hash budget: with more rows than +/// [`UNIVMON_MAX_L2_ROWS`], or more columns than `rows` leave bits for, the +/// shape is the largest one built and its guarantee misses the target. +fn univmon_l2_shape(eps: f64, delta: f64) -> (u32, u32) { + use univmon::{l2_failure_probability, l2_relative_error, L2_ROW_FAILURE}; + let rows = (1..=UNIVMON_MAX_L2_ROWS) + .find(|&rows| l2_failure_probability(rows) <= delta) + .unwrap_or(UNIVMON_MAX_L2_ROWS); + let max_bits = (UNIVMON_HASH_BITS / rows - 1).min(26); + let max_cols = 1u32 << max_bits; + let meets = |cols: u32| l2_relative_error(cols).is_some_and(|error| error <= eps); + if !(eps.is_finite() && eps > 0.0) || !meets(max_cols) { + return (rows, max_cols); + } + // The norm's error `ε` needs `ε₂ ≤ 1 − (1 − ε)²`; a power-of-two width + // needs `2/(0.1 ε₂²)` columns and any other `9/(4 · 0.1 ε₂²)`. + let f2_error = 1.0 - (1.0 - eps.min(1.0)).powi(2); + let general = 9.0 / (4.0 * L2_ROW_FAILURE * f2_error * f2_error); + // Off powers of two the error falls as the width grows, and a power of + // two meets the target whenever its non-power-of-two neighbours do, so + // walking down from the estimate stops at the smallest such width. + let mut general = saturating_ceil(general, 1, max_cols); + while general > 1 && meets(general - 1) { + general -= 1; + } + while !meets(general) { + general += 1; + } + let power_of_two = (0..=max_bits) + .map(|bits| 1u32 << bits) + .find(|&cols| meets(cols)) + .unwrap_or(max_cols); + (rows, general.min(power_of_two)) +} + +/// The Chebyshev share of the distinct count's failure probability at +/// heap `k` and relative error `eps`: `1.35/(k ε²)`. +fn univmon_distinct_chebyshev(heap_size: u32, eps: f64) -> f64 { + univmon::DISTINCT_VARIANCE / (f64::from(heap_size) * eps * eps) +} + +/// The smallest heap `k ≥ 8` whose distinct count misses by more than +/// `eps · F0` with probability at most `delta`, top-layer completeness +/// included: `1.35/(k ε²) + (e/4)^(k/2) ≤ δ`. Capped; a capped heap's +/// guarantee misses the target. +fn univmon_distinct_heap(eps: f64, delta: f64) -> u32 { + if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) { + return UNIVMON_MAX_HEAP; + } + let meets = |k: u32| { + univmon_distinct_chebyshev(k, eps) + univmon::incomplete_top_layer_bound(k) <= delta + }; + let mut k = saturating_ceil( + univmon::DISTINCT_VARIANCE / (delta * eps * eps), + univmon::DISTINCT_MIN_HEAP, + UNIVMON_MAX_HEAP, + ); + while !meets(k) && k < UNIVMON_MAX_HEAP { + k += 1; + } + k +} + +/// Size a UnivMon for one readout's `(eps, delta)`: +/// - L2: the smallest rows and columns meeting the target +/// ([`univmon_l2_shape`]), one layer (L2 reads only layer 0) and a +/// one-key heap; +/// - distinct count: the smallest heap meeting it +/// ([`univmon_distinct_heap`]) and the most layers, since the layers the +/// top layer needs depend on the source's distinct bound, which plan +/// selection binds. The bound holds whatever the Count Sketch keeps in +/// the heaps, so each layer's is one counter; +/// - total and entropy: the baseline shape (the total is exact; entropy +/// has no certified bound). +fn univmon_params(intent: &AggIntent, eps: f64, delta: f64) -> SketchParams { + match intent { + AggIntent::FrequencyL2 { .. } => { + let (sketch_rows, sketch_cols) = univmon_l2_shape(eps, delta); + SketchParams::UnivMon { + heap_size: 1, + sketch_rows, + sketch_cols, + layers: 1, + } + } + AggIntent::Cardinality { .. } => SketchParams::UnivMon { + heap_size: univmon_distinct_heap(eps, delta), + sketch_rows: 1, + sketch_cols: 1, + layers: UNIVMON_MAX_LAYERS, + }, + _ => UNIVMON_BASELINE, + } +} + +mod tests { + use super::*; + use asap_types::ir::operator::agg_intent::{default_cardinality, default_quantile}; + + /// Classic HLL's precision grows until its failure probability over the + /// source's distinct bound meets the target, up to 18. + #[test] + fn classic_hll_precision_grows_for_its_failure_probability() { + let p = min_precision(0.05, 0.01, 64, 4); + assert!(p > 4); + assert!(hll::classic_failure_probability(p, 0.05, 64) <= 0.01); + assert!(hll::classic_failure_probability(p - 1, 0.05, 64) > 0.01); + assert_eq!(min_precision(0.05, 1e-30, 4096, 12), 12); + } + + /// A supported estimator contract supplies a probability, unlike + /// generic HLL RSE: sized for δ = 0.01 over at most 128 distinct items, + /// the classic guarantee binds to a known failure probability. + #[test] + fn bounded_classic_hll_has_a_feasible_confidence_target() { + let precision = + classic_hll_precision(128, 0.05, 0.01).expect("finite confidence-sized HLL"); + let guarantee = hll::classic_guarantee(precision, Some(0.05), "m") + .unwrap() + .bind(&|statistic| { + let (precision, eps, _) = hll::parse_classic_failure_statistic(statistic)?; + Some(hll::classic_failure_probability(precision, eps, 128)) + }); + assert!(!guarantee.has_unknown()); + assert!(guarantee.spec.failure_probability.evaluate().unwrap() <= 0.01); + assert_eq!(guarantee.spec.error.evaluate(), Some(0.05)); + } + + /// Tighter confidence must increase precision or explicitly become unavailable. + #[test] + fn sizing_and_domain_limits_are_consistent() { + let model = hll::ClassicHllConfidence::new(128, 0.05).unwrap(); + let precision = |delta| classic_hll_precision(128, 0.05, delta); + assert!(precision(0.001).unwrap() > precision(0.01).unwrap()); + assert!(precision(1e-12).is_none()); + assert!(precision(0.0).is_none()); + assert!(precision(f64::NAN).is_none()); + assert!(model.failure_probability(3).is_none()); + assert!(model.failure_probability(19).is_none()); + assert!(model.failure_probability(7).is_none()); + for (n, e) in [ + (0, 0.05), + (hll::MAX_CONTRACT_DISTINCT + 1, 0.05), + (128, 0.0), + (128, f64::NAN), + ] { + assert!(hll::ClassicHllConfidence::new(n, e).is_none()); + } + } + + /// Each algorithm's predefined list (`parameter_list`) is this sizing + /// over the error grid ε = 0.1 … 0.001 at failure probability 0.01, + /// smallest first, without repeats; KMV's and UnivMon's distinct counts + /// stop at ε = 0.01. Count-Min lists each sized width with depths 5, 7, + /// 10 and 12, Count Sketch with 47, 81, 117 and 155, and a heap variant + /// each of those with + /// every heap size of the 1-2-5 series 10 … 10 000. UnivMon's list also + /// combines each L2 shape with each distinct-count shape (28 entries). + #[test] + fn parameter_list_is_the_sizing_over_the_error_grid() { + use asap_types::summary_type::parameter_list; + let full_grid = [0.1, 0.05, 0.02, 0.01, 0.005, 0.002, 0.001]; + let distinct_grid = [0.1, 0.05, 0.02, 0.01]; + let cms_depths = [5, 7, 10, 12]; + let count_sketch_depths = [47, 81, 117, 155]; + let heap_sizes = [10, 20, 50, 100, 200, 500, 1_000, 2_000, 5_000, 10_000]; + let l2 = AggIntent::FrequencyL2 { col: None }; + let top_1 = AggIntent::TopK { k: 1 }; + let quantile = default_quantile(0.5); + let distinct = default_cardinality(); + for (algorithm, intents) in [ + (SketchAlgorithm::Kll, vec![&quantile]), + (SketchAlgorithm::DDSketch, vec![&quantile]), + (SketchAlgorithm::Hll, vec![&distinct]), + (SketchAlgorithm::Kmv, vec![&distinct]), + (SketchAlgorithm::Cms, vec![&distinct]), + (SketchAlgorithm::CountSketch, vec![&distinct]), + (SketchAlgorithm::CmsWithHeap, vec![&top_1]), + (SketchAlgorithm::CountSketchWithHeap, vec![&top_1]), + (SketchAlgorithm::UnivMon, vec![&l2, &distinct, &quantile]), + ] { + let mut sized: Vec = Vec::new(); + for intent in intents { + let grid: &[f64] = match (algorithm, intent) { + ( + SketchAlgorithm::Kmv | SketchAlgorithm::UnivMon, + AggIntent::Cardinality { .. }, + ) => &distinct_grid, + _ => &full_grid, + }; + for &eps in grid { + let listed: Vec = match size_params(algorithm, intent, eps, 0.01) + { + SketchParams::Cms { width, .. } => cms_depths + .iter() + .map(|&depth| SketchParams::Cms { width, depth }) + .collect(), + SketchParams::CountSketch { width, .. } => count_sketch_depths + .iter() + .map(|&depth| SketchParams::CountSketch { width, depth }) + .collect(), + SketchParams::CmsWithHeap { width, .. } => cms_depths + .iter() + .flat_map(|&depth| { + heap_sizes + .iter() + .map(move |&heap_size| SketchParams::CmsWithHeap { + width, + depth, + heap_size, + }) + }) + .collect(), + SketchParams::CountSketchWithHeap { width, .. } => count_sketch_depths + .iter() + .flat_map(|&depth| { + heap_sizes.iter().map(move |&heap_size| { + SketchParams::CountSketchWithHeap { + width, + depth, + heap_size, + } + }) + }) + .collect(), + other => vec![other], + }; + for params in listed { + if !sized.contains(¶ms) { + sized.push(params); + } + } + } + } + let list = parameter_list(algorithm); + let (listed_sized, combined): (Vec<_>, Vec<_>) = + list.iter().partition(|params| sized.contains(params)); + assert_eq!( + format!("{listed_sized:?}"), + format!("{:?}", sized.iter().collect::>()), + "{algorithm:?}" + ); + let expected_combined = if algorithm == SketchAlgorithm::UnivMon { + 28 + } else { + 0 + }; + assert_eq!(combined.len(), expected_combined, "{algorithm:?}"); + } + } + + /// CMS width is `⌈e/ε⌉` and depth `⌈ln(1/δ)⌉`. + #[test] + fn epsilon_delta_sizes_cms_depth() { + let intent = AggIntent::Count; + assert_eq!( + size_params(SketchAlgorithm::Cms, &intent, 0.001, 0.001), + SketchParams::Cms { + width: 2719, + depth: 7 + } // ⌈e/0.001⌉, ⌈ln 1000⌉ + ); + assert_eq!( + size_params(SketchAlgorithm::Cms, &intent, 0.001, 0.01), + SketchParams::Cms { + width: 2719, + depth: 5 + } + ); + assert_eq!( + size_params(SketchAlgorithm::Cms, &intent, 0.01, 0.01), + SketchParams::Cms { + width: 272, + depth: 5 + } + ); + } + + /// A top-k heap holds `max(k, ⌈1/ε⌉)` entries over a CMS sized as for counts. + #[test] + fn topk_heap_capacity_respects_accuracy_and_output_count() { + let intent = AggIntent::TopK { k: 25 }; + assert_eq!( + size_params(SketchAlgorithm::CmsWithHeap, &intent, 0.01, 0.01), + SketchParams::CmsWithHeap { + width: 272, // ⌈e/0.01⌉ + depth: 5, + heap_size: 100, + } + ); + } + + /// The executor's `CountSketch<_, RegularPath>` takes a column as the + /// low 32 hash bits modulo the width, so a row fails with probability + /// `1/3` (to within `2^-32`) at any width, not `3/8` off powers of two: + /// ε = 0.05 (width 1200) needs depth 47 at δ = 0.01, 81 at 1e-3 and + /// 117 at 1e-4, not 85, 149 and 215. + #[test] + fn depth_follows_the_libraries_modulo_column_hash() { + let width = count_sketch_width(0.05); + assert_eq!(width, 1200); + assert!((count_sketch::row_failure_probability(width) - 1.0 / 3.0).abs() < 1e-6); + assert_eq!( + [0.01, 1e-3, 1e-4].map(|delta| count_sketch_depth(width, delta)), + [47, 81, 117] + ); + } + + /// The depth is the smallest odd one whose binomial tail meets δ. Each + /// is at most Hoeffding's `ln(1/δ) / (2 (1/2 − p)²)` at the row's + /// failure probability `p ≈ 1/3`: `18 ln(1/δ)` at any width. + #[test] + fn count_sketch_depth_is_the_smallest_meeting_the_binomial_tail() { + use count_sketch::count_sketch_failure_probability; + for width in [1024, 3000, 30_000] { + let hoeffding = 18.0 * (1.0 + 1e-4); + for delta in [0.1, 0.01, 0.001] { + let depth = count_sketch_depth(width, delta); + assert!(depth % 2 == 1); + assert!(count_sketch_failure_probability(width, depth).unwrap() <= delta); + if depth > 1 { + assert!(count_sketch_failure_probability(width, depth - 2).unwrap() > delta); + } + assert!( + f64::from(depth) <= hoeffding * (1.0 / delta).ln(), + "{width} {delta}" + ); + } + } + // Any width fails a row with probability 1/3 (to within 2^-32 w/3): + // P(Bin(3, 1/3) ≥ 2) = 7/27. + for width in [1024, 1000] { + let tail = count_sketch_failure_probability(width, 3).unwrap(); + assert!((tail - 7.0 / 27.0).abs() < 1e-6, "{width}"); + } + assert_eq!(count_sketch_failure_probability(1000, 4), None); + } + + /// Pass 1 sizes classic HLL from (ε, δ) without data: the smallest + /// precision with `m ≥ 1/(2ε²δ)` that the tail formula certifies at the + /// target ε, which its guarantee states as its error bound. + #[test] + fn precision_is_sized_from_epsilon_and_delta() { + for (eps, delta, precision) in [(0.05, 0.01, 15), (0.02, 0.01, 17)] { + let params = size_params(SketchAlgorithm::Hll, &default_cardinality(), eps, delta); + let SketchParams::Hll { precision: sized } = params else { + panic!("{params:?}") + }; + assert_eq!(sized, precision); + } + } + + /// `k` never exceeds the 26 602 `asap_sketchlib` silently caps it at, so + /// a guarantee never claims a larger `k` than runs. + #[test] + fn kll_k_is_capped_at_the_library_maximum() { + assert_eq!(kll_k(1e-6), KLL_MAX_K); + assert_eq!(KLL_MAX_K, 26_602); + } + + /// KLL `k` inverts the rank-error fit: ε = 0.01 → 269, ε = 0.05 → 52. + #[test] + fn accuracy_target_drives_kll_k() { + let q = default_quantile(0.99); + assert_eq!( + size_params(SketchAlgorithm::Kll, &q, 0.01, 0.01), + SketchParams::Kll { k: 269 } + ); + assert_eq!( + size_params(SketchAlgorithm::Kll, &q, 0.05, 0.01), + SketchParams::Kll { k: 52 } + ); + } + + /// A zero ε saturates KLL `k` to the tightest buildable value. + #[test] + fn degenerate_epsilon_saturates_to_tightest_kll_params() { + assert_eq!( + size_params(SketchAlgorithm::Kll, &default_quantile(0.99), 0.0, 0.01), + SketchParams::Kll { k: 26_602 } + ); + } + + /// Example 2's Q1 (ε = 0.02, δ = 0.01) needs a heap of 337,500 keys, + /// `⌈1.35/(δ ε²)⌉`: the top layer's term is negligible at that heap. + /// At (0.5, 0.5) it is not: 1.35/(12 · 0.25) + (e/4)^6 > 0.5, while 13 + /// keys give 0.415 + 0.081. + #[test] + fn distinct_heap_for_example2_q1() { + assert_eq!(univmon_distinct_heap(0.02, 0.01), 337_500); + assert_eq!(univmon_distinct_heap(0.5, 0.5), 13); + } +} diff --git a/crates/accuracy/src/guarantee/univmon.rs b/crates/accuracy/src/guarantee/univmon.rs index c0545c20c..55ec1bf58 100644 --- a/crates/accuracy/src/guarantee/univmon.rs +++ b/crates/accuracy/src/guarantee/univmon.rs @@ -17,34 +17,16 @@ //! (OctoSketch aggregators fed promoted deltas) are not covered: the //! executor rejects them. use super::*; -#[cfg(test)] -use asap_types::ir::operator::AggIntent; -/// Layers `asap_sketchlib` builds: layer `i` hashes at seed index `i`, and -/// seed 19 picks the layers a key reaches. -#[cfg(test)] -pub(crate) const MAX_LAYERS: u8 = - asap_sketchlib::sketch_framework::univmon::UNIVMON_MAX_LAYERS as u8; -/// The most rows an L2 sketch is sized with: the deepest odd shape within -/// the 20 rows the executor builds ([`hash_independent`]), so the row median -/// is one row's estimate, and within the hash budget at the more than 20 -/// columns an L2 guarantee needs (5 column bits: 19 · 6 = 114 ≤ 128). -#[cfg(test)] -const MAX_L2_ROWS: u32 = 19; -/// Each row of a layer reads its column and sign bits from one hash. -#[cfg(test)] -const HASH_BITS: u32 = 128; /// The per-row failure probability the L2 guarantee fixes: a row misses by /// more than `ε₂ F2` with probability at most `2q/ε₂² = 0.1`. Fixing it /// lets a shape state one `(ε, δ)`: the columns give `ε`, the rows `δ`. -const L2_ROW_FAILURE: f64 = 0.1; +pub(super) const L2_ROW_FAILURE: f64 = 0.1; /// `Var[estimate_cardinality] ≤ 1.35 F0²/k` for `k ≥ 8`, the constant the library /// proves (it also states the looser `2 F0²/k`). -const DISTINCT_VARIANCE: f64 = 1.35; +pub(super) const DISTINCT_VARIANCE: f64 = 1.35; /// The smallest heap the distinct-count variance bound holds for. -const DISTINCT_MIN_HEAP: u32 = 8; -#[cfg(test)] -const CARD_CAP: u32 = 1 << 26; +pub(super) const DISTINCT_MIN_HEAP: u32 = 8; const L2_CONTRACT: &str = "univmon_layer0_f2_median_chebyshev_binomial_v1"; const DISTINCT_CONTRACT: &str = "univmon_distinct_complete_top_layer_chebyshev_v1"; @@ -53,16 +35,6 @@ const DISTINCT_CONTRACT: &str = "univmon_distinct_complete_top_layer_chebyshev_v const INCOMPLETE_TOP_LAYER: &str = "univmon_incomplete_top_layer_probability"; const MAX_DISTINCT: &str = "max_distinct"; -/// The shape baseline for readouts without a size model: the total (exact -/// whatever the shape) and entropy (uncertified). -#[cfg(test)] -const BASELINE: SketchParams = SketchParams::UnivMon { - heap_size: 256, - sketch_rows: 5, - sketch_cols: 1024, - layers: 16, -}; - pub(super) fn guarantee( algorithm: &SketchAlgorithm, params: &SketchParams, @@ -101,7 +73,7 @@ pub(super) fn guarantee( } /// Whether the executor builds this shape, with independent hashes: at -/// most [`MAX_LAYERS`] layers and `MATRIX_MAX_ROWS` (20) rows, the rows a +/// most `UNIVMON_MAX_LAYERS` (the library's) layers and `MATRIX_MAX_ROWS` (20) rows, the rows a /// UnivMon state encodes, and `rows · (⌈log2 cols⌉ + 1) ≤ 128` /// ([`asap_sketchlib::UnivMon::check_shape`]; the heap size is not part of /// the hash rules). @@ -122,7 +94,7 @@ pub(crate) fn hash_independent(rows: u32, cols: u32, layers: u8) -> bool { /// [`L2_ROW_FAILURE`] gives `ε₂ = √(2q/0.1)`. The norm then misses by at /// most `1 − √(1 − ε₂)` (the low side; the high side `√(1 + ε₂) − 1` is /// smaller). `None` when `ε₂ ≥ 1`. -fn l2_relative_error(cols: u32) -> Option { +pub(super) fn l2_relative_error(cols: u32) -> Option { let f2_error = (2.0 * column_collision(cols) / L2_ROW_FAILURE).sqrt(); (f2_error < 1.0).then(|| 1.0 - (1.0 - f2_error).sqrt()) } @@ -145,80 +117,16 @@ fn column_collision(cols: u32) -> f64 { /// The median of `rows` independent rows misses only when at least /// `⌈rows/2⌉` of them miss: `P(Binomial(rows, 0.1) ≥ ⌈rows/2⌉)`. -fn l2_failure_probability(rows: u32) -> f64 { +pub(super) fn l2_failure_probability(rows: u32) -> f64 { super::binomial_upper_tail(rows, L2_ROW_FAILURE, rows.div_ceil(2)) } -/// The smallest rows and columns whose L2 guarantee meets `(eps, delta)`, -/// clamped to the hash budget: with more rows than [`MAX_L2_ROWS`], or more -/// columns than `rows` leave bits for, the shape is the largest one built -/// and its guarantee misses the target. -#[cfg(test)] -fn l2_shape(eps: f64, delta: f64) -> (u32, u32) { - let rows = (1..=MAX_L2_ROWS) - .find(|&rows| l2_failure_probability(rows) <= delta) - .unwrap_or(MAX_L2_ROWS); - let max_bits = (HASH_BITS / rows - 1).min(26); - let max_cols = 1u32 << max_bits; - let meets = |cols: u32| l2_relative_error(cols).is_some_and(|error| error <= eps); - if !(eps.is_finite() && eps > 0.0) || !meets(max_cols) { - return (rows, max_cols); - } - // The norm's error `ε` needs `ε₂ ≤ 1 − (1 − ε)²`; a power-of-two width - // needs `2/(0.1 ε₂²)` columns and any other `9/(4 · 0.1 ε₂²)`. - let f2_error = 1.0 - (1.0 - eps.min(1.0)).powi(2); - let general = 9.0 / (4.0 * L2_ROW_FAILURE * f2_error * f2_error); - // Off powers of two the error falls as the width grows, and a power of - // two meets the target whenever its non-power-of-two neighbours do, so - // walking down from the estimate stops at the smallest such width. - let mut general = saturating_ceil(general, 1, max_cols); - while general > 1 && meets(general - 1) { - general -= 1; - } - while !meets(general) { - general += 1; - } - let power_of_two = (0..=max_bits) - .map(|bits| 1u32 << bits) - .find(|&cols| meets(cols)) - .unwrap_or(max_cols); - (rows, general.min(power_of_two)) -} - /// `(e/4)^(k/2)`: the chance the top layer of a heap-`k` pyramid misses a /// key, once the expected keys reaching it are at most `k/2` (Chernoff). -fn incomplete_top_layer_bound(heap_size: u32) -> f64 { +pub(super) fn incomplete_top_layer_bound(heap_size: u32) -> f64 { (f64::from(heap_size) / 2.0 * (1.0 - 2.0 * std::f64::consts::LN_2)).exp() } -/// The Chebyshev share of the distinct count's failure probability at -/// heap `k` and relative error `eps`: `1.35/(k ε²)`. -#[cfg(test)] -fn distinct_chebyshev(heap_size: u32, eps: f64) -> f64 { - DISTINCT_VARIANCE / (f64::from(heap_size) * eps * eps) -} - -/// The smallest heap `k ≥ 8` whose distinct count misses by more than -/// `eps · F0` with probability at most `delta`, top-layer completeness -/// included: `1.35/(k ε²) + (e/4)^(k/2) ≤ δ`. Capped; a capped heap's -/// guarantee misses the target. -#[cfg(test)] -fn distinct_heap(eps: f64, delta: f64) -> u32 { - if !(eps.is_finite() && eps > 0.0 && delta.is_finite() && delta > 0.0) { - return CARD_CAP; - } - let meets = |k: u32| distinct_chebyshev(k, eps) + incomplete_top_layer_bound(k) <= delta; - let mut k = saturating_ceil( - DISTINCT_VARIANCE / (delta * eps * eps), - DISTINCT_MIN_HEAP, - CARD_CAP, - ); - while !meets(k) && k < CARD_CAP { - k += 1; - } - k -} - /// The statistic a UnivMon distinct count over `source` leaves its /// top-layer failure probability as. #[allow(dead_code)] // Read again in #1207 PR 4, with θ from `LogicalProperties::parameters`. @@ -319,42 +227,12 @@ pub(crate) fn distinct_guarantee( )) } -/// Size a UnivMon for one readout's `(eps, delta)`: -/// - L2: the smallest rows and columns meeting the target ([`l2_shape`]), -/// one layer (L2 reads only layer 0) and a one-key heap; -/// - distinct count: the smallest heap meeting it ([`distinct_heap`]) and -/// the most layers, since the layers the top layer needs depend on the -/// source's distinct bound, which plan selection binds. The bound holds -/// whatever the Count Sketch keeps in the heaps, so each layer's is one -/// counter; -/// - total and entropy: the baseline shape (the total is exact; entropy -/// has no certified bound). -#[cfg(test)] -pub(super) fn size_params(intent: &AggIntent, eps: f64, delta: f64) -> SketchParams { - match intent { - AggIntent::FrequencyL2 { .. } => { - let (sketch_rows, sketch_cols) = l2_shape(eps, delta); - SketchParams::UnivMon { - heap_size: 1, - sketch_rows, - sketch_cols, - layers: 1, - } - } - AggIntent::Cardinality { .. } => SketchParams::UnivMon { - heap_size: distinct_heap(eps, delta), - sketch_rows: 1, - sketch_cols: 1, - layers: MAX_LAYERS, - }, - _ => BASELINE, - } -} - #[cfg(test)] mod tests { use super::*; + use crate::guarantee::sizing_oracle::{size_params, UNIVMON_BASELINE}; use asap_types::ir::operator::agg_intent::default_cardinality; + use asap_types::ir::operator::AggIntent; fn l2_intent() -> AggIntent { AggIntent::FrequencyL2 { col: None } @@ -406,7 +284,7 @@ mod tests { #[test] fn l2_shape_is_the_smallest_meeting_its_target() { for (eps, delta) in TARGETS { - let params = size_params(&l2_intent(), eps, delta); + let params = size_params(SketchAlgorithm::UnivMon, &l2_intent(), eps, delta); let guarantee = l2(¶ms).expect("an L2 guarantee"); assert_eq!(guarantee.spec.accuracy_metric, AccuracyMetric::Relative); assert!( @@ -457,7 +335,7 @@ mod tests { assert!(l2(&univmon(1, 7, 1 << 16, 1)).is_some()); assert!(l2(&univmon(1, 5, 1024, 20)).is_none()); for (eps, delta) in [(0.001, 1e-6), (1e-5, 0.01), (0.01, 1e-12)] { - let params = size_params(&l2_intent(), eps, delta); + let params = size_params(SketchAlgorithm::UnivMon, &l2_intent(), eps, delta); let SketchParams::UnivMon { sketch_rows, sketch_cols, @@ -494,7 +372,7 @@ mod tests { #[test] fn distinct_heap_is_the_smallest_meeting_its_target() { for (eps, delta) in TARGETS { - let params = size_params(&default_cardinality(), eps, delta); + let params = size_params(SketchAlgorithm::UnivMon, &default_cardinality(), eps, delta); let bind = |params: &SketchParams, max_distinct| { let guarantee = distinct_guarantee(params, delta, "m").expect("a distinct guarantee"); @@ -520,22 +398,12 @@ mod tests { } } - /// Example 2's Q1 (ε = 0.02, δ = 0.01) needs a heap of 337,500 keys, - /// `⌈1.35/(δ ε²)⌉`: the top layer's term is negligible at that heap. - /// At (0.5, 0.5) it is not: 1.35/(12 · 0.25) + (e/4)^6 > 0.5, while 13 - /// keys give 0.415 + 0.081. - #[test] - fn distinct_heap_for_example2_q1() { - assert_eq!(distinct_heap(0.02, 0.01), 337_500); - assert_eq!(distinct_heap(0.5, 0.5), 13); - } - /// Without the source's bound the failure probability stays unknown /// and no target is met; a bound the pyramid is too shallow for gives /// probability 1. #[test] fn distinct_guarantee_needs_the_source_bound_and_enough_layers() { - let params = size_params(&default_cardinality(), 0.05, 0.01); + let params = size_params(SketchAlgorithm::UnivMon, &default_cardinality(), 0.05, 0.01); let guarantee = distinct_guarantee(¶ms, 0.01, "m").unwrap(); assert_eq!(guarantee.spec.failure_probability.evaluate(), None); assert!(!meets(&guarantee, 0.05, Some(0.01))); @@ -563,7 +431,7 @@ mod tests { assert!(distinct_guarantee(&univmon(7, 1, 1, 19), 0.5, "m").is_none()); assert!(distinct_guarantee(&univmon(8, 1, 1, 20), 0.5, "m").is_none()); assert!(distinct_guarantee(&univmon(8, 1, 1, 19), 0.5, "m").is_some()); - let sized = size_params(&default_cardinality(), 0.05, 0.01); + let sized = size_params(SketchAlgorithm::UnivMon, &default_cardinality(), 0.05, 0.01); assert!(guarantee( &SketchAlgorithm::UnivMon, &sized, @@ -591,7 +459,7 @@ mod tests { /// The total stays exact; entropy stays uncertified. #[test] fn total_is_exact_and_entropy_uncertified() { - let params = size_params(&default_cardinality(), 0.05, 0.01); + let params = size_params(SketchAlgorithm::UnivMon, &default_cardinality(), 0.05, 0.01); let total = guarantee( &SketchAlgorithm::UnivMon, ¶ms, @@ -604,7 +472,7 @@ mod tests { assert!(total.is_exact()); assert!(guarantee( &SketchAlgorithm::UnivMon, - &BASELINE, + &UNIVMON_BASELINE, &SketchStatistic::FrequencyEntropy ) .is_none()); diff --git a/crates/accuracy/src/lib.rs b/crates/accuracy/src/lib.rs index 32ee13bd5..13be59fc7 100644 --- a/crates/accuracy/src/lib.rs +++ b/crates/accuracy/src/lib.rs @@ -28,8 +28,6 @@ pub mod propagation; mod propagation_stats; mod requirements; pub mod sizing; -#[cfg(feature = "test-support")] -pub mod test_support; pub use budget::per_input_target; pub use error_propagation::{error_propagation, ErrorPropagation}; diff --git a/crates/accuracy/src/propagation.rs b/crates/accuracy/src/propagation.rs index 41fd07d4a..6ed6ad9e7 100644 --- a/crates/accuracy/src/propagation.rs +++ b/crates/accuracy/src/propagation.rs @@ -21,8 +21,8 @@ use asap_types::ir::{ SchemaDerivationError, }; use asap_types::summary_type::{ - ExactKind, MergedError, NonNegativeWeightProof, SketchAlgorithm, SketchStatistic, - SummaryInputExpr, SummaryTypeCapability, SummaryUpdate, WeightDomain, + raw_data_samples_of_metric, ExactKind, MergedError, NonNegativeWeightProof, SketchAlgorithm, + SketchStatistic, SummaryInputExpr, SummaryTypeCapability, SummaryUpdate, WeightDomain, }; use crate::composition::{ @@ -36,32 +36,6 @@ use crate::PropagationStats; /// A rebuilt node per original node, keyed by the original's address. type NodeToRewrittenNodeCache = HashMap<*const OperatorNode, Rc>; -/// The metric whose raw data samples, or plain sums of them, are every value -/// `node` outputs, or `None`. Only a time-series scan, a time range over it, -/// an `offset`-only time shift (it moves the window, not the samples) and a -/// plain `sum` keep that; any other operator (rate and arithmetic included) -/// ends it. The metric's type is not read here: whether its -/// samples are non-negative is plan selection's question -/// ([`WeightDomain::RawDataSamplesOfMetric`]). -pub fn raw_data_samples_of_metric(node: &OperatorNode) -> Option { - match node.non_asap()? { - NonASAPOp::Scan { - source: Source::TimeSeries { metric }, - .. - } => Some(metric.clone()), - NonASAPOp::TimeRange { child, .. } => raw_data_samples_of_metric(child), - NonASAPOp::TimeShift { shift, child } if shift.at.is_none() => { - raw_data_samples_of_metric(child) - } - NonASAPOp::Aggregate { - measures, child, .. - } if matches!(measures.as_slice(), [AggIntent::Sum { col: None }]) => { - raw_data_samples_of_metric(child) - } - _ => None, - } -} - /// The approximate inputs a query's value composes: every sketch summary /// state reachable from `root`, each once, when the value carries a /// guarantee that is not exact ([`root_guarantee`]), including compositions @@ -642,7 +616,7 @@ pub(crate) fn fold_stats( /// from its tumbling windows: it is one of them, or between two of them, so it /// shares their sign. Anything else (rate, arithmetic, other /// functions) ends it. Only the sign of the values is read from it. -pub(crate) fn estimates_raw_data_samples_of(node: &OperatorNode) -> Option { +pub(crate) fn estimates_raw_data_samples_of(node: &Rc) -> Option { match &node.operator { Operator::NonASAP(NonASAPOp::TimeRange { child, .. }) => { estimates_raw_data_samples_of(child) @@ -1505,7 +1479,7 @@ fn interpolation_guarantee( family: &FieldDataType, update: &SummaryUpdate, query: &SketchStatistic, - input: &OperatorNode, + input: &Rc, mut guarantee: AccuracyGuarantee, ) -> Option { let interpolates = matches!(family, FieldDataType::Sketch(SketchAlgorithm::DDSketch)) @@ -1600,3 +1574,42 @@ pub fn pinned_column(conjunct: &ScalarExpr) -> Option { _ => None, } } + +#[cfg(test)] +mod tests { + use super::*; + use asap_types::summary_type::{NonNegativeWeightProof, SketchAlgorithm, SummaryInputExpr}; + + /// A Count-Min estimate has a bound only over weights proven + /// non-negative: an open requirement (`RawDataSamplesOfMetric`) is not a proof. + #[test] + fn count_min_estimate_has_no_bound_over_an_open_requirement() { + let summary_type = FieldDataType::Sketch(SketchAlgorithm::Cms); + let query = SketchStatistic::PointCount { + key: ColumnRef::SampleValue, + value: None, + }; + let with = |weight_domain| SummaryUpdate { + item: Some(SummaryInputExpr::Column(ColumnRef::SampleValue)), + weight: SummaryInputExpr::Column(ColumnRef::SampleValue), + weight_domain, + }; + assert!(!estimate_has_bound( + &summary_type, + &with(WeightDomain::RawDataSamplesOfMetric { metric: "m".into() }), + &query + )); + assert!(!estimate_has_bound( + &summary_type, + &with(WeightDomain::UnknownOrSigned), + &query + )); + assert!(estimate_has_bound( + &summary_type, + &with(WeightDomain::NonNegative { + proof: NonNegativeWeightProof::CounterRawDataSamples + }), + &query + )); + } +} diff --git a/crates/accuracy/src/sizing.rs b/crates/accuracy/src/sizing.rs index ddb42ffea..a79d8b5c2 100644 --- a/crates/accuracy/src/sizing.rs +++ b/crates/accuracy/src/sizing.rs @@ -1,6 +1,6 @@ -//! The statistic a summary is read for. (Today's sizing for an `(ε, δ)` is -//! test-only, `estimators::size_params`: the predefined lists are checked -//! against it.) +//! The statistic a summary is read for. (The predefined parameter lists +//! are checked against the closed-form sizing for an `(ε, δ)` in +//! `guarantee::sizing_oracle`, which is test-only.) use asap_types::ir::operator::AggIntent; use asap_types::ir::scalar::ColumnRef; @@ -22,36 +22,3 @@ pub fn sketch_statistic(intent: &AggIntent) -> Option { _ => return None, }) } - -#[cfg(test)] -mod tests { - use super::*; - use asap_types::summary_type::{SketchAlgorithm, SketchParams}; - - /// CMS width is `⌈e/ε⌉` and depth `⌈ln(1/δ)⌉`. - #[test] - fn epsilon_delta_sizes_cms_depth() { - let intent = AggIntent::Count; - assert_eq!( - crate::guarantee::size_params(SketchAlgorithm::Cms, &intent, 0.001, 0.001), - SketchParams::Cms { - width: 2719, - depth: 7 - } // ⌈e/0.001⌉, ⌈ln 1000⌉ - ); - assert_eq!( - crate::guarantee::size_params(SketchAlgorithm::Cms, &intent, 0.001, 0.01), - SketchParams::Cms { - width: 2719, - depth: 5 - } - ); - assert_eq!( - crate::guarantee::size_params(SketchAlgorithm::Cms, &intent, 0.01, 0.01), - SketchParams::Cms { - width: 272, - depth: 5 - } - ); - } -} diff --git a/crates/accuracy/src/test_support.rs b/crates/accuracy/src/test_support.rs deleted file mode 100644 index bb1ba7986..000000000 --- a/crates/accuracy/src/test_support.rs +++ /dev/null @@ -1,101 +0,0 @@ -//! Helpers that only other crates' tests call, exposed under the -//! `test-support` feature so the normal public API stays as narrow as its -//! production users need. Each forwards to the crate-private function or -//! constant of the same name. -use std::rc::Rc; - -use asap_types::accuracy::AccuracyGuarantee; -use asap_types::ir::operator::arguments::Reduction; -use asap_types::ir::schema::FieldDataType; -use asap_types::ir::{OperatorNode, ScalarExpr}; -use asap_types::summary_type::{SketchStatistic, SummaryUpdate}; - -use crate::composition::StreamNorm; -use crate::propagation; -pub use crate::propagation_stats::PropagationStats; - -/// [`propagation::composed_guarantee`]. -pub fn composed_guarantee(node: &OperatorNode) -> Option { - propagation::composed_guarantee(node) -} - -/// `propagation::scalar_guarantee`. -pub fn scalar_guarantee( - expr: &ScalarExpr, - column: &dyn Fn(usize) -> Option, -) -> Option { - propagation::scalar_guarantee(expr, column) -} - -/// `propagation::stream_norm`. -pub fn stream_norm(node: &Rc) -> Option { - propagation::stream_norm(node) -} - -/// `propagation::fold_stats`. -pub fn fold_stats(reduction: &Reduction, input: &Rc) -> Option { - propagation::fold_stats(reduction, input) -} - -/// `propagation::estimates_raw_data_samples_of`. -pub fn estimates_raw_data_samples_of(node: &OperatorNode) -> Option { - propagation::estimates_raw_data_samples_of(node) -} - -/// `propagation::estimate_has_bound`. -pub fn estimate_has_bound( - family: &FieldDataType, - update: &SummaryUpdate, - query: &SketchStatistic, -) -> bool { - propagation::estimate_has_bound(family, update, query) -} - -/// `propagation::estimate_bound_over_raw_data_samples`. -pub fn estimate_bound_over_raw_data_samples( - family: &FieldDataType, - update: &SummaryUpdate, - query: &SketchStatistic, -) -> Option { - propagation::estimate_bound_over_raw_data_samples(family, update, query) -} - -/// `propagation::source_distinct_guarantee`. -pub fn source_distinct_guarantee( - family: &FieldDataType, - query: &SketchStatistic, - input: &Rc, -) -> Option { - propagation::source_distinct_guarantee(family, query, input) -} - -/// `crate::guarantee::cms::cms_depth`. -pub fn cms_depth(delta: f64) -> u32 { - crate::guarantee::cms::cms_depth(delta) -} - -/// `crate::guarantee::kll::kll_rank_error_99`. -pub fn kll_rank_error_99(k: u32) -> f64 { - crate::guarantee::kll::kll_rank_error_99(k) -} - -/// `crate::composition::QUOTIENT_OPERAND_DOMAINS`. -pub const QUOTIENT_OPERAND_DOMAINS: &str = crate::composition::QUOTIENT_OPERAND_DOMAINS; - -/// `crate::composition::STREAM_ROW_COUNT`. -pub const STREAM_ROW_COUNT: &str = crate::composition::STREAM_ROW_COUNT; - -/// `crate::composition::source_norm_statistic`. -pub fn source_norm_statistic(norm: &str, source: &str) -> String { - crate::composition::source_norm_statistic(norm, source) -} - -/// `crate::composition::raw_data_samples_sign_statistic`. -pub fn raw_data_samples_sign_statistic(metric: &str) -> String { - crate::composition::raw_data_samples_sign_statistic(metric) -} - -/// `stats.sign_statistic` (see [`PropagationStats`]). -pub fn sign_statistic(stats: &PropagationStats) -> Option<&str> { - stats.sign_statistic.as_deref() -} diff --git a/crates/devtools/Cargo.toml b/crates/devtools/Cargo.toml index 1e6c69df1..80079502b 100644 --- a/crates/devtools/Cargo.toml +++ b/crates/devtools/Cargo.toml @@ -37,8 +37,6 @@ tokio = { version = "1", features = ["rt", "macros", "rt-multi-thread"] } [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } -# Pass 1's target list (`per_computation_candidates`) for the tests. -asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates", features = ["test-support"] } [[test]] diff --git a/crates/devtools/src/bin/asap_planner.rs b/crates/devtools/src/bin/asap_planner.rs index 7ddbe3ba4..adc4dc5ab 100644 --- a/crates/devtools/src/bin/asap_planner.rs +++ b/crates/devtools/src/bin/asap_planner.rs @@ -80,7 +80,7 @@ // Stage 2 implements). Each // step lists its groups (`id`, `label`, `children`, `parents`, // `queries`, `roots_of`, `node`) and their candidates (`index`, -// `implements`, `children`, `origin`, `accuracy_budget_parts`, `added` +// `implements`, `children`, `origin`, `added` // (not in the group at the step before), `label`, `node`, // `group_of_node`). With `stage3`, `selected_choice` maps each group the // plan uses to its candidate's index, or is null with diff --git a/crates/devtools/src/candidate_labels.rs b/crates/devtools/src/candidate_labels.rs index 8372d36ae..2b5e06d3b 100644 --- a/crates/devtools/src/candidate_labels.rs +++ b/crates/devtools/src/candidate_labels.rs @@ -6,30 +6,6 @@ use serde_json::Value; -use asap_types::stages::HowToComputeAggregateMeasure; -use asap_types::summary_type::SketchAlgorithm; - -/// A Pass 1 per-computation candidate, e.g. "exact", "Sum acc" or "Kll". -pub fn computation_label(candidate: &HowToComputeAggregateMeasure) -> String { - match candidate { - HowToComputeAggregateMeasure::Exact => "exact".to_string(), - HowToComputeAggregateMeasure::ExactAccumulator(kinds) => { - let kinds: Vec = kinds.iter().map(|kind| format!("{kind:?}")).collect(); - format!("{} acc", kinds.join("/")) - } - HowToComputeAggregateMeasure::Summary(algorithm) => sketch_name(algorithm), - } -} - -/// A sketch algorithm's display name, e.g. "CMS+heap" or "Kll". -fn sketch_name(algorithm: &SketchAlgorithm) -> String { - match algorithm { - SketchAlgorithm::CmsWithHeap => "CMS+heap".to_string(), - SketchAlgorithm::CountSketchWithHeap => "CountSketch+heap".to_string(), - other => format!("{other:?}"), - } -} - /// One node's operator kind with its sketch family and parameters, its /// summary query, its time range and its tumbling-window layout, when it has them: e.g. /// `SummaryAgg Kll(k=200)`, `SummaryEstimate Quantile(q=0.5)`. diff --git a/crates/devtools/src/planning_stages.rs b/crates/devtools/src/planning_stages.rs index c31b3d1b4..b4ab56335 100644 --- a/crates/devtools/src/planning_stages.rs +++ b/crates/devtools/src/planning_stages.rs @@ -7,7 +7,7 @@ use asap_planner::{ run_planning, PlanSearchSettings, PlanningModels, PlanningReport, PlanningRun, SelectionError, }; use asap_stage0_memo::memo_of_queries; -use asap_stage1_pass1_per_computation_candidates::{pass1_memo, Pass1Error}; +use asap_stage1_pass1_per_computation_candidates::pass1_memo; use asap_stage1_pass2_reuse_candidates::generate_logical_asap_memo_candidates; use asap_stage2_physical_optimization::generate_physical_asap_memo_candidates; use asap_stage3_plan_selection::select_plan; @@ -246,23 +246,14 @@ pub fn run_stages_until( .deployment_capabilities .supported_summaries .as_deref(), - ); + ) // As `run_planning`: a query Pass 1 cannot plan is reported before // contradictory deployment capabilities. - if let Err(Pass1Error::PerComputation(error)) = &pass1 { - return Err(PlanningStagesError::Pass1(error.to_string())); - } + .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); } - let pass1 = match pass1 { - Ok(pass1) => pass1, - Err(error) => { - run.selection = Err(SelectionError::LogicalASAPCandidates(error.to_string())); - return Ok(stages); - } - }; run.pass1_memo = Some(pass1.clone()); if until == RunUntil::Pass1 { return Ok(stages); diff --git a/crates/devtools/tests/asap_planner.rs b/crates/devtools/tests/asap_planner.rs index eb2623b54..8f5a04519 100644 --- a/crates/devtools/tests/asap_planner.rs +++ b/crates/devtools/tests/asap_planner.rs @@ -889,10 +889,9 @@ 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: no DDSketch candidate is offered, and Stage 1's -/// `pruned_candidates` says why. Without raw data, a plan is still selected -/// with guarantees enforced, from materialized views. A deployment with an -/// unknown field is refused. +/// results retained: no DDSketch candidate is offered. Without raw data, a +/// plan is still selected with guarantees enforced, from materialized +/// views. A deployment with an unknown field is refused. #[test] fn deployment_capabilities_flag_sets_the_capabilities_and_shows_them() { let with_capabilities = |capabilities: &str, extra: &[&str]| { @@ -931,12 +930,6 @@ fn deployment_capabilities_flag_sets_the_capabilities_and_shows_them() { "query_time_results_retained": true, }) ); - // Pass 1 lists why DDSketch is gone. - assert_eq!( - pass1_pruned(&kll_kept), - [("DDSketch".into(), "UnsupportedByDeployment".into())] - ); - assert!(pass1_pruned(&default).is_empty()); assert!(selects_a_plan(&kll_kept["stage3_plan_selection"])); let physical = kll_kept["stage2_physical_asap_optimization"]["candidates"] .as_array() diff --git a/crates/executor/Cargo.toml b/crates/executor/Cargo.toml index 7661ad112..e3706488f 100644 --- a/crates/executor/Cargo.toml +++ b/crates/executor/Cargo.toml @@ -27,8 +27,6 @@ test-support = ["planner-types/test-support"] [dev-dependencies] asap-executor = { path = ".", features = ["test-support"] } rmp-serde = "1" -asap-stage0-memo = { path = "../stage0-memo" } -asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates", features = ["test-support"] } # The planning stages through the facade (a dev-dependency cycle, for # integration tests only). asap-planner = { path = "../planner" } diff --git a/crates/integration-tests/Cargo.toml b/crates/integration-tests/Cargo.toml index dbe28ea89..49d278e7b 100644 --- a/crates/integration-tests/Cargo.toml +++ b/crates/integration-tests/Cargo.toml @@ -10,7 +10,7 @@ asap-types = { path = "../types", features = ["test-support"] } asap-frontend-promql = { path = "../frontend-promql" } asap-frontend-sql = { path = "../frontend-sql" } asap-stage0-memo = { path = "../stage0-memo" } -asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates", features = ["test-support"] } +asap-stage1-pass1-per-computation-candidates = { path = "../stage1-pass1-per-computation-candidates" } asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } asap-accuracy = { path = "../accuracy" } asap-cost = { path = "../cost" } @@ -22,7 +22,6 @@ asap-devtools = { path = "../devtools" } [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } -asap-accuracy = { path = "../accuracy", features = ["test-support"] } asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } asap-devtools = { path = "../devtools" } # The tests plan PromQL and SQL workloads through the facade. diff --git a/crates/integration-tests/tests/main.rs b/crates/integration-tests/tests/main.rs index fa844281e..bc74bcd3d 100644 --- a/crates/integration-tests/tests/main.rs +++ b/crates/integration-tests/tests/main.rs @@ -19,7 +19,8 @@ mod materialized_views; mod nested; mod operator_design_examples; mod operator_sharing; -mod per_computation_candidates_sql; +mod pass1_candidates; +mod pass1_candidates_sql; mod per_series_exact_execution; mod production_rollup_workloads; mod promql_to_post_asap; diff --git a/crates/integration-tests/tests/pass1_candidates.rs b/crates/integration-tests/tests/pass1_candidates.rs new file mode 100644 index 000000000..9e4c9930d --- /dev/null +++ b/crates/integration-tests/tests/pass1_candidates.rs @@ -0,0 +1,523 @@ +//! Frontends → Pass 1's memo: every candidate Pass 1 adds outputs its +//! group's schema (`Memo::add_candidate` checks it), so every way to compute +//! a query keeps its output columns (names, types and nullability). + +use asap_frontend_sql::{lower_sql, SqlCatalog}; +use asap_stage1_pass1_per_computation_candidates::pass1_memo; +use asap_types::accuracy::AccuracyTarget; +use asap_types::ir::operator::AggIntent; +use asap_types::ir::scalar::{ColumnRef, CompareOpKind, ScalarValue}; +use asap_types::ir::schema::FieldDataType; +use asap_types::ir::schema::{DataType, Field, Schema}; +use asap_types::ir::{ASAPOp, NonASAPOp, Operator, QueryRoot, ScalarExpr}; +use asap_types::stages::{Memo, MemoGroupId}; +use asap_types::summary_type::{SketchAlgorithm, SummaryInputExpr, SummaryUpdate}; +use asap_types::workload::{ + BatchEntry, DataWorkload, DurationMs, PlanningWorkload, Query, QueryLanguage, + QueryRequirements, QueryWorkload, +}; + +fn accuracy() -> AccuracyTarget { + AccuracyTarget::max_error(0.01).failure_probability(0.01) +} + +async fn sql(query: &str) -> QueryRoot { + let catalog = SqlCatalog::new().with_table( + "flows", + Schema::new(vec![ + Field::plain("src", DataType::Utf8, false), + Field::plain("dst", DataType::Utf8, false), + Field::plain("bytes", DataType::Float64, false), + ]), + ); + let root = lower_sql(query, &catalog) + .await + .unwrap_or_else(|e| panic!("lower failed for {query:?}: {e}")); + QueryRoot::Operator(root) +} + +fn promql(query: &str) -> QueryRoot { + let workload = PlanningWorkload { + query_workload: QueryWorkload { + language: QueryLanguage::PromQL, + query_batch: Some(vec![BatchEntry { + query: Query(query.into()), + requirements: QueryRequirements { + accuracy: accuracy(), + ..Default::default() + }, + predictability: Default::default(), + invocations: 1, + execute_at: None, + range_evaluation: None, + }]), + repeating_queries: None, + }, + data_workload: Some(DataWorkload::sampled_every( + asap_frontend_promql::promql_metric_names(query).unwrap_or_default(), + DurationMs(1000), + )), + }; + // As the planner does before Stage 0 (`Stage1ToStage3Pass`): each + // series' identity is realized as a column. + match asap_frontend_promql::lower_promql_query_workload(&workload) + .unwrap_or_else(|e| panic!("lower failed for {query:?}: {e}")) + .remove(0) + { + QueryRoot::Operator(node) => QueryRoot::Operator( + asap_types::ir::schema::series_identity::with_promql_series_identity(&node) + .unwrap_or(node), + ), + scalar => scalar, + } +} + +/// Stage 0's memo of the one query `root`, without an accuracy target. +fn stage0(root: QueryRoot) -> Memo { + asap_stage0_memo::memo_of_queries(&[root], &[None], &DataWorkload::default()).unwrap() +} + +/// Pass 1's memo of the one query `root`. +fn pass1(root: QueryRoot) -> Memo { + pass1_memo(stage0(root), None).unwrap() +} + +/// The one `Aggregate` group of `memo`. +fn root_group(memo: &Memo) -> MemoGroupId { + let [group] = aggregate_groups(memo)[..] else { + panic!("one aggregate group expected") + }; + group +} + +/// Pass 1 over `root`; returns how many candidates its aggregate groups +/// 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}")); + aggregate_groups(&memo) + .iter() + .map(|group| memo.groups()[group.0 as usize].candidates.len()) + .sum() +} + +/// The groups of `memo` whose expression is an `Aggregate`. +fn aggregate_groups(memo: &Memo) -> Vec { + memo.groups() + .iter() + .enumerate() + .filter(|(_, group)| { + matches!( + group.expression, + Operator::NonASAP(NonASAPOp::Aggregate { .. }) + ) + }) + .map(|(index, _)| MemoGroupId(index as u32)) + .collect() +} + +#[tokio::test] +async fn sql_candidates_output_the_query_columns() { + for query in [ + "SELECT src, count(*) FROM flows GROUP BY src HAVING src = 'a'", + "SELECT src, count(*) FROM flows GROUP BY src HAVING count(*) > 10", + "SELECT src, avg(bytes), count(*), approx_distinct(dst) FROM flows GROUP BY src", + "SELECT count(*) FILTER (WHERE bytes > 10), approx_percentile_cont(bytes, 0.99) FROM flows", + "SELECT avg(bytes) FROM flows", + "SELECT sum(flows.bytes) FROM flows", + "SELECT src, approx_percentile_cont(bytes, 0.99) FILTER (WHERE bytes > 10) FROM flows GROUP BY src", + "SELECT approx_percentile_cont(bytes, 0.99) FILTER (WHERE bytes > 10) FROM flows", + ] { + assert!(candidates_of_aggregates(query, sql(query).await) > 1, "{query}"); + } +} + +#[test] +fn promql_candidates_output_the_query_columns() { + for query in [ + "avg by (job) (m)", + "avg_over_time(m[5m])", + "quantile(0.99, m) - quantile(0.5, m)", + "scalar(quantile(0.99, m)) - scalar(quantile(0.5, m))", + "topk by (job) (10, sum_over_time(m[1m]))", + "topk(3, sum by (job) (rate(m[5m])))", + "count by (job) (m)", + "count_over_time(m[5m])", + "quantile_over_time(0.99, m[5m])", + ] { + assert!( + candidates_of_aggregates(query, promql(query)) > 1, + "{query}" + ); + } +} + +/// The algorithm and update of every sketch state group of Pass 1's memo +/// of `root`. +fn sketch_builds(root: QueryRoot) -> Vec<(SketchAlgorithm, SummaryUpdate)> { + pass1(root) + .groups() + .iter() + .filter_map(|group| match &group.expression { + Operator::ASAP(ASAPOp::SummaryAgg { + summary_type: FieldDataType::Sketch(kind), + input, + .. + }) => Some((*kind, input.clone())), + _ => None, + }) + .collect() +} + +/// A PromQL top-k over per-series sums offers both heap algorithms, and a +/// count offers Count-Min. +#[test] +fn topk_offers_both_heap_algorithms() { + let topk = sketch_builds(promql("topk by (job) (10, sum_over_time(m[1m]))")); + let algorithms: Vec<_> = topk.iter().map(|(kind, _)| *kind).collect(); + assert_eq!( + algorithms, + [ + SketchAlgorithm::CmsWithHeap, + SketchAlgorithm::CountSketchWithHeap + ] + ); + let count = sketch_builds(promql("count by (job) (m)")); + assert!(count.iter().any(|(kind, _)| *kind == SketchAlgorithm::Cms)); +} + +/// Top-K over a grouped sum is a whole-expression heap: it absorbs the +/// sum and ranks its group keys, read from the rows the sum reads. +#[test] +fn topk_over_an_aggregate_ranks_its_labels() { + let builds = sketch_builds(promql("topk(3, sum by (job) (rate(m[5m])))")); + assert_eq!(builds.len(), 2); + for (_, update) in &builds { + assert_eq!( + update.item, + Some(SummaryInputExpr::Column(ColumnRef::Named("job".into()))) + ); + } +} + +/// A subquery inside a measure filter is an input group of the filtered +/// state: the outer count's state reads the inner quantile's group, which +/// has its own candidates (exact and the quantile sketches' readouts). +#[tokio::test] +async fn subquery_in_a_measure_filter_is_an_input_group_of_the_state() { + let query = "SELECT src, count(*) FILTER (WHERE bytes > (SELECT approx_percentile_cont(bytes, 0.5) FROM flows)) \ + FROM flows GROUP BY src"; + let memo = pass1(sql(query).await); + let subqueries: Vec = memo + .groups() + .iter() + .filter_map(|group| match &group.expression { + Operator::ASAP(ASAPOp::SummaryAgg { + filter: Some(filter), + .. + }) => Some( + filter + .0 + .operator_refs() + .into_iter() + .copied() + .collect::>(), + ), + _ => None, + }) + .flatten() + .collect(); + assert!(!subqueries.is_empty()); + // The subquery reads the inner quantile's aggregate group. + for subquery in subqueries { + let below = memo.groups()[subquery.0 as usize].expression.children(); + assert!(below.iter().any(|group| { + matches!( + memo.groups()[group.0 as usize].expression, + Operator::NonASAP(NonASAPOp::Aggregate { .. }) + ) && memo.groups()[group.0 as usize].candidates.len() > 1 + })); + } +} + +/// The candidate of `memo`'s root group that is not its own expression +/// and computes `avg` from its `sum` and `count` states, and every group +/// below it. +fn avg_candidate_groups(memo: &Memo) -> Vec { + let root = root_group(memo); + let group = &memo.groups()[root.0 as usize]; + let mut below: Vec = Vec::new(); + let mut to_visit: Vec = group.candidates[1..] + .iter() + .flat_map(|candidate| { + candidate + .expression + .operator + .children() + .into_iter() + .copied() + }) + .collect(); + while let Some(next) = to_visit.pop() { + if !below.contains(&next) { + below.push(next); + to_visit.extend( + memo.groups()[next.0 as usize] + .expression + .children() + .into_iter() + .copied(), + ); + } + } + below +} + +fn avg_table() -> SqlCatalog { + SqlCatalog::new().with_table( + "t", + Schema::new(vec![ + Field::plain("k", DataType::Utf8, true), + Field::plain("ok", DataType::Bool, false), + Field::plain("value", DataType::Float64, false), + ]), + ) +} + +/// A filtered SQL `avg` is NULL where no row passes the filter: its quotient +/// is NULL when the count is 0. The runtime executes no filtered state yet, +/// so the shape is checked. +#[tokio::test] +async fn filtered_sql_avg_is_null_without_matching_rows() { + let catalog = avg_table(); + for query in [ + "SELECT k, avg(value) FILTER (WHERE value > 100) FROM t GROUP BY k", + "SELECT avg(value) FILTER (WHERE value > 100) FROM t", + ] { + let exact = lower_sql(query, &catalog).await.unwrap(); + let memo = pass1(QueryRoot::Operator(exact)); + let root = &memo.groups()[root_group(&memo).0 as usize]; + assert!( + root.group_properties.schema.fields.last().unwrap().nullable, + "{query}" + ); + assert!(root.candidates.len() > 1, "{query}"); + let null_when_no_count = memo.groups().iter().any(|group| { + let Operator::NonASAP(NonASAPOp::Project { cols, child, .. }) = &group.expression + else { + return false; + }; + let count = memo.groups()[child.0 as usize] + .group_properties + .schema + .fields + .len() + - 1; + matches!( + &cols.last().unwrap().expr, + ScalarExpr::Case { branches, .. } if matches!( + &branches[..], + [(ScalarExpr::Compare { left, op: CompareOpKind::Eq, right, .. }, + ScalarExpr::Literal(ScalarValue::Null))] + if **left == ScalarExpr::Column(count) + && **right == ScalarExpr::Literal(ScalarValue::Int64(0)) + ) + ) + }); + assert!(null_when_no_count, "{query}"); + } +} + +/// PromQL `avg` divides its `sum` and `count` vectors with a `BinaryOp`, +/// grouped, global and per series alike. Prometheus averages incrementally +/// once a sum overflows, so the division stands in only for finite operands +/// and quotient (`checked_finite_division`). +#[test] +fn promql_avg_divides_sum_and_count_vectors() { + for query in ["avg by (job) (m)", "avg(m)", "avg_over_time(m[5m])"] { + let memo = pass1(promql(query)); + let root = &memo.groups()[root_group(&memo).0 as usize]; + assert!(root.candidates.len() > 1, "{query}"); + let kinds: Vec<_> = avg_candidate_groups(&memo) + .iter() + .map(|group| memo.groups()[group.0 as usize].expression.kind_name()) + .collect(); + assert!(!kinds.contains(&"Join"), "{query}: {kinds:?}"); + let divisions: Vec = memo + .groups() + .iter() + .flat_map(|group| &group.candidates) + .filter_map(|candidate| match &candidate.expression.operator { + Operator::NonASAP(NonASAPOp::BinaryOp { operator, .. }) => { + Some(operator.checked_finite_division) + } + _ => None, + }) + .collect(); + assert!(!divisions.is_empty(), "{query}"); + assert!(divisions.iter().all(|checked| *checked), "{query}"); + } +} + +/// `count(*)` over `t(k, v)`, every column nullable, under a key-only +/// `HAVING`: no count accumulator or sketch can be built, so Pass 1 adds no +/// group, not even the `Filter` its candidates would push below the +/// aggregate. +#[tokio::test] +async fn an_unsupported_way_under_a_key_only_having_adds_no_group() { + let root = lower_sql( + "SELECT k, count(*) FROM t GROUP BY k HAVING k > 'a'", + &table(&[("v", true)]), + ) + .await + .unwrap(); + let stage0 = stage0(QueryRoot::Operator(root)); + let memo = pass1_memo(stage0.clone(), None).unwrap(); + assert_eq!(memo.groups().len(), stage0.groups().len()); + assert!(memo + .groups() + .iter() + .all(|group| !group.reached_by_queries().is_empty())); +} + +/// A multi-measure aggregate's `count(*)` is the same group as another +/// query's `count(*)` over the same rows: Pass 1 writes the measure's own +/// aggregate as the frontend writes one. +#[tokio::test] +async fn a_multi_measure_aggregates_part_is_the_equal_stage0_group() { + let roots = [ + sql("SELECT src, count(*), sum(bytes) FROM flows GROUP BY src").await, + sql("SELECT src, count(*) FROM flows GROUP BY src").await, + ]; + let stage0 = + asap_stage0_memo::memo_of_queries(&roots, &[None, None], &DataWorkload::default()).unwrap(); + let memo = pass1_memo(stage0, None).unwrap(); + let counts = memo + .groups() + .iter() + .filter(|group| { + matches!( + &group.expression, + Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) + if measures.as_slice() == [AggIntent::Count] + ) + }) + .count(); + assert_eq!(counts, 1); +} + +/// SQL `sum` of a subquery's `sum`, read through the subquery's renaming +/// `Project`: the outer sum's state also gets one exact sum over the raw +/// rows, a fused build listing the `Project` and the inner aggregate. +#[tokio::test] +async fn sql_sum_of_a_subquerys_sum_is_one_sum_over_the_rows() { + let memo = pass1( + sql("SELECT src, sum(s) FROM \ + (SELECT src, dst, sum(bytes) AS s FROM flows GROUP BY src, dst) x GROUP BY src") + .await, + ); + let fused: Vec<_> = memo + .groups() + .iter() + .flat_map(|group| &group.candidates) + .filter(|candidate| { + matches!( + candidate.expression.operator, + Operator::ASAP(ASAPOp::SummaryAgg { .. }) + ) && !candidate.fused_groups.is_empty() + }) + .collect(); + assert_eq!(fused.len(), 1); + assert_eq!(fused[0].fused_groups.len(), 2); +} + +/// `t(k Utf8 NULL, )` as a catalog. +fn table(columns: &[(&str, bool)]) -> SqlCatalog { + let mut fields = vec![Field::plain("k", DataType::Utf8, true)]; + fields.extend( + columns + .iter() + .map(|(name, nullable)| Field::plain(*name, DataType::Float64, *nullable)), + ); + SqlCatalog::new().with_table("t", Schema::new(fields)) +} + +/// Pass 1's memo of `query` over `catalog`. +async fn pass1_sql(catalog: &SqlCatalog, query: &str) -> Memo { + let root = lower_sql(query, catalog).await.unwrap(); + pass1(QueryRoot::Operator(root)) +} + +/// The update of every `count` state (exact or sketch) in `memo`. +fn count_updates(memo: &Memo) -> Vec { + memo.groups() + .iter() + .filter_map(|group| match &group.expression { + Operator::ASAP(ASAPOp::SummaryAgg { + summary_type, + input, + .. + }) if !matches!( + summary_type, + FieldDataType::ExactAggregate(asap_types::summary_type::ExactKind::Sum, _) + ) => + { + Some(input.clone()) + } + _ => None, + }) + .collect() +} + +/// Whether `update` reads only the column `name` of `t`. +fn reads_only(update: &SummaryUpdate, name: &str) -> bool { + let column = SummaryInputExpr::Column(ColumnRef::Named(name.into())); + match &update.item { + Some(item) => *item == column && update.weight == SummaryInputExpr::Constant(1.0), + None => update.weight == column, + } +} + +/// SQL `avg` as `sum` and `count` keeps an explicit output alias: its +/// candidate outputs the root group's schema, which names it. +#[tokio::test] +async fn sql_avg_keeps_its_explicit_output_name() { + let memo = pass1_sql(&avg_table(), "SELECT avg(value) AS avg_latency FROM t").await; + assert!(memo.groups()[root_group(&memo).0 as usize].candidates.len() > 1); + let QueryRoot::Operator(query_root) = &memo.queries()[0].root else { + panic!("operator root expected") + }; + let output = &memo.groups()[query_root.0 as usize].group_properties.schema; + assert_eq!(output.fields.last().unwrap().name, "avg_latency"); +} + +/// `count(*)` with no column known to be non-null (one nullable numeric +/// column, or several and none named `value`) gets no accumulator or +/// sketch: the root group keeps only its plain exact aggregate, not a count +/// of a nullable column. +#[tokio::test] +async fn sql_count_star_without_a_non_null_column_is_only_exact() { + for columns in [&[("v", true)][..], &[("a", true), ("b", true)][..]] { + let memo = pass1_sql(&table(columns), "SELECT k, count(*) FROM t GROUP BY k").await; + assert_eq!( + memo.groups()[root_group(&memo).0 as usize].candidates.len(), + 1, + "{columns:?}" + ); + assert!(count_updates(&memo).is_empty(), "{columns:?}"); + } +} + +/// `count(v)` of a nullable `v` updates on `v` under its `v IS NOT NULL` +/// filter: it counts the non-null values. The runtime executes no filtered +/// state yet, so the shape is checked. +#[tokio::test] +async fn sql_count_of_a_nullable_column_counts_its_values() { + let catalog = table(&[("v", true), ("n", false)]); + let memo = pass1_sql(&catalog, "SELECT k, count(v) FROM t GROUP BY k").await; + let updates = count_updates(&memo); + assert!(!updates.is_empty()); + for update in &updates { + assert!(reads_only(update, "v"), "{updates:?}"); + } +} diff --git a/crates/integration-tests/tests/pass1_candidates_sql.rs b/crates/integration-tests/tests/pass1_candidates_sql.rs new file mode 100644 index 000000000..17db96566 --- /dev/null +++ b/crates/integration-tests/tests/pass1_candidates_sql.rs @@ -0,0 +1,208 @@ +//! SQL → Pass 1 memo candidates: where each `HAVING` is applied, the +//! guarantees composed over estimates, and what a Top-K heap sketch ranks. + +use asap_frontend_sql::{lower_sql, SqlCatalog}; +use asap_stage1_pass1_per_computation_candidates::pass1_memo; +use asap_types::ir::scalar::ColumnRef; +use asap_types::ir::schema::FieldDataType; +use asap_types::ir::schema::{DataType, Field, Schema}; +use asap_types::ir::{ASAPOp, NonASAPOp, Operator, Predicate, QueryRoot, ScalarExpr}; +use asap_types::stages::Memo; +use asap_types::summary_type::{SketchAlgorithm, SummaryInputExpr}; + +/// Pass 1's memo of `sql` over `flows(src, bytes)`. +async fn pass1(sql: &str) -> Memo { + pass1_over( + vec![ + Field::plain("src", DataType::Utf8, false), + Field::plain("bytes", DataType::Float64, false), + ], + sql, + ) + .await +} + +/// Pass 1's memo of `sql` over `flows(fields)`. +async fn pass1_over(fields: Vec, sql: &str) -> Memo { + let catalog = SqlCatalog::new().with_table("flows", Schema::new(fields)); + let root = lower_sql(sql, &catalog) + .await + .unwrap_or_else(|e| panic!("lower failed for {sql:?}: {e}")); + let memo = asap_stage0_memo::memo_of_queries( + &[QueryRoot::Operator(root)], + &[None], + &Default::default(), + ) + .unwrap(); + pass1_memo(memo, None).unwrap_or_else(|e| panic!("Pass 1 failed for {sql:?}: {e}")) +} + +/// Whether some candidate applies a `HAVING` below the aggregate: a +/// `Filter` group over the aggregate's input, which a state build reads. +fn having_pushed_below(memo: &Memo) -> bool { + let groups = memo.groups(); + groups.iter().any(|group| { + let Operator::NonASAP(NonASAPOp::Aggregate { child, .. }) = &group.expression else { + return false; + }; + groups.iter().any(|filter| { + matches!(&filter.expression, Operator::NonASAP(NonASAPOp::Filter { child: input, .. }) if input == child) + }) + }) +} + +/// A key-only `HAVING` is pushed below the aggregate. +#[tokio::test] +async fn key_only_having_is_pushed_below() { + let memo = pass1("SELECT src, count(*) FROM flows GROUP BY src HAVING src = 'a'").await; + assert!(having_pushed_below(&memo)); +} + +/// A `HAVING` over an aggregate value stays above the output. +#[tokio::test] +async fn value_having_stays_above() { + let memo = pass1("SELECT src, count(*) FROM flows GROUP BY src HAVING count(*) > 10").await; + assert!(!having_pushed_below(&memo)); +} + +/// A global aggregate's `HAVING`, even a constant one, stays above the output. +#[tokio::test] +async fn global_constant_having_stays_above() { + let memo = pass1("SELECT count(*) FROM flows HAVING false").await; + assert!(!having_pushed_below(&memo)); +} + +/// A `HAVING` that reads a key and a value pushes its key conjunct below +/// the aggregate and keeps its value conjunct above: some candidate of the +/// `HAVING`'s `Filter` group filters by `count(*) > 10` alone. +#[tokio::test] +async fn mixed_having_pushes_its_key_conjunct_below() { + let memo = + pass1("SELECT src, count(*) FROM flows GROUP BY src HAVING src = 'a' AND count(*) > 10") + .await; + assert!(having_pushed_below(&memo)); + let (filter, value_conjunct) = memo + .groups() + .iter() + .find_map(|group| match &group.expression { + Operator::NonASAP(NonASAPOp::Filter { + pred: Predicate(ScalarExpr::BoolAnd(conjuncts)), + .. + }) => Some((group, conjuncts[1].clone())), + _ => None, + }) + .expect("the HAVING's Filter group"); + assert!(filter.candidates.iter().any(|candidate| matches!( + &candidate.expression.operator, + Operator::NonASAP(NonASAPOp::Filter { pred, .. }) if pred.0 == value_conjunct + ))); +} + +/// The item and weight columns of every heap sketch state group in Pass 1's +/// memo of `sql` over `flows(key: key_type, bytes)`. +async fn heap_updates(key: &str, key_type: DataType, sql: &str) -> Vec<(String, String)> { + heap_updates_over( + vec![ + Field::plain(key, key_type, false), + Field::plain("bytes", DataType::Float64, false), + ], + sql, + ) + .await +} + +/// [`heap_updates`] over `flows(fields)`. +async fn heap_updates_over(fields: Vec, sql: &str) -> Vec<(String, String)> { + let memo = pass1_over(fields, sql).await; + let name = |expr: &SummaryInputExpr| match expr { + SummaryInputExpr::Column(ColumnRef::Named(name)) => name.clone(), + // The ranked value when it is the child's one sample value. + SummaryInputExpr::Column(ColumnRef::SampleValue) => "".into(), + SummaryInputExpr::Tuple(items) => match items.as_slice() { + [SummaryInputExpr::Column(ColumnRef::Named(name))] => name.clone(), + other => panic!("one item column: {other:?}"), + }, + SummaryInputExpr::Constant(value) => value.to_string(), + other => panic!("a named column or constant: {other:?}"), + }; + memo.groups() + .iter() + .filter_map(|group| match &group.expression { + Operator::ASAP(ASAPOp::SummaryAgg { + summary_type: + FieldDataType::Sketch( + SketchAlgorithm::CmsWithHeap | SketchAlgorithm::CountSketchWithHeap, + ), + input, + .. + }) => Some((name(input.item.as_ref().unwrap()), name(&input.weight))), + _ => None, + }) + .collect() +} + +const COUNT_RANKED_TOPK: &str = + "SELECT KEY, count(*) FROM flows GROUP BY KEY ORDER BY count(*) DESC LIMIT 10"; + +/// An Int64 key is not mistaken for the ranked value: both heap sketches +/// are built over raw rows, keyed by the key with unit weight. +#[tokio::test] +async fn topk_heap_over_an_int64_key_counts_raw_rows() { + let updates = heap_updates( + "port", + DataType::Int64, + &COUNT_RANKED_TOPK.replace("KEY", "port"), + ) + .await; + assert_eq!(updates.len(), 2, "{updates:?}"); + assert!( + updates + .iter() + .all(|(item, weight)| item == "port" && weight == "1"), + "{updates:?}" + ); +} + +/// A key named `value` is not the ranked value: the heap sketches are +/// fed raw rows with unit weight. +#[tokio::test] +async fn topk_heap_over_a_key_named_value_counts_raw_rows() { + let updates = heap_updates( + "value", + DataType::Utf8, + &COUNT_RANKED_TOPK.replace("KEY", "value"), + ) + .await; + assert_eq!(updates.len(), 2, "{updates:?}"); + assert!( + updates + .iter() + .all(|(item, weight)| item == "value" && weight == "1"), + "{updates:?}" + ); +} + +/// SQL's per-group top-k idiom (`ROW_NUMBER() OVER (PARTITION BY city +/// ORDER BY COUNT(*) DESC) … WHERE rn <= 5`) is a heavy-hitter top-k, as +/// PromQL `topk by (city)` is: both heap sketches are offered, keyed by the +/// host and fed raw rows with unit weight. +#[tokio::test] +async fn rownumber_per_group_topk_offers_heap_sketches() { + let updates = heap_updates_over( + vec![ + Field::plain("city", DataType::Utf8, false), + Field::plain("host", DataType::Utf8, false), + ], + "SELECT city, host, c FROM (SELECT city, host, COUNT(*) AS c, ROW_NUMBER() OVER \ + (PARTITION BY city ORDER BY COUNT(*) DESC) AS rn FROM flows GROUP BY city, host) \ + WHERE rn <= 5", + ) + .await; + assert_eq!(updates.len(), 2, "{updates:?}"); + assert!( + updates + .iter() + .all(|(item, weight)| item == "host" && weight == "1"), + "{updates:?}" + ); +} diff --git a/crates/integration-tests/tests/per_computation_candidates_sql.rs b/crates/integration-tests/tests/per_computation_candidates_sql.rs deleted file mode 100644 index abaf44691..000000000 --- a/crates/integration-tests/tests/per_computation_candidates_sql.rs +++ /dev/null @@ -1,142 +0,0 @@ -//! SQL → Pass 1 per-computation candidates: where each `HAVING` is applied, -//! the guarantees composed over estimates, and what a Top-K heap sketch -//! ranks. - -use asap_frontend_sql::{lower_sql, SqlCatalog}; -use asap_stage1_pass1_per_computation_candidates::test_support::generate_per_computation_candidates; -use asap_types::accuracy::AccuracyTarget; -use asap_types::ir::schema::{DataType, Field, Schema}; -use asap_types::ir::QueryRoot; -use asap_types::stages::{ComputationTarget, HavingPlacement}; - -async fn targets(sql: &str) -> Vec { - let catalog = SqlCatalog::new().with_table( - "flows", - Schema::new(vec![ - Field::plain("src", DataType::Utf8, false), - Field::plain("bytes", DataType::Float64, false), - ]), - ); - let root = lower_sql(sql, &catalog) - .await - .unwrap_or_else(|e| panic!("lower failed for {sql:?}: {e}")); - generate_per_computation_candidates( - &asap_stage0_memo::memo_of_queries( - &[QueryRoot::Operator(root)], - &[None], - &Default::default(), - ) - .unwrap(), - ) - .unwrap() - .targets -} - -fn placements(targets: &[ComputationTarget]) -> Vec { - targets - .iter() - .flat_map(|target| target.having_filters.iter().map(|entry| entry.placement)) - .collect() -} - -#[tokio::test] -async fn key_only_having_is_pushed_below() { - let targets = targets("SELECT src, count(*) FROM flows GROUP BY src HAVING src = 'a'").await; - assert_eq!(placements(&targets), vec![HavingPlacement::BelowAggregate]); -} - -#[tokio::test] -async fn value_having_stays_above() { - let targets = - targets("SELECT src, count(*) FROM flows GROUP BY src HAVING count(*) > 10").await; - assert_eq!(placements(&targets), vec![HavingPlacement::AboveOutput]); -} - -#[tokio::test] -async fn global_constant_having_stays_above() { - let targets = targets("SELECT count(*) FROM flows HAVING false").await; - assert_eq!(placements(&targets), vec![HavingPlacement::AboveOutput]); -} - -#[tokio::test] -async fn mixed_key_and_value_having_stays_above() { - let targets = - targets("SELECT src, count(*) FROM flows GROUP BY src HAVING src = 'a' AND count(*) > 10") - .await; - assert_eq!(placements(&targets), vec![HavingPlacement::AboveOutput]); -} - -/// Whether `node` reads a quantile sketch (KLL or DDSketch) anywhere below it. -fn reads_quantile_sketch(node: &std::rc::Rc) -> bool { - use asap_types::summary_type::SketchAlgorithm; - asap_types::ir::OperatorNode::reachable(node) - .iter() - .any(|node| { - matches!( - node.asap(), - Some(asap_types::ir::ASAPOp::SummaryAgg { - summary_type: asap_types::ir::schema::FieldDataType::Sketch(kind), - .. - }) if matches!(kind, SketchAlgorithm::Kll | SketchAlgorithm::DDSketch) - ) - }) -} - -/// A measure filter or a grouping key that reads an approximate value -/// decides which rows count, or which group a row joins, by an estimate, so -/// an estimate near a threshold or a group boundary can change the result -/// arbitrarily: the output has no guarantee (#669), whether the measure -/// counts rows or folds the estimate itself. So does a count of the -/// estimates' distinct values, of non-null estimates, or a group key -/// computed from an estimate. -#[tokio::test] -async fn a_filter_or_group_key_over_an_estimate_has_no_guarantee() { - let catalog = SqlCatalog::new().with_table( - "flows", - Schema::new(vec![ - Field::plain("src", DataType::Utf8, false), - Field::plain("bytes", DataType::Float64, false), - ]), - ); - let accuracy = AccuracyTarget::max_error(0.01); - for sql in [ - "SELECT count(*) FILTER (WHERE p > 5) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s", - "SELECT max(p) FILTER (WHERE p < 100) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s", - "SELECT p, count(*) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s \ - GROUP BY p", - "SELECT p, max(p) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s \ - GROUP BY p", - "SELECT p, sum(p) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s \ - GROUP BY p", - "SELECT p > 5, count(*) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s \ - GROUP BY p > 5", - "SELECT count(DISTINCT p) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s", - "SELECT count(p) FROM \ - (SELECT src, approx_percentile_cont(bytes, 0.99) AS p FROM flows GROUP BY src) s", - ] { - let root = lower_sql(sql, &catalog) - .await - .unwrap_or_else(|e| panic!("lower failed for {sql:?}: {e}")); - // No guarantee meets the target, so Pass 1 prunes the sketch - // unless every output is accepted. - let candidates: Vec<_> = - asap_integration_tests::planning::logical_candidates_ignoring_guarantees( - root, - accuracy.clone(), - ) - .into_iter() - .filter(reads_quantile_sketch) - .collect(); - assert!(!candidates.is_empty(), "{sql}"); - for candidate in candidates { - assert_eq!(candidate.guarantee, None, "{sql}"); - } - } -} diff --git a/crates/planner/Cargo.toml b/crates/planner/Cargo.toml index 8a79dbcb9..bd9ded37b 100644 --- a/crates/planner/Cargo.toml +++ b/crates/planner/Cargo.toml @@ -37,7 +37,6 @@ thiserror = "2" [dev-dependencies] asap-stage3-plan-selection = { path = "../stage3-plan-selection" } asap-stage2-physical-optimization = { path = "../stage2-physical-optimization" } -asap-accuracy = { path = "../accuracy", features = ["test-support"] } # Tests read a plan's roots as IR (`PhysicalASAPDAG::query_roots`). asap-types = { path = "../types", features = ["test-support"] } # The SQL frontend plans through DataFusion, which is async; `e2e_plan` is diff --git a/crates/planner/src/run.rs b/crates/planner/src/run.rs index 7022ef25d..c18adcca6 100644 --- a/crates/planner/src/run.rs +++ b/crates/planner/src/run.rs @@ -8,9 +8,7 @@ use asap_stage0_memo::memo_of_queries; use std::rc::Rc; use std::time::Instant; -use asap_stage1_pass1_per_computation_candidates::{ - pass1_memo, Pass1Error, PerComputationCandidateError, -}; +use asap_stage1_pass1_per_computation_candidates::{pass1_memo, PerComputationCandidateError}; use asap_stage1_pass2_reuse_candidates::generate_logical_asap_memo_candidates; use asap_stage2_physical_optimization::generate_physical_asap_memo_candidates; use asap_stage3_plan_selection::{select_plan, ErrorSelectingPlan, Selection}; @@ -108,24 +106,20 @@ pub fn run_planning( }) .collect(); let initial = memo_of_queries(&roots, &accuracy_targets, data)?; - // Pass 1: the per-computation candidates the deployment can run. + // 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(), - ); - // A query Pass 1 cannot plan is an input error. - let pass1 = match pass1 { - Err(Pass1Error::PerComputation(error)) => return Err(error), - pass1 => pass1, - }; + )?; let mut report = PlanningReport { pass1_ms: elapsed_ms(started), ..PlanningReport::default() }; - let pass1_memo = pass1.as_ref().ok().filter(|_| settings.inspect).cloned(); + let pass1_memo = settings.inspect.then(|| pass1.clone()); let mut logical_asap_candidates = None; let mut physical_asap_candidates = None; let selection = (|| { @@ -133,8 +127,6 @@ pub fn run_planning( .deployment_capabilities .validate(data) .map_err(SelectionError::InvalidDeploymentCapabilities)?; - let pass1 = - pass1.map_err(|error| SelectionError::LogicalASAPCandidates(error.to_string()))?; // Pass 2: the reuse rules, readout requirements and logical edges. let started = Instant::now(); let logical = generate_logical_asap_memo_candidates(pass1, entries, models.evidence); diff --git a/crates/stage1-pass1-per-computation-candidates/Cargo.toml b/crates/stage1-pass1-per-computation-candidates/Cargo.toml index 0a4df4c1a..0c8e36180 100644 --- a/crates/stage1-pass1-per-computation-candidates/Cargo.toml +++ b/crates/stage1-pass1-per-computation-candidates/Cargo.toml @@ -13,10 +13,5 @@ asap-types = { path = "../types" } asap-accuracy = { path = "../accuracy" } thiserror = "2" -[features] -# The test helpers (`test_support`) other crates' tests share. -test-support = [] - [dev-dependencies] asap-types = { path = "../types", features = ["test-support"] } -asap-accuracy = { path = "../accuracy", features = ["test-support"] } diff --git a/crates/stage1-pass1-per-computation-candidates/src/candidates/measure_output.rs b/crates/stage1-pass1-per-computation-candidates/src/candidates/measure_output.rs new file mode 100644 index 000000000..a8e5e2689 --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/src/candidates/measure_output.rs @@ -0,0 +1,555 @@ +//! The operator that computes one measure by one way, and the groups it +//! reads, built pending ([`Pending`]): exact accumulators, summaries and +//! their readouts, `avg` from its `sum` and `count`, a heap's ranked rows, +//! and a multi-measure aggregate's measures joined on their group keys. + +use asap_types::ir::operator::arguments::{BinaryOpKind, JoinKind, Reduction}; +use asap_types::ir::operator::AggIntent; +use asap_types::ir::scalar::expr_ir::ArithmeticOpKind; +use asap_types::ir::scalar::{resolve_column_ref, ColumnRef, CompareOpKind, ScalarValue}; +use asap_types::ir::schema::{DataType, FieldDataType, Schema}; +use asap_types::ir::{ + ASAPOp, BinaryOperator, ExprSemantics, NonASAPOp, Operator, OperatorResultKind, Predicate, + ProjectItem, ScalarExpr, +}; +use asap_types::stages::{Memo, MemoGroupId}; +use asap_types::summary_type::{ExactKind, SummaryInputExpr}; + +use asap_accuracy::sizing::sketch_statistic; + +use super::pending::{add_candidate, commit_pending, Pending}; +use super::SingleMeasure; +use crate::computation_targets::HowToComputeAggregateMeasure; +use crate::summary_realization::{ + measure_input, summary_update, with_raw_data_samples_requirement, +}; +use crate::{schema, PerComputationCandidateError}; + +/// The operator that computes `measure` by `way` for +/// `result_group`: its value after its group keys, its column names not +/// yet the group's ([`add_output_candidate`] renames them). The groups it +/// reads are pushed onto `pending`; nothing is added to `memo`. +pub(super) fn measure_output( + memo: &Memo, + pending: &mut Pending, + measure: &SingleMeasure<'_>, + way: &HowToComputeAggregateMeasure, + result_group: MemoGroupId, +) -> Result, PerComputationCandidateError> { + Ok(match way { + HowToComputeAggregateMeasure::ExactAccumulator(kinds) if kinds.len() == 1 => { + let read = measure_input( + measure.intent, + memo, + measure.unfiltered_input, + measure.filter, + )?; + let build = accumulator_build(memo, kinds[0], measure.intent, measure, read)?; + Operator::ASAP(ASAPOp::FinalizeExactAccumulator { + child: pending.push(memo, build)?, + }) + } + HowToComputeAggregateMeasure::Summary(algorithm) => { + let summary_type = FieldDataType::Sketch(*algorithm); + let read = measure_input( + measure.intent, + memo, + measure.unfiltered_input, + measure.filter, + )?; + let update = with_raw_data_samples_requirement( + summary_update( + measure.intent, + &summary_type, + measure.reduction, + schema(memo, measure.unfiltered_input), + read, + )?, + measure.raw_data_samples_of, + ); + let build = Operator::ASAP(ASAPOp::SummaryAgg { + child: measure.input, + input: update, + summary_type, + reduction: measure.reduction.clone(), + filter: measure.filter.cloned(), + }); + summary_readout( + memo, + pending, + build, + measure.intent, + measure.reduction, + result_group, + )? + } + HowToComputeAggregateMeasure::ExactAccumulator(kinds) => { + let (AggIntent::Avg { col }, [ExactKind::Sum, ExactKind::Count]) = + (measure.intent, kinds.as_slice()) + else { + return Err(PerComputationCandidateError::Unsupported( + "several exact states other than avg's sum then count", + )); + }; + // The count counts the averaged column, as `avg` does: it is + // non-null (a nullable input prunes this candidate), so it counts + // the rows the sum reads. + let sum_intent = AggIntent::Sum { col: *col }; + let count_intent = AggIntent::Count; + let read = measure_input(&sum_intent, memo, measure.unfiltered_input, measure.filter)?; + let sum = accumulator_build(memo, ExactKind::Sum, &sum_intent, measure, read.clone())?; + let count = accumulator_build(memo, ExactKind::Count, &count_intent, measure, read)?; + let sum = pending.push(memo, sum)?; + let count = pending.push(memo, count)?; + let sum = pending.push( + memo, + Operator::ASAP(ASAPOp::FinalizeExactAccumulator { child: sum }), + )?; + let count = pending.push( + memo, + Operator::ASAP(ASAPOp::FinalizeExactAccumulator { child: count }), + )?; + if memo.groups()[measure.unfiltered_input.0 as usize] + .group_properties + .result_kind + == OperatorResultKind::Relation + { + return sql_avg( + memo, + pending, + measure.reduction, + measure.filter.is_some(), + sum, + count, + ); + } + // `avg` is Float64 whatever the summed type, as `Avg`'s output is, + // and a PromQL binary operator reads Float64 sample values. A + // grouped sum or count ends with its value, cast when not Float64 + // (a count is Int64). A per-series sum keeps the input's labels, + // so its value is the sample-value column; a per-series count is + // Float64. + let (sum, count) = match measure.reduction { + Reduction::Reduce(by) => ( + last_as_float64(memo, pending, by.len(), sum)?, + last_as_float64(memo, pending, by.len(), count)?, + ), + Reduction::PerEntity => { + let sum_schema = pending.schema(memo, sum); + let value = resolve_column_ref(&ColumnRef::SampleValue, sum_schema) + .ok() + .and_then(|column| sum_schema.fields.get(column)); + if value.map(|field| &field.dtype) + != Some(&FieldDataType::Plain(DataType::Float64)) + { + return Err(PerComputationCandidateError::Unsupported( + "non-Float64 per-series avg", + )); + } + (sum, count) + } + }; + Operator::NonASAP(NonASAPOp::BinaryOp { + operator: BinaryOperator { + checked_relative_division: false, + // PromQL's `avg` and `avg_over_time` switch to an + // incremental mean when the sum overflows, so the + // quotient stands in only when operands and result are + // finite; otherwise the original query runs. + checked_finite_division: true, + kind: BinaryOpKind::Arithmetic(ArithmeticOpKind::Div), + vector_match: None, + }, + return_bool: false, + lhs: sum, + rhs: count, + }) + } + }) +} + +/// The readout of `intent` from the summary state `build` computes, for +/// `result_group` (an aggregate of `intent` grouped by `reduction`): its +/// estimate, as a top-k's ranked rows for a top-k ([`ranked_as_topk`]). +/// The state and, for a top-k, the estimate are pushed onto `pending`. +pub(super) fn summary_readout( + memo: &Memo, + pending: &mut Pending, + build: Operator, + intent: &AggIntent, + reduction: &Reduction, + result_group: MemoGroupId, +) -> Result, PerComputationCandidateError> { + let query = sketch_statistic(intent).ok_or(PerComputationCandidateError::Unsupported( + "sketch evaluation", + ))?; + let state = pending.push(memo, build)?; + let estimate = Operator::ASAP(ASAPOp::SummaryEstimate { + summary_input: state, + query, + }); + let AggIntent::TopK { .. } = intent else { + return Ok(estimate); + }; + let estimate = pending.push(memo, estimate)?; + ranked_as_topk( + reduction, + schema(memo, result_group), + pending.schema(memo, estimate), + estimate, + ) +} + +/// The accumulator build of `kind` for `intent` over `measure`'s input, +/// filtered and grouped as `measure`. +pub(super) fn accumulator_build( + memo: &Memo, + kind: ExactKind, + intent: &AggIntent, + measure: &SingleMeasure<'_>, + read: SummaryInputExpr, +) -> Result, PerComputationCandidateError> { + let summary_type = FieldDataType::exact(kind); + Ok(Operator::ASAP(ASAPOp::SummaryAgg { + input: summary_update( + intent, + &summary_type, + measure.reduction, + schema(memo, measure.unfiltered_input), + read, + )?, + child: measure.input, + summary_type, + reduction: measure.reduction.clone(), + filter: measure.filter.cloned(), + })) +} + +/// Adds `output` (over memo groups and `pending`) as a candidate of +/// `result_group`, filtered by `above` when there is one, and returns what +/// each id names once `pending` is added ([`commit_pending`], its summary +/// builds listing `fused_groups`). When its column names differ from the +/// group's, `output` becomes its own group, read through a `Project` that +/// names its columns as the group does ([`renaming_project`]). With an +/// `above` predicate the output (named as the group) is a group, and the +/// `Filter` over it is the candidate. The candidate's schema is checked +/// against the group's on the pending expressions, before any is added: a +/// mismatch is `Unsupported`. +pub(super) fn add_output_candidate( + memo: &mut Memo, + result_group: MemoGroupId, + mut pending: Pending, + output: Operator, + above: Option<&Predicate>, + fused_groups: &[MemoGroupId], +) -> Result MemoGroupId, PerComputationCandidateError> { + let to = schema(memo, result_group).clone(); + let output_group = pending.push(memo, output)?; + let from = pending.schema(memo, output_group).clone(); + let named = if from == to { + pending.pop() + } else { + renaming_project(&from, &to, output_group)? + }; + let candidate = match above { + None => named, + Some(pred) => Operator::NonASAP(NonASAPOp::Filter { + pred: pred.clone(), + child: pending.push(memo, named)?, + }), + }; + let checked = pending.push(memo, candidate)?; + if pending.schema(memo, checked) != &to { + return Err(PerComputationCandidateError::Unsupported( + "a candidate whose schema differs from its group's", + )); + } + let candidate = pending.pop(); + let group_of = commit_pending(memo, pending, fused_groups)?; + let candidate = candidate.map_children(|&input| group_of(input)); + add_candidate(memo, result_group, candidate, None, Vec::new())?; + Ok(group_of) +} + +/// A `Project` over `output` (schema `from`) that names its columns as a +/// group of schema `to` does. `output` must have the group's number of +/// columns, and the group's schema must be closed (list every column its +/// rows carry). +fn renaming_project( + from: &Schema, + to: &Schema, + output: MemoGroupId, +) -> Result, PerComputationCandidateError> { + // An open schema's rows carry columns it does not list (a PromQL + // series whose identity is not realized as a column): a `Project` lists + // its columns, so it would drop them, and its rows are not the group's. + if !to.closed { + return Err(PerComputationCandidateError::Unsupported( + "a rename drops the columns an open schema does not list", + )); + } + if from.fields.len() != to.fields.len() { + return Err(PerComputationCandidateError::Unsupported( + "substituted output with other columns than the aggregate", + )); + } + let cols = to + .fields + .iter() + .enumerate() + .map(|(column, field)| ProjectItem { + alias: Some(field.name.clone()), + expr: ScalarExpr::Column(column), + }) + .collect(); + Ok(Operator::NonASAP(NonASAPOp::Project { + cols, + child: output, + })) +} + +/// A heap's top-k `estimate` (schema `estimated`: `[partitions.., items.., +/// topk]`, one row per ranked item) in the columns of a result group of +/// schema `to`, as a `Project`: its `[keys.., topk_k]`, with `topk_k` the +/// estimated Float64 weight, then the item columns. This is the exact +/// top-k's physical shape (its ranked rows' value, then the columns naming +/// each ranked item: PromQL labels, SQL group keys), so consumers of +/// `[keys.., topk_k]` find those columns where they were. +fn ranked_as_topk( + reduction: &Reduction, + to: &Schema, + estimated: &Schema, + estimate: MemoGroupId, +) -> Result, PerComputationCandidateError> { + let ranked_index = reduction.group_keys().map_or(0, |keys| keys.len()); + let fields = &estimated.fields; + let estimated_value = fields.len() - 1; + let cols = to + .fields + .iter() + .enumerate() + .map(|(index, field)| { + let source = if index == ranked_index { + estimated_value + } else { + fields[..estimated_value] + .iter() + .position(|input| input.name == field.name) + .ok_or(PerComputationCandidateError::Unsupported( + "top-k estimate without a ranked-row identity column", + ))? + }; + // The estimated weight is Float64; an exact top-k of a SQL + // count ranks Int64 values, so its column is cast to them. + let expr = match (&fields[source].dtype, &field.dtype) { + (FieldDataType::Plain(from), FieldDataType::Plain(to)) if from != to => { + ScalarExpr::Cast { + expr: Box::new(ScalarExpr::Column(source)), + to: to.clone(), + try_cast: false, + } + } + _ => ScalarExpr::Column(source), + }; + Ok(ProjectItem { + alias: Some(field.name.clone()), + expr, + }) + }) + .collect::, PerComputationCandidateError>>()?; + Ok(Operator::NonASAP(NonASAPOp::Project { + cols, + child: estimate, + })) +} + +/// `group` (a memo group or pending), a grouped aggregate's `keys` group +/// keys and then its value, with the value cast to Float64 unless it +/// already is one (a pending `Project` over it). +fn last_as_float64( + memo: &Memo, + pending: &mut Pending, + keys: usize, + group: MemoGroupId, +) -> Result { + if pending + .schema(memo, group) + .fields + .last() + .map(|field| &field.dtype) + == Some(&FieldDataType::Plain(DataType::Float64)) + { + return Ok(group); + } + let mut cols = key_items(keys); + cols.push(ProjectItem { + alias: None, + expr: ScalarExpr::Cast { + expr: Box::new(ScalarExpr::Column(keys)), + to: DataType::Float64, + try_cast: false, + }, + }); + pending.push( + memo, + Operator::NonASAP(NonASAPOp::Project { cols, child: group }), + ) +} + +/// SQL `avg` from its finalized `sum` and `count` groups (memo groups or +/// pending): joined on the group keys (NULL keys match), then +/// `sum / count` as Float64. A group with no row passing the measure +/// filter, or an empty global input, counts 0 and its `avg` is NULL. +fn sql_avg( + memo: &Memo, + pending: &mut Pending, + reduction: &Reduction, + filtered: bool, + sum: MemoGroupId, + count: MemoGroupId, +) -> Result, PerComputationCandidateError> { + let Some(by) = reduction.group_keys().filter(|by| !by.is_without()) else { + return Err(PerComputationCandidateError::Unsupported( + "SQL avg without `by` keys", + )); + }; + let keys = by.len(); + let float = |column| { + Box::new(ScalarExpr::Cast { + expr: Box::new(ScalarExpr::Column(column)), + to: DataType::Float64, + try_cast: false, + }) + }; + let count_column = keys + 1 + keys; + let mut avg = ScalarExpr::Arithmetic { + op: ArithmeticOpKind::Div, + left: float(keys), + right: float(count_column), + semantics: ExprSemantics::Sql, + }; + if filtered || keys == 0 { + avg = ScalarExpr::Case { + operand: None, + branches: vec![( + ScalarExpr::Compare { + left: Box::new(ScalarExpr::Column(count_column)), + op: CompareOpKind::Eq, + right: Box::new(ScalarExpr::Literal(ScalarValue::Int64(0))), + semantics: ExprSemantics::Sql, + }, + ScalarExpr::Literal(ScalarValue::Null), + )], + else_expr: Some(Box::new(avg)), + }; + } + let mut cols = key_items(keys); + cols.push(ProjectItem { + alias: None, + expr: avg, + }); + let join = join_on_keys(memo, pending, keys, sum, count); + let joined = pending.push(memo, join)?; + Ok(Operator::NonASAP(NonASAPOp::Project { + cols, + child: joined, + })) +} + +/// `left` joined with `right` (memo groups or pending) on their leading +/// `keys` columns; NULL keys match each other, as grouping treats them. +fn join_on_keys( + memo: &Memo, + pending: &Pending, + keys: usize, + left: MemoGroupId, + right: MemoGroupId, +) -> Operator { + let width = pending.schema(memo, left).fields.len(); + let right_schema = pending.schema(memo, right); + let column = |id| Box::new(ScalarExpr::Column(id)); + let matches = (0..keys) + .map(|key| { + let equal = ScalarExpr::Compare { + left: column(key), + op: CompareOpKind::Eq, + right: column(width + key), + semantics: ExprSemantics::Sql, + }; + if right_schema.fields[key].nullable { + ScalarExpr::BoolOr(vec![ + equal, + ScalarExpr::BoolAnd(vec![ + ScalarExpr::IsNull(column(key)), + ScalarExpr::IsNull(column(width + key)), + ]), + ]) + } else { + equal + } + }) + .collect::>(); + let (kind, pred) = match matches.len() { + 0 => ( + JoinKind::Cross, + ScalarExpr::Literal(ScalarValue::Boolean(true)), + ), + _ => (JoinKind::Inner, ScalarExpr::BoolAnd(matches)), + }; + Operator::NonASAP(NonASAPOp::Join { + kind, + pred: Predicate(pred), + left, + right, + }) +} + +/// Joins single-measure `parts` (each a group, memo or pending: group +/// keys, then one value) on their group keys, pushing the joins onto +/// `pending`, and projects `result_group`'s output columns. Every part has +/// the same groups, so an inner join keeps them all; NULL keys match each +/// other, as grouping treats them. +pub(super) fn join_measures( + memo: &Memo, + pending: &mut Pending, + reduction: &Reduction, + result_group: MemoGroupId, + parts: &[MemoGroupId], +) -> Result, PerComputationCandidateError> { + let Some(by) = reduction.group_keys().filter(|by| !by.is_without()) else { + return Err(PerComputationCandidateError::Unsupported( + "multi-measure aggregate without `by` keys", + )); + }; + let keys = by.len(); + let width = keys + 1; + let (&first, rest) = parts.split_first().expect("an aggregate has measures"); + let mut joined = first; + for &part in rest { + let join = join_on_keys(memo, pending, keys, joined, part); + joined = pending.push(memo, join)?; + } + let to = schema(memo, result_group); + let mut cols = key_items(keys); + cols.extend((0..to.fields.len() - keys).map(|measure| ProjectItem { + alias: None, + expr: ScalarExpr::Column(measure * width + keys), + })); + for (item, field) in cols.iter_mut().zip(&to.fields) { + item.alias = Some(field.name.clone()); + } + Ok(Operator::NonASAP(NonASAPOp::Project { + cols, + child: joined, + })) +} + +/// The first `keys` columns, unrenamed. +fn key_items(keys: usize) -> Vec> { + (0..keys) + .map(|key| ProjectItem { + alias: None, + expr: ScalarExpr::Column(key), + }) + .collect() +} diff --git a/crates/stage1-pass1-per-computation-candidates/src/candidates/mod.rs b/crates/stage1-pass1-per-computation-candidates/src/candidates/mod.rs new file mode 100644 index 000000000..30992f0e8 --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/src/candidates/mod.rs @@ -0,0 +1,509 @@ +//! Stage 1, Pass 1's candidates: [`add_pass1_candidates`] adds each way to +//! compute a group as candidates, through `Memo::find_or_add_group` and +//! `Memo::add_candidate`, from the targets `crate::computation_targets` +//! finds: +//! +//! - **Exact.** Every group's own expression is a candidate of it. +//! - **Exact accumulator.** An accumulator-state group +//! (`SummaryAgg` of an exact summary type) and a `FinalizeExactAccumulator` +//! candidate over it; `avg` finalizes its `sum` and `count` states and +//! divides them. +//! - **Summary.** One state group per sketch algorithm (`SummaryAgg` of +//! it), with one build candidate per configuration of the algorithm's predefined +//! list (`parameter_list`), and a readout (`SummaryEstimate`) group over +//! it, read by the result group. +//! - **Fused builds.** A whole-expression top-k (a heap over the rows below +//! a per-item `sum` or `count`) and a nested distributive aggregate (one +//! exact `Sum`, `Min` or `Max` state over the rows below a `sum` of a +//! `sum`, a `min` of a `min` or a `max` of a `max`): each computes several +//! operators of one appearance as one operator, and its builds list the +//! groups of the operators it replaces in `fused_groups` (concepts doc +//! §3, "Fused groups"). +//! +//! Every intermediate result is its own group, and every candidate is one +//! operator over input groups. A candidate outputs its group's schema +//! exactly (`add_candidate` checks it), so a readout whose column names +//! differ from the group's is read through a renaming `Project` group. +//! $\boldsymbol\theta$ lives only in `LogicalProperties::parameters`, never +//! in an operator. +//! +//! Pass 1 sets no input requirement: each candidate's are empty, and Pass 2 +//! gives each readout's input its required accuracy (a top-k readout's +//! `heap_size` ≥ k is part of that rule; concepts doc, section 2). +//! +//! A measure filter or `HAVING` prunes nothing. The measure filter is +//! applied as `SummaryAgg.filter`. A `HAVING` is the aggregate's own +//! `having` or a consumer `Filter` group directly above the aggregate group, +//! read from the memo: its key-only conjuncts (`key_only_having`) are pushed +//! below the aggregate by the candidates that compute the filtered result +//! (the aggregate group, or that `Filter` group); the other conjuncts stay +//! one `Filter` above the output. +//! +//! Each way is built pending (`Pending`) and added only once +//! every check that can find it unsupported has passed, so an unsupported +//! way adds nothing to the memo. + +mod measure_output; +mod pending; + +use std::collections::BTreeMap; + +use asap_types::ir::operator::arguments::Reduction; +use asap_types::ir::operator::AggIntent; +use asap_types::ir::schema::FieldDataType; +use asap_types::ir::{ASAPOp, NonASAPOp, Operator, OperatorResultKind, Predicate, ScalarExpr}; +use asap_types::stages::{raw_data_samples_of_metric_of_group, Memo, MemoGroupId}; + +use crate::computation_targets::{ + having_filter_groups, nested_distributive_input, whole_expression_input, ComputationTarget, + HowToComputeAggregateMeasure, +}; +use crate::summary_realization::{measure_input, with_raw_data_samples_requirement}; +use crate::{expression, PerComputationCandidateError}; +use measure_output::{ + accumulator_build, add_output_candidate, join_measures, measure_output, summary_readout, +}; +pub(crate) use pending::Pending; +use pending::{add_candidate, commit_pending}; + +/// Adds Pass 1's candidates to `memo` (Stage 0's, without candidates): +/// every group's own expression, then, for each aggregate group with +/// `targets`, each way to compute it. A consumer `Filter` group whose +/// `HAVING` has key-only conjuncts gets the candidates that compute its +/// rows with those conjuncts pushed below the aggregate. Every group and +/// candidate is added through `Memo::find_or_add_group` and +/// `Memo::add_candidate`. +pub(crate) fn add_pass1_candidates( + memo: &mut Memo, + targets: &[ComputationTarget], +) -> Result<(), PerComputationCandidateError> { + // Stage 0's groups: a consumer `Filter` among them is a query's + // `HAVING`; the `Filter` groups Pass 1 adds are parts of its candidates. + let stage0_groups = memo.groups().len(); + for index in 0..stage0_groups { + let group = MemoGroupId(index as u32); + let own = expression(memo, group).clone(); + add_candidate(memo, group, own, None, Vec::new())?; + } + let mut targets_of: BTreeMap> = BTreeMap::new(); + for target in targets { + targets_of + .entry(target.aggregate_group) + .or_default() + .push(target); + } + for (&aggregate_group, group_targets) in &targets_of { + let Operator::NonASAP(NonASAPOp::Aggregate { + reduction, having, .. + }) = expression(memo, aggregate_group) + else { + continue; + }; + let (below, above) = split_having(reduction, having); + // Each consumer `Filter` group whose `HAVING` has key-only conjuncts + // gets the candidates that compute its rows with them pushed below, + // after the aggregate's own; the other conjuncts of both stay above, + // as one `Filter`. + let pushed_down: Vec<_> = having_filter_groups(memo, aggregate_group) + .filter(|&(filter, _)| (filter.0 as usize) < stage0_groups) + .filter(|(_, pred)| { + pred.0 + .conjuncts() + .iter() + .any(|conjunct| key_only_having(reduction, conjunct)) + }) + .map(|(filter, pred)| (filter, split_having(reduction, having.iter().chain([pred])))) + .collect(); + let ways = AggregateWays { + aggregate_group, + result_group: aggregate_group, + below: &below, + above: above.as_ref(), + targets: group_targets, + }; + add_aggregate_candidates(memo, &ways)?; + for (filter, (below, above)) in pushed_down { + let filtered = AggregateWays { + result_group: filter, + below: &below, + above: above.as_ref(), + ..ways + }; + add_aggregate_candidates(memo, &filtered)?; + } + } + Ok(()) +} + +/// The conjuncts of `havings` over an aggregate's output, in order, split +/// into those that read only its group keys ([`key_only_having`]), which +/// can filter its input rows, and the others, joined as one predicate +/// (`None` when every conjunct is key-only). +fn split_having<'a>( + reduction: &Reduction, + havings: impl IntoIterator>, +) -> (Vec>, Option>) { + let (key_only, mut rest): (Vec<_>, Vec<_>) = havings + .into_iter() + .flat_map(|having| having.0.conjuncts()) + .cloned() + .partition(|conjunct| key_only_having(reduction, conjunct)); + let rest = match rest.len() { + 0 => None, + 1 => rest.pop().map(Predicate), + _ => Some(Predicate(ScalarExpr::BoolAnd(rest))), + }; + (key_only.into_iter().map(Predicate).collect(), rest) +} + +/// Whether the `HAVING` conjunct `conjunct` over an aggregate's output can +/// filter its input rows instead: it reads no other operator, and either +/// reads only its `by(...)` group keys, at least one of them, or is a +/// constant built of literals and comparison and boolean operators (such as +/// `1 = 0`), which no input row changes. A column-free conjunct with +/// anything else, such as a function call, may be volatile (`random() < +/// 0.5`) and stays above. A global aggregate (no group keys) never +/// qualifies: its one output row exists even when no input row does, so no +/// row predicate can stand in. +pub(crate) fn key_only_having(reduction: &Reduction, conjunct: &ScalarExpr) -> bool { + let keys = match reduction { + Reduction::Reduce(by) if !by.is_without() => by.len(), + _ => 0, + }; + let columns = conjunct.columns_referenced(); + keys > 0 + && conjunct.operator_refs().is_empty() + && columns.iter().all(|id| *id < keys) + && (!columns.is_empty() || literal_comparison_or_boolean(conjunct)) +} + +/// Whether `expr` is built only of literals and comparison and boolean +/// operators: no column, function call or timestamp. +fn literal_comparison_or_boolean(expr: &ScalarExpr) -> bool { + matches!( + expr, + ScalarExpr::Literal(_) + | ScalarExpr::Compare { .. } + | ScalarExpr::BoolAnd(_) + | ScalarExpr::BoolOr(_) + | ScalarExpr::Not(_) + | ScalarExpr::IsNull(_) + | ScalarExpr::IsNotNull(_) + ) && expr + .children() + .into_iter() + .all(literal_comparison_or_boolean) +} + +/// The ways to compute one result from an aggregate group's targets. +struct AggregateWays<'a> { + /// The aggregate group whose measures are computed. + aggregate_group: MemoGroupId, + /// The group the candidates compute: the aggregate group, or a consumer + /// `Filter` group above it whose key-only `HAVING` conjuncts go below. + result_group: MemoGroupId, + /// Key-only predicates over the aggregate's output, applied to its + /// input rows (their key columns renumbered to the input's). + below: &'a [Predicate], + /// The predicate applied as a `Filter` above the output, if any. + above: Option<&'a Predicate>, + /// The aggregate's targets, one per measure that has one. + targets: &'a [&'a ComputationTarget], +} + +/// One measure of an aggregate, computed on its own over `input`. +pub(crate) struct SingleMeasure<'a> { + /// The rows the measure reads: a memo group, or a pending `Filter` of + /// the key-only `HAVING` conjuncts over `unfiltered_input`. + pub(crate) input: MemoGroupId, + /// The memo group `input` filters, or `input` itself: it has `input`'s + /// schema and kind, and is ranked as `input` is. + pub(crate) unfiltered_input: MemoGroupId, + pub(crate) reduction: &'a Reduction, + pub(crate) intent: &'a AggIntent, + pub(crate) filter: Option<&'a Predicate>, + /// The metric whose raw data samples, or plain sums of them, are every + /// value the aggregate reads: a heap-sketch weight read from them + /// carries the open requirement `WeightDomain::RawDataSamplesOfMetric`. + pub(crate) raw_data_samples_of: Option<&'a str>, +} + +/// Adds `ways.result_group`'s candidates that compute it from +/// `ways.aggregate_group`'s measures: for a single measure, each of its +/// target's ways and fused ways; for several, one candidate joining the +/// measures' own groups (a single-measure aggregate each, with its own +/// candidates) on the group keys. Each way starts pending with the +/// key-only `HAVING` conjuncts as `Filter`s over the aggregate's input. +fn add_aggregate_candidates( + memo: &mut Memo, + ways: &AggregateWays<'_>, +) -> Result<(), PerComputationCandidateError> { + let Operator::NonASAP(NonASAPOp::Aggregate { + child, + reduction, + measures, + output_names, + filters, + .. + }) = expression(memo, ways.aggregate_group).clone() + else { + unreachable!("add_pass1_candidates passes only aggregate groups"); + }; + let keys: Vec = reduction + .group_keys() + .map_or_else(Vec::new, |by| by.keys().to_vec()); + // A way over the aggregate's input rows, filtered by the key-only + // conjuncts, pending. + let start_way = |memo: &Memo| -> Result<(Pending, MemoGroupId), PerComputationCandidateError> { + let mut pending = Pending::new(memo); + let mut input = child; + for predicate in ways.below { + let pred = Predicate(predicate.0.map_columns(&mut |column| keys[column])); + input = pending.push( + memo, + Operator::NonASAP(NonASAPOp::Filter { pred, child: input }), + )?; + } + Ok((pending, input)) + }; + let raw_data_samples = raw_data_samples_of_metric_of_group(memo, child); + let measure = |index: usize, input: MemoGroupId| SingleMeasure { + input, + unfiltered_input: child, + reduction: &reduction, + intent: &measures[index], + filter: filters.get(index).and_then(Option::as_ref), + raw_data_samples_of: raw_data_samples.as_deref(), + }; + let target_of = |index: usize| { + ways.targets + .iter() + .find(|target| target.measure_index == index) + }; + if measures.len() == 1 { + let Some(target) = target_of(0) else { + return Ok(()); + }; + for way in &target.ways_to_compute { + unless_unsupported(start_way(memo).and_then(|(pending, input)| { + add_measure_way( + memo, + pending, + &measure(0, input), + way, + ways.result_group, + ways.above, + ) + }))?; + } + // A fused computation has no `HAVING`, so nothing filters its input. + if let Some(fused) = &target.fused_computation { + for way in &fused.ways_to_compute { + unless_unsupported(add_fused_candidate( + memo, + ways.aggregate_group, + ways.result_group, + &measure(0, child), + way, + &fused.absorbed_groups, + ))?; + } + } + return Ok(()); + } + // The measures are joined back on their group keys: SQL rows grouped + // `by` keys (PromQL aggregates have one measure each). + if !matches!(&reduction, Reduction::Reduce(by) if !by.is_without()) + || memo.groups()[child.0 as usize].group_properties.result_kind + != OperatorResultKind::Relation + { + return Ok(()); + } + let joined = unless_unsupported(start_way(memo).and_then(|(mut pending, input)| { + let parts = (0..measures.len()) + .map(|index| { + pending.push( + memo, + single_measure_part( + &reduction, + &measures, + &output_names, + &filters, + index, + input, + ), + ) + }) + .collect::, _>>()?; + let output = join_measures(memo, &mut pending, &reduction, ways.result_group, &parts)?; + let group_of = + add_output_candidate(memo, ways.result_group, pending, output, ways.above, &[])?; + Ok(( + group_of(input), + parts.into_iter().map(group_of).collect::>(), + )) + }))?; + // Each measure's own group gets its ways once the join adds it. + let Some((input, parts)) = joined else { + return Ok(()); + }; + for (index, part) in parts.into_iter().enumerate() { + if let Some(target) = target_of(index) { + for way in &target.ways_to_compute { + unless_unsupported(add_measure_way( + memo, + Pending::new(memo), + &measure(index, input), + way, + part, + None, + ))?; + } + } + } + Ok(()) +} + +/// Measure `index` of a multi-measure aggregate over `input` as its own +/// single-measure aggregate, written as the frontends write one: its name, +/// and its filter only when it has one (an unfiltered aggregate lists none), +/// so it is the same group as an equal Stage 0 aggregate. +fn single_measure_part( + reduction: &Reduction, + measures: &[AggIntent], + output_names: &[String], + filters: &[Option>], + index: usize, + input: MemoGroupId, +) -> Operator { + Operator::NonASAP(NonASAPOp::Aggregate { + child: input, + reduction: reduction.clone(), + measures: vec![measures[index].clone()], + output_names: output_names + .get(index) + .map_or_else(Vec::new, |name| vec![name.clone()]), + filters: filters + .get(index) + .cloned() + .flatten() + .map_or_else(Vec::new, |filter| vec![Some(filter)]), + having: None, + }) +} + +/// `added`, or `None` when the way is one Pass 1 cannot build +/// (`Unsupported`), which is not offered. Every check that returns +/// `Unsupported` runs before the way adds its first group or candidate (its +/// groups are pending until then), so an unsupported way leaves the memo +/// unchanged. +fn unless_unsupported( + added: Result, +) -> Result, PerComputationCandidateError> { + match added { + Err(PerComputationCandidateError::Unsupported(_)) => Ok(None), + added => added.map(Some), + } +} + +/// Adds `measure`'s way `way`, started in `pending`, as candidates of +/// `result_group`, filtered by `above` when there is one: its +/// groups are built pending ([`measure_output`](fn@measure_output)), checked, and only then +/// added. +pub(crate) fn add_measure_way( + memo: &mut Memo, + mut pending: Pending, + measure: &SingleMeasure<'_>, + way: &HowToComputeAggregateMeasure, + result_group: MemoGroupId, + above: Option<&Predicate>, +) -> Result<(), PerComputationCandidateError> { + let output = measure_output(memo, &mut pending, measure, way, result_group)?; + add_output_candidate(memo, result_group, pending, output, above, &[]).map(|_| ()) +} + +/// Adds the fused computation `way` of `aggregate_group`'s single measure +/// `measure`, as candidates of `result_group`: a whole-expression heap (a +/// summary way) or a nested distributive merge (an exact accumulator way). +/// Its builds list `absorbed_groups`, the groups of the operators it +/// replaces, in `fused_groups`. +fn add_fused_candidate( + memo: &mut Memo, + aggregate_group: MemoGroupId, + result_group: MemoGroupId, + measure: &SingleMeasure<'_>, + way: &HowToComputeAggregateMeasure, + absorbed_groups: &[MemoGroupId], +) -> Result<(), PerComputationCandidateError> { + let mut pending = Pending::new(memo); + match way { + HowToComputeAggregateMeasure::Summary(algorithm) => { + let (rows, update, partitions) = whole_expression_input(memo, aggregate_group).ok_or( + PerComputationCandidateError::Unsupported("whole-expression top-k input"), + )?; + let build = Operator::ASAP(ASAPOp::SummaryAgg { + child: rows, + input: with_raw_data_samples_requirement(update, measure.raw_data_samples_of), + summary_type: FieldDataType::Sketch(*algorithm), + reduction: partitions, + filter: None, + }); + let output = summary_readout( + memo, + &mut pending, + build, + measure.intent, + measure.reduction, + result_group, + )?; + add_output_candidate(memo, result_group, pending, output, None, absorbed_groups) + .map(|_| ())?; + } + HowToComputeAggregateMeasure::ExactAccumulator(_) => { + // The merged build computes the outer aggregate's own + // accumulator state, from the rows below the inner aggregate: a + // candidate of that state group. + let (rows, inner, partitions, kind) = nested_distributive_input(memo, aggregate_group) + .ok_or(PerComputationCandidateError::Unsupported( + "nested distributive merge input", + ))?; + let outer_build = accumulator_build( + memo, + kind, + measure.intent, + measure, + measure_input( + measure.intent, + memo, + measure.unfiltered_input, + measure.filter, + )?, + )?; + let below_inner = SingleMeasure { + input: rows, + unfiltered_input: rows, + reduction: &partitions, + intent: &inner, + filter: None, + raw_data_samples_of: None, + }; + let merged = accumulator_build( + memo, + kind, + &inner, + &below_inner, + measure_input(&inner, memo, rows, None)?, + )?; + let outer_state = pending.push(memo, outer_build)?; + let group_of = commit_pending(memo, pending, &[])?; + add_candidate( + memo, + group_of(outer_state), + merged, + None, + absorbed_groups.to_vec(), + )?; + } + } + Ok(()) +} diff --git a/crates/stage1-pass1-per-computation-candidates/src/candidates/pending.rs b/crates/stage1-pass1-per-computation-candidates/src/candidates/pending.rs new file mode 100644 index 000000000..44fd9d99e --- /dev/null +++ b/crates/stage1-pass1-per-computation-candidates/src/candidates/pending.rs @@ -0,0 +1,186 @@ +//! A way to compute a group, built pending before it is added: its +//! expressions are checked against the schemas the memo derives for them +//! (`Memo::output_schema_of_pending_expression`) and added only once every +//! check that can find the way unsupported has passed, so an unsupported +//! way adds nothing. + +use asap_types::ir::schema::FieldDataType; +use asap_types::ir::schema::Schema; +use asap_types::ir::{ASAPOp, Operator}; +use asap_types::stages::{ + CandidateExpression, CandidateForMemoGroup, LogicalProperties, LogicalRequirements, Memo, + MemoGroupId, OriginOfCandidateForMemoGroup, +}; +use asap_types::summary_type::{parameter_list, SketchParams}; + +use crate::{schema, PerComputationCandidateError}; + +/// The expressions of one way to compute a group, not yet in the memo, in +/// the order they are added, each with its derived output schema. Each +/// reads memo groups or earlier pending expressions: pending expression `k` +/// is named `MemoGroupId(first_id + k)`, the id it would get as a new group. +pub(crate) struct Pending { + /// The memo's group count when the way was started. + first_id: usize, + /// Each pending expression with its output schema, derived once when it + /// was pushed. + expressions_with_schemas: Vec<(Operator, Schema)>, +} + +impl Pending { + /// An empty way over `memo`'s groups. + pub(crate) fn new(memo: &Memo) -> Self { + Self { + first_id: memo.groups().len(), + expressions_with_schemas: Vec::new(), + } + } + + /// Appends `expression`, once its output schema derives over `memo` and + /// the earlier pending expressions, and returns the id that names it. + /// An expression that does not derive is a bug in the rule that built it. + pub(crate) fn push( + &mut self, + memo: &Memo, + expression: Operator, + ) -> Result { + let schema = + memo.output_schema_of_pending_expression(&self.expressions_with_schemas, &expression)?; + let id = MemoGroupId( + u32::try_from(self.first_id + self.expressions_with_schemas.len()) + .expect("a memo has at most u32::MAX groups"), + ); + self.expressions_with_schemas.push((expression, schema)); + Ok(id) + } + + /// The last pushed expression, removed: it becomes a candidate rather + /// than a group. + pub(crate) fn pop(&mut self) -> Operator { + self.expressions_with_schemas + .pop() + .expect("an expression was pushed") + .0 + } + + /// The output schema of `group`: a memo group's, or a pending + /// expression's. + pub(crate) fn schema<'a>(&'a self, memo: &'a Memo, group: MemoGroupId) -> &'a Schema { + match (group.0 as usize).checked_sub(self.first_id) { + None => schema(memo, group), + Some(index) => &self.expressions_with_schemas[index].1, + } + } +} + +/// Adds `pending` to `memo` in order, each pending input replaced by the +/// group it became: a summary build as a state group with its build +/// candidates, listing `fused_groups` ([`add_state_group`]), any other +/// expression as its own group's candidate ([`add_group`]). Returns what +/// each id names now: a memo group stays, a pending id becomes the group its +/// expression became. The caller has already checked the way, so a failure +/// here is a bug. +/// +/// # Panics +/// +/// When `memo` gained groups since the way was started. +pub(crate) fn commit_pending( + memo: &mut Memo, + pending: Pending, + fused_groups: &[MemoGroupId], +) -> Result MemoGroupId, PerComputationCandidateError> { + let first_id = pending.first_id; + assert_eq!( + memo.groups().len(), + first_id, + "no group is added between starting and adding a way" + ); + let mut groups: Vec = Vec::with_capacity(pending.expressions_with_schemas.len()); + let group_of = move |groups: &[MemoGroupId], id: MemoGroupId| { + (id.0 as usize) + .checked_sub(first_id) + .map_or(id, |index| groups[index]) + }; + for (expression, _) in pending.expressions_with_schemas { + let expression = expression.map_children(|&input| group_of(&groups, input)); + let group = match expression { + Operator::ASAP(ASAPOp::SummaryAgg { .. }) => { + add_state_group(memo, expression, fused_groups)? + } + _ => add_group(memo, expression)?, + }; + groups.push(group); + } + Ok(move |id| group_of(&groups, id)) +} + +/// The group of `operator`, whatever adds it, with `operator` as its +/// candidate: an intermediate result is its own group. +pub(crate) fn add_group( + memo: &mut Memo, + operator: Operator, +) -> Result { + let group = memo.find_or_add_group(operator.clone())?; + add_candidate(memo, group, operator, None, Vec::new())?; + Ok(group) +} + +/// The state group of `build` (a `SummaryAgg`) with its build candidates: +/// one per configuration of a sketch algorithm's predefined list +/// (`parameter_list`), or the one exact accumulator build. Each lists +/// `fused_groups`. +pub(crate) fn add_state_group( + memo: &mut Memo, + build: Operator, + fused_groups: &[MemoGroupId], +) -> Result { + let group = memo.find_or_add_group(build.clone())?; + let configurations: Vec> = match &build { + Operator::ASAP(ASAPOp::SummaryAgg { + summary_type: FieldDataType::Sketch(algorithm), + .. + }) => parameter_list(*algorithm) + .iter() + .cloned() + .map(Some) + .collect(), + _ => vec![None], + }; + for parameters in configurations { + add_candidate( + memo, + group, + build.clone(), + parameters, + fused_groups.to_vec(), + )?; + } + Ok(group) +} + +/// Adds the candidate `operator` with `parameters` to `group`. Its input +/// requirements are empty: Pass 2 sets each readout's required accuracy +/// (`Memo::set_candidate_input_requirements`). +pub(crate) fn add_candidate( + memo: &mut Memo, + group: MemoGroupId, + operator: Operator, + parameters: Option, + fused_groups: Vec, +) -> Result<(), PerComputationCandidateError> { + let expression = CandidateExpression { operator }; + let logical_properties = LogicalProperties::new(&expression, parameters)?; + let input_requirements = + vec![LogicalRequirements::default(); expression.operator.children().len()]; + memo.add_candidate( + group, + CandidateForMemoGroup { + expression, + logical_properties, + input_requirements, + fused_groups, + origin: OriginOfCandidateForMemoGroup::Pass1, + }, + )?; + Ok(()) +} 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 f20edcf93..91839069c 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs @@ -1,252 +1,105 @@ -//! Stage 1 (logical ASAP-aware optimization), Pass 1: per-computation -//! candidate generation, as defined in -//! `docs/design_docs/proposals/planner-layering.md`. +//! Stage 1, Pass 1's computation targets over the memo groups (concepts doc +//! `memo-groups-properties-requirements.md`, section 3, "Stage 1, Pass 1"). //! -//! [`generate_per_computation_candidates`] walks the memo groups of the -//! workload's memo groups ([`Memo`]) and -//! returns, for every eligible computation, its unranked candidates. A -//! computation ([`ComputationTarget`]) is one measure of an `Aggregate` -//! group whose intent has a realization besides plain exact execution, once -//! however many queries read the group; nested aggregates and operators -//! read by scalar roots are found too. -//! Pass 1 does not consider sharing across computations; that is Pass 2. +//! [`computation_targets`](fn@crate::computation_targets::computation_targets) walks the memo groups and finds, for every +//! aggregate group, one target ([`ComputationTarget`](crate::computation_targets::ComputationTarget)) per measure whose +//! intent has a realization besides plain exact execution, once however +//! many queries read the group, with the ways to compute it and its fused +//! computations: a whole-expression top-k (a heap over the rows below a +//! per-item `sum` or `count`) and a nested distributive aggregate (one +//! exact `Sum`, `Min` or `Max` state over the rows below a `sum` of a +//! `sum`, a `min` of a `min` or a `max` of a `max`). The candidates that +//! compute the targets are `crate::candidates`'. //! -//! - A candidate says how a target is computed: exact or a summary -//! ([`HowToComputeAggregateMeasure`]). Each target has exactly one exact option: -//! its exact accumulator states (`ExactAccumulator`; `[Sum, Count]` for -//! `avg`) when they can be built, otherwise plain `Exact`. Whether they are -//! materialized is decided in Stage 2. -//! - A computation that fuses a target with the targets beneath it is the -//! outer target's [`FusedComputation`], which absorbs the ones beneath and -//! has its own candidates: the whole-expression top-k over a per-item -//! `sum` or `count` (`Summary` of a heap family) and the nested sum, a -//! grouped `sum` over a `sum` (`ExactAccumulator([Sum])`). -//! - Summary choices here are unsized families. Adding them to memo groups -//! creates one build candidate per listed parameter configuration -//! (`parameter_list`); Pass 2 gives readouts their required accuracy. -//! - Candidates are pruned only when provably unable to run, or when the -//! exact candidate provably dominates them (a PromQL top-k's heap over its -//! instant vector, one row per item); accuracy prunes nothing here (Pass -//! 2's dead-candidate elimination does). -//! - A measure filter or `HAVING` prunes nothing. The target records the -//! measure filter (applied as `SummaryAgg.filter`) and one [`HavingEntry`] -//! per consumer `Filter` directly above the aggregate: a key-only predicate -//! applied by every consumer of the aggregate's group, across queries, may go -//! below the aggregate, anything else stays above the output (approximate -//! outputs then get guarantee `None`). So every candidate of a group -//! computes the group's own rows. -//! -//! The input must be a logical DAG: ASAP operators are rejected. A logical -//! DAG has no physical properties (#1200). No cost or accuracy model is -//! used; ranking and discarding valid candidates belong to Stage 3. -use std::collections::{HashMap, HashSet}; -use std::rc::Rc; +//! 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::ir::operator::arguments::{Reduction, Source}; +use asap_types::ir::operator::arguments::Reduction; +use asap_types::ir::operator::arguments::Source; +use asap_types::ir::operator::non_asap::any_measure_filtered; use asap_types::ir::operator::AggIntent; use asap_types::ir::scalar::{resolve_column_ref, ColumnRef}; -use asap_types::ir::schema::FieldDataType; -use asap_types::ir::{ - NonASAPOp, OperatorNode, OperatorResultKind, Predicate, QueryRoot, SchemaDerivationError, -}; -use asap_types::stages::MemoGroupError; +use asap_types::ir::schema::{ColumnId, Schema}; +use asap_types::ir::{NonASAPOp, Operator, OperatorResultKind, Predicate, ScalarExpr}; +use asap_types::stages::{Memo, MemoGroupId}; use asap_types::summary_type::{ ExactKind, SketchAlgorithm, StatisticKind, SummaryInputExpr, SummaryUpdate, }; -use thiserror::Error; use asap_accuracy::sizing::sketch_statistic; - -use crate::summary_realization::summary_candidates; use asap_types::deployment_capabilities::{summary_supported, SupportedSummary}; -use asap_types::stages::{ - ComputationTarget, FusedComputation, HavingEntry, HavingPlacement, - HowToComputeAggregateMeasure, Memo, MemoGroupId, -}; -/// Unranked candidates of one measure and the candidates pruned for it. -#[derive(Debug, Clone, PartialEq)] -pub(super) struct ComputationChoices { - pub candidates: Vec, - pub pruned: Vec, -} - -impl ComputationChoices { - /// Prune matching candidates; a pruned exact accumulator form is replaced by - /// plain `Exact`, so the target keeps one exact option. - fn prune(&mut self, applies: impl Fn(&HowToComputeAggregateMeasure) -> bool) { - let pruned = prune_own(&mut self.candidates, applies); - self.pruned.extend(pruned); - } -} - -/// Removes from a measure's own `candidates` the ones `applies` matches -/// (never `Exact`) and returns them; a pruned exact accumulator form is -/// replaced by plain `Exact`, so the measure keeps one exact option. -fn prune_own( - candidates: &mut Vec, - applies: impl Fn(&HowToComputeAggregateMeasure) -> bool, -) -> Vec { - let (pruned, kept): (Vec<_>, _) = std::mem::take(candidates) - .into_iter() - .partition(|choice| *choice != HowToComputeAggregateMeasure::Exact && applies(choice)); - *candidates = kept; - if pruned - .iter() - .any(|choice| matches!(choice, HowToComputeAggregateMeasure::ExactAccumulator(_))) - { - candidates.insert(0, HowToComputeAggregateMeasure::Exact); - } - pruned -} - -/// Compact Pass 1 inventory over the memo groups it walked: one target per -/// measure of each aggregate group, however many queries read the group. -/// Pass 1's working form, not its output: -/// [`pass1_memo`](crate::pass1_memo) -/// builds, prunes and attaches it to the memo groups. Public only to tests -/// (feature `test-support`). -#[derive(Debug, Clone)] -pub struct PerComputationCandidates { - /// Each query's root over the memo groups' logical nodes, in workload - /// order: a group several queries read is one node. Whole-workload - /// candidates are these roots with chosen candidates substituted - /// (test support only). - #[cfg(any(test, feature = "test-support"))] - pub roots: Vec, - /// Each memo group's logical node, by group index. - pub(crate) logical_nodes: Rc<[Rc]>, - /// The targets; a whole-workload choice has one digit per target, - /// ranging over [`ComputationTarget::choice_count`]. - pub targets: Vec, -} - -impl PerComputationCandidates { - /// The `Aggregate` node of `target`'s memo group. - #[cfg(any(test, feature = "test-support"))] - pub fn aggregate(&self, target: &ComputationTarget) -> &Rc { - &self.logical_nodes[target.aggregate_group.0 as usize] - } - - /// The number of whole-workload candidates: the size of the Cartesian - /// product of the targets' candidates, where a target with a fused - /// computation and the targets beneath that it absorbs count as their - /// own combinations plus the fused computation's candidates (the - /// absorbed targets are not computed then), saturating at `usize::MAX`. - /// A target with `n` candidates and `f` fused ones counts `n · Π m + f`, - /// the product over the targets it absorbs that no other of them - /// absorbs, each counted the same way. It is exactly the number of - /// choices enumeration keeps ([`Self::absorbed_choice_varies`]). - #[cfg(any(test, feature = "test-support"))] - pub fn combinations(&self) -> usize { - let absorbed: HashSet = absorbed_targets(&self.targets).collect(); - (0..self.targets.len()) - .filter(|index| !absorbed.contains(index)) - .map(|index| self.combinations_of(index)) - .fold(1usize, usize::saturating_mul) - } +use crate::summary_realization::{realize_keyed_additive_summary_input, summary_candidates}; +use crate::{expression, schema, PerComputationCandidateError}; - /// [`Self::combinations`] of target `index` with the targets it absorbs. - #[cfg(any(test, feature = "test-support"))] - fn combinations_of(&self, index: usize) -> usize { - let target = &self.targets[index]; - let n = target.ways_to_compute.len(); - let Some(fused) = &target.fused_computation else { - return n; - }; - let absorbed_by_another = |a: usize| { - fused.absorbed_targets.iter().any(|&b| { - self.targets[b] - .fused_computation - .as_ref() - .is_some_and(|inner| inner.absorbed_targets.contains(&a)) - }) - }; - fused - .absorbed_targets - .iter() - .filter(|&&a| !absorbed_by_another(a)) - .map(|&a| self.combinations_of(a)) - .fold(n, usize::saturating_mul) - .saturating_add(fused.ways_to_compute.len()) - } - - /// Whether `choice` picks a fused computation and a candidate other - /// than the first for a target it absorbs: the same whole-workload - /// candidate as the one with the first, so enumeration skips it. - #[cfg(any(test, feature = "test-support"))] - pub fn absorbed_choice_varies(&self, choice: &[usize]) -> bool { - self.targets.iter().zip(choice).any(|(target, &index)| { - target - .computation_for(index) - .and_then(|(_, absorbed)| absorbed) - .is_some_and(|inner| inner.iter().any(|&i| choice[i] != 0)) - }) - } - - /// This inventory without the summary candidates the executor does not - /// support (`supported_summaries`, the deployment's - /// `DeploymentCapabilities::supported_summaries`; `None` supports - /// every one): a target's own are removed, and so are a fused - /// computation's (with all of them removed, the fusion is not offered). - /// The readout is the statistic the measure's estimate reads (the outer measure's for a - /// fused computation). With every summary supported it is unchanged. - pub fn without_unsupported_summaries( - mut self, - supported_summaries: Option<&[SupportedSummary]>, - ) -> Self { - for target in self.targets.iter_mut() { - let aggregate = &self.logical_nodes[target.aggregate_group.0 as usize]; - let Some(NonASAPOp::Aggregate { measures, .. }) = aggregate.non_asap() else { - continue; - }; - let Some(readout) = sketch_statistic(&measures[target.measure_index]).map(|s| s.kind()) - else { - continue; - }; - let unsupported = |candidate: &HowToComputeAggregateMeasure| { - matches!(candidate, HowToComputeAggregateMeasure::Summary(family) - if !summary_supported(supported_summaries, family, readout)) - }; - prune_own(&mut target.ways_to_compute, unsupported); - if let Some(fused) = &mut target.fused_computation { - fused.ways_to_compute.retain(|way| !unsupported(way)); - } - } - self - } +/// How one Pass 1 target is computed besides plain exact execution: by +/// exact accumulator states or a summary. Plain exact execution is not a +/// way here: it is always offered, as the aggregate group's own +/// expression. +#[derive(Debug, Clone, PartialEq)] +pub(crate) enum HowToComputeAggregateMeasure { + /// One or more exact mergeable accumulator states, by accumulator kind, + /// finalized and combined into the measure: one state for `sum`, + /// `count`, `min`, `max`, `rate`, `irate` and `increase`; `[Sum, Count]`, + /// divided, for `avg`. + ExactAccumulator(Vec), + /// A sketch algorithm: its state group gets one build candidate per + /// configuration of the algorithm's predefined list (`parameter_list`). + Summary(SketchAlgorithm), } -/// The indices of `targets` some target's fused computation absorbs. -#[cfg(any(test, feature = "test-support"))] -fn absorbed_targets(targets: &[ComputationTarget]) -> impl Iterator + '_ { - targets - .iter() - .filter_map(|target| target.fused_computation.as_ref()) - .flat_map(|fused| fused.absorbed_targets.iter().copied()) +/// One measure of an aggregate group with at least one realization besides +/// exact execution. +#[derive(Debug)] +pub(crate) struct ComputationTarget { + /// The memo group of the `Aggregate` the measure belongs to. + pub aggregate_group: MemoGroupId, + /// Index into the aggregate's measures. + pub measure_index: usize, + /// The measure's unranked ways to compute it besides plain exact + /// execution, the exact accumulator first when it has one; empty when + /// Pass 1 pruned every one. + pub ways_to_compute: Vec, + /// The fused computation of this measure together with the target + /// directly beneath it, offered beside this target's own candidates; + /// `None` when no fusion applies. + pub fused_computation: Option, } -#[derive(Debug, Error)] -pub enum PerComputationCandidateError { - #[error(transparent)] - Structure(#[from] SchemaDerivationError), - /// A node of a query is not a valid group over its children's groups - /// (Stage 0, `Memo::find_or_add_group`). - #[error(transparent)] - MemoGroup(#[from] MemoGroupError), - #[error("logical candidate input already contains ASAP operators")] - ContainsAsap, - #[error("choice must name one listed candidate per target")] - InvalidChoice, - #[error("unsupported substitution in logical ASAP-aware optimization: {0}")] - Unsupported(&'static str), +/// A target's measure computed together with the targets beneath it, as +/// one operator that replaces their operators in this appearance of the +/// sub-expression (concepts doc §3, "Fused groups"): the whole-expression +/// top-k over a per-item `sum` or `count` (`Summary` of a heap algorithm), or +/// a nested distributive aggregate, a grouped `sum`, `min` or `max` over the +/// same reduction (`ExactAccumulator([Sum])`, `[Min]` or `[Max]`). It has +/// the outer target's aggregate, measure, filter and `HAVING`. +#[derive(Debug)] +pub(crate) struct FusedComputation { + /// The groups of the operators it replaces, which its builds list in + /// `fused_groups`: the aggregate beneath (after the column-renaming + /// `Project` between them, when there is one), then, for a + /// whole-expression heap over the raw data samples beneath a grouped sum + /// of per-series sums or counts (`topk(k, sum by (G) + /// (sum_over_time(m[W])))`), the per-series aggregate beneath that, then + /// 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. + pub ways_to_compute: Vec, } -/// Enumerate exact, rewrite and summary choices of one measure in stable catalog -/// order, without ranking or empirical assessment. A summary is not a claim that -/// a deployment meets the measure's accuracy requirement. The one exact option -/// comes first: the exact accumulator form if the intent has one, else `Exact`. -pub(super) fn computation_candidates_for_intent(intent: &AggIntent) -> ComputationChoices { +/// Enumerate the exact accumulator and summary choices of one measure in +/// stable catalog order, without ranking or empirical assessment. A summary +/// is not a claim that a deployment meets the measure's accuracy +/// requirement. The exact accumulator form comes first when the intent has +/// one; plain exact execution is not listed (it is the group's own +/// expression). A quantile outside [0, 1] gets no summary: its answer is +/// -Inf or +Inf. +pub(crate) fn computation_candidates_for_intent( + intent: &AggIntent, +) -> Vec { let states = match intent { AggIntent::Count => vec![ExactKind::Count], AggIntent::Sum { .. } => vec![ExactKind::Sum], @@ -258,230 +111,165 @@ pub(super) fn computation_candidates_for_intent(intent: &AggIntent) -> Computati AggIntent::Avg { .. } => vec![ExactKind::Sum, ExactKind::Count], _ => vec![], }; - let exact = if states.is_empty() { - HowToComputeAggregateMeasure::Exact - } else { - HowToComputeAggregateMeasure::ExactAccumulator(states) - }; - let mut choices = ComputationChoices { - candidates: vec![exact], - pruned: vec![], - }; - if sketch_statistic(intent).is_some() { - let summaries = summary_candidates(intent).into_iter(); - if matches!(intent, AggIntent::Quantile { q, .. } if !(0.0..=1.0).contains(q)) { - choices - .pruned - .extend(summaries.map(HowToComputeAggregateMeasure::Summary)); - } else { - choices - .candidates - .extend(summaries.map(HowToComputeAggregateMeasure::Summary)); - } + let mut choices = Vec::new(); + if !states.is_empty() { + choices.push(HowToComputeAggregateMeasure::ExactAccumulator(states)); + } + let quantile_outside_unit_interval = + matches!(intent, AggIntent::Quantile { q, .. } if !(0.0..=1.0).contains(q)); + if sketch_statistic(intent).is_some() && !quantile_outside_unit_interval { + choices.extend( + summary_candidates(intent) + .into_iter() + .map(HowToComputeAggregateMeasure::Summary), + ); } choices } /// Whether an `avg` measure's input may be null, so `count` rows differ from /// counted values. An unresolvable input is treated as possibly null. -fn nullable_avg_input(node: &OperatorNode, intent: &AggIntent) -> bool { - let Some(NonASAPOp::Aggregate { child, .. }) = node.non_asap() else { - return true; - }; +fn nullable_avg_input(input: &Schema, intent: &AggIntent) -> bool { let column = match intent.input_cols().first() { Some(column) => Some(*column), - None => resolve_column_ref(&ColumnRef::SampleValue, &child.schema).ok(), + None => resolve_column_ref(&ColumnRef::SampleValue, input).ok(), }; column - .and_then(|column| child.schema.fields.get(column)) + .and_then(|column| input.fields.get(column)) .is_none_or(|field| field.nullable) } -/// Whether `having` over `aggregate`'s output reads only `by(...)` group keys. -/// A global aggregate (no group keys) never qualifies: its one output row -/// exists even when no input row does, so no row predicate can stand in. -fn key_only_having(aggregate: &OperatorNode, having: &Predicate) -> bool { - let keys = match aggregate.non_asap() { - Some(NonASAPOp::Aggregate { - reduction: Reduction::Reduce(by), - .. - }) if !by.is_without() => by.len(), - _ => 0, - }; - keys > 0 - && having.0.operator_refs().is_empty() - && having.0.columns_referenced().iter().all(|id| *id < keys) -} - -fn placement(below: bool) -> HavingPlacement { - if below { - HavingPlacement::BelowAggregate - } else { - HavingPlacement::AboveOutput - } +/// The consumer `Filter` groups directly above `aggregate_group` (its +/// `HAVING` as the SQL frontend lowers it), with their predicates. A +/// `Filter` that reads the aggregate from a scalar expression stays a plain +/// consumer. +pub(crate) fn having_filter_groups( + memo: &Memo, + aggregate_group: MemoGroupId, +) -> impl Iterator)> { + memo.groups()[aggregate_group.0 as usize] + .parent_groups() + .iter() + .filter_map(move |&parent| match expression(memo, parent) { + Operator::NonASAP(NonASAPOp::Filter { child, pred }) if *child == aggregate_group => { + Some((parent, pred)) + } + _ => None, + }) } -/// Each memo group's expression as an operator-node tree, by group id: the -/// trees target discovery still walks. `Memo::logical_node_trees` is -/// deleted; discovery reads the groups in #1207 PR 3. -fn logical_node_trees(memo: &Memo) -> Vec> { - let _ = memo; - todo!("#1207 PR 3: discover targets over the memo groups, not node trees") +/// Whether `aggregate_group` has a `HAVING`: its own `having` or a consumer +/// `Filter` group directly above it ([`having_filter_groups`]). +fn has_having(memo: &Memo, aggregate_group: MemoGroupId) -> bool { + matches!( + expression(memo, aggregate_group), + Operator::NonASAP(NonASAPOp::Aggregate { + having: Some(_), + .. + }) + ) || having_filter_groups(memo, aggregate_group).next().is_some() } -/// Discover one target per measure of each eligible aggregate memo group of -/// `dag`, including operator plans read by scalar roots: 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 prune reasons -/// are reported on the target. Measure filters and `HAVING` keep every -/// candidate; the target records how they are applied. A group's consumers -/// are its parent groups and the query roots that read it; a consumer -/// `Filter`'s key-only `HAVING` is pushed below only when every consumer of -/// the group applies the same predicate, so every candidate of a shared -/// aggregate computes the group's own rows (#1089). -pub fn generate_per_computation_candidates( +/// Discover one target per measure of each eligible aggregate group of +/// `memo`, nested aggregates and those read by scalar roots included: +/// 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. +pub(crate) fn computation_targets( memo: &Memo, -) -> Result { - let logical_nodes: Rc<[Rc]> = logical_node_trees(memo).into(); - let group_of: HashMap<*const OperatorNode, MemoGroupId> = logical_nodes - .iter() - .enumerate() - .map(|(g, node)| (Rc::as_ptr(node), MemoGroupId(g as u32))) - .collect(); - // Each query's root over the groups' logical nodes, in workload order: - // a group several queries read is one node. - let node = |g: &MemoGroupId| Rc::clone(&logical_nodes[g.0 as usize]); - let roots: Vec = memo - .queries() + supported_summaries: Option<&[SupportedSummary]>, +) -> Result, PerComputationCandidateError> { + if memo + .groups() .iter() - .map(|query| match &query.root { - QueryRoot::Operator(g) => QueryRoot::Operator(node(g)), - QueryRoot::Scalar(expr) => QueryRoot::Scalar(expr.map_operator_refs(&mut |g| node(g))), - }) - .collect(); - let mut seen = HashSet::new(); - // Each aggregate group. - let mut aggregates = Vec::new(); - // Every consumer of each group's node: `Some(parent)`, or `None` for a - // query root or scalar reference. - let mut consumers: HashMap<*const OperatorNode, Vec>>> = HashMap::new(); - for root in &roots { - root.validate_structure()?; - let operators = match root { - QueryRoot::Operator(node) => vec![node], - QueryRoot::Scalar(expr) => expr.operator_refs(), - }; - for root in operators { - if root.contains_asap() { - return Err(PerComputationCandidateError::ContainsAsap); - } - consumers.entry(Rc::as_ptr(root)).or_default().push(None); - for node in OperatorNode::reachable(root) { - if !seen.insert(Rc::as_ptr(&node)) { - continue; - } - for child in node.children() { - consumers - .entry(Rc::as_ptr(child)) - .or_default() - .push(Some(Rc::clone(&node))); - } - if matches!(node.non_asap(), Some(NonASAPOp::Aggregate { .. })) { - aggregates.push(node); - } - } - } + .any(|group| matches!(group.expression, Operator::ASAP(_))) + { + return Err(PerComputationCandidateError::ContainsAsap); } let mut targets = Vec::new(); - for node in aggregates { - let Some(NonASAPOp::Aggregate { - measures, - filters, - having, - .. - }) = node.non_asap() + for (index, group) in memo.groups().iter().enumerate() { + let Operator::NonASAP(NonASAPOp::Aggregate { + child, measures, .. + }) = &group.expression else { continue; }; - let aggregate_group = group_of[&Rc::as_ptr(&node)]; - let mut entries: Vec = having - .iter() - .map(|having| HavingEntry { - filter: None, - predicate: having.clone(), - placement: placement(key_only_having(&node, having)), - }) - .collect(); - let parents = &consumers[&Rc::as_ptr(&node)]; - // Only a `Filter` whose input is this aggregate is its `HAVING`; one - // that reads it from a scalar expression stays a plain consumer. - let mut filters_above: Vec<(&Rc, &Predicate)> = Vec::new(); - for parent in parents.iter().flatten() { - if let Some(NonASAPOp::Filter { child, pred }) = parent.non_asap() { - if Rc::ptr_eq(child, &node) - && !filters_above - .iter() - .any(|(filter, _)| Rc::ptr_eq(filter, parent)) - { - filters_above.push((parent, pred)); - } - } - } - for (filter, predicate) in &filters_above { - // Every consumer of the group, across queries, applies it. - let shared_by_all = filters_above.len() == parents.len() - && filters_above.iter().all(|(_, other)| other == predicate); - entries.push(HavingEntry { - filter: Some(Rc::clone(filter)), - predicate: (*predicate).clone(), - placement: placement(shared_by_all && key_only_having(&node, predicate)), - }); - } + let aggregate_group = MemoGroupId(index as u32); for (measure, intent) in measures.iter().enumerate() { let mut choices = computation_candidates_for_intent(intent); - if choices.candidates == [HowToComputeAggregateMeasure::Exact] - && choices.pruned.is_empty() - { + if choices.is_empty() { continue; } - if matches!(intent, AggIntent::Avg { .. }) && nullable_avg_input(&node, intent) { - choices.prune(|choice| { - matches!(choice, HowToComputeAggregateMeasure::ExactAccumulator(_)) + if matches!(intent, AggIntent::Avg { .. }) + && nullable_avg_input(schema(memo, *child), intent) + { + choices.retain(|choice| { + !matches!(choice, HowToComputeAggregateMeasure::ExactAccumulator(_)) }); } if matches!(intent, AggIntent::Count) - && node.children()[0].result_kind == OperatorResultKind::Relation + && memo.groups()[child.0 as usize].group_properties.result_kind + == OperatorResultKind::Relation { - choices.prune(|choice| matches!(choice, HowToComputeAggregateMeasure::Summary(_))); + choices + .retain(|choice| !matches!(choice, HowToComputeAggregateMeasure::Summary(_))); } targets.push(ComputationTarget { aggregate_group, measure_index: measure, - ways_to_compute: choices.candidates, - measure_filter: filters.get(measure).cloned().flatten(), - having_filters: entries.clone(), + ways_to_compute: choices, fused_computation: None, }); } } - add_whole_expression_targets(&mut targets, &logical_nodes); - prune_topk_heaps_over_one_row_per_item(memo, &mut targets, &logical_nodes); - add_nested_sum_targets(&mut targets, &logical_nodes); + add_whole_expression_targets(memo, &mut targets); + prune_topk_heaps_over_one_row_per_item(memo, &mut targets); + add_nested_distributive_targets(memo, &mut targets); close_absorptions(&mut targets); - Ok(PerComputationCandidates { - #[cfg(any(test, feature = "test-support"))] - roots, - logical_nodes, - targets, - }) + without_unsupported_summaries(memo, &mut targets, supported_summaries); + Ok(targets) } -/// Adds to each fused computation's `absorbed_targets` the targets its absorbed -/// targets' own fused computations absorb, transitively: none of them is -/// computed when the fused computation is picked, so enumeration keeps only -/// their first choice ([`PerComputationCandidates::absorbed_choice_varies`]) -/// and [`PerComputationCandidates::combinations`] counts exactly those. +/// 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( + memo: &Memo, + targets: &mut [ComputationTarget], + supported_summaries: Option<&[SupportedSummary]>, +) { + for target in targets.iter_mut() { + let Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) = + expression(memo, target.aggregate_group) + else { + continue; + }; + let Some(readout) = sketch_statistic(&measures[target.measure_index]).map(|s| s.kind()) + else { + continue; + }; + let unsupported = |candidate: &HowToComputeAggregateMeasure| { + matches!(candidate, HowToComputeAggregateMeasure::Summary(algorithm) + if !summary_supported(supported_summaries, algorithm, readout)) + }; + target.ways_to_compute.retain(|way| !unsupported(way)); + if let Some(fused) = &mut target.fused_computation { + fused.ways_to_compute.retain(|way| !unsupported(way)); + } + } +} + +/// Adds to each fused computation's `absorbed_groups` the groups its +/// absorbed targets' own fused computations replace, transitively: the +/// fused computation replaces all their operators, so its builds list all +/// their groups in `fused_groups`. fn close_absorptions(targets: &mut [ComputationTarget]) { loop { let mut changed = false; @@ -489,12 +277,18 @@ fn close_absorptions(targets: &mut [ComputationTarget]) { let Some(fused) = &targets[t].fused_computation else { continue; }; - let beneath: Vec = fused - .absorbed_targets + let beneath: Vec = fused + .absorbed_groups .iter() - .filter_map(|&a| targets[a].fused_computation.as_ref()) - .flat_map(|inner| inner.absorbed_targets.iter().copied()) - .filter(|b| !fused.absorbed_targets.contains(b)) + .filter_map(|&group| { + targets + .iter() + .find(|target| target.aggregate_group == group)? + .fused_computation + .as_ref() + }) + .flat_map(|inner| inner.absorbed_groups.iter().copied()) + .filter(|b| !fused.absorbed_groups.contains(b)) .collect(); if let Some(fused) = targets[t] .fused_computation @@ -502,8 +296,8 @@ fn close_absorptions(targets: &mut [ComputationTarget]) { .filter(|_| !beneath.is_empty()) { for b in beneath { - if !fused.absorbed_targets.contains(&b) { - fused.absorbed_targets.push(b); + if !fused.absorbed_groups.contains(&b) { + fused.absorbed_groups.push(b); } } changed = true; @@ -515,187 +309,272 @@ fn close_absorptions(targets: &mut [ComputationTarget]) { } } -/// Nested-sum merge: a grouped `sum` over the value of a `sum` target -/// beneath it gets a fused computation ([`ComputationTarget::fused_computation`]) -/// with the one candidate `ExactAccumulator([Sum])`: one exact `Sum` -/// accumulator over the inner sum's input, grouped by the outer keys (the -/// sum of the inner groups' sums is the sum of their rows), absorbing the -/// inner target. Offered whatever else reads the inner sum: it is one more -/// candidate of the outer sum's group, and the inner sum's group keeps its -/// own candidates for its other consumers. Applied when neither has a filter -/// or `HAVING` -/// ([`nested_sum_input`]), and when the outer sum is not itself absorbed by -/// a merge and has no fused computation yet, and the inner sum has none, so -/// merges do not stack. An outer sum a whole-expression top-k absorbs -/// (`topk(k, sum by (G) (sum_over_time(m[W])))`) keeps its merge for the -/// top-k's own candidates. -fn add_nested_sum_targets(targets: &mut [ComputationTarget], logical_nodes: &[Rc]) { - let aggregate = |target: &ComputationTarget| &logical_nodes[target.aggregate_group.0 as usize]; - // The targets a merge absorbs. - let mut absorbed: HashSet = HashSet::new(); +/// Nested distributive merge: a grouped `sum`, `min` or `max` over the +/// value of a target of the same reduction beneath it (`sum` of `sum`, +/// `min` of `min`, `max` of `max`) gets a fused computation +/// ([`ComputationTarget::fused_computation`]) with the one candidate +/// `ExactAccumulator([kind])`: one exact accumulator of that kind over the +/// inner aggregate's input, grouped by the outer keys (the sum, min or max +/// of the inner groups' values is that of their rows), absorbing the inner +/// target. Offered whatever else reads the inner aggregate: its group keeps +/// its own candidates for its other consumers. Applied when neither has a +/// filter or `HAVING` ([`nested_distributive_input`]), and when neither the +/// outer aggregate nor the inner one has a fused computation yet, so merges +/// do not stack. Targets follow the memo's group order, inputs first, so an +/// outer aggregate is reached before any merge above it. An outer sum a +/// whole-expression top-k absorbs (`topk(k, sum by (G) +/// (sum_over_time(m[W])))`) keeps its merge for the top-k's own candidates. +fn add_nested_distributive_targets(memo: &Memo, targets: &mut [ComputationTarget]) { for t in 0..targets.len() { let target = &targets[t]; - if absorbed.contains(&t) - || target.fused_computation.is_some() - || !target.having_filters.is_empty() - { + if target.fused_computation.is_some() || has_having(memo, target.aggregate_group) { continue; } - let Some(NonASAPOp::Aggregate { child, .. }) = aggregate(target).non_asap() else { + let Some(nested) = nested_aggregates(memo, target.aggregate_group) else { continue; }; let Some(inner) = targets .iter() - .position(|other| Rc::ptr_eq(aggregate(other), child)) + .position(|other| other.aggregate_group == nested.inner) else { continue; }; - // Merges do not stack: the inner sum must not have a fused + // Merges do not stack: the inner aggregate must not have a fused // computation of its own. - if !targets[inner].having_filters.is_empty() - || targets[inner].fused_computation.is_some() - || nested_sum_input(aggregate(target)).is_none() - { + if has_having(memo, nested.inner) || targets[inner].fused_computation.is_some() { continue; } - absorbed.insert(inner); - let merge = HowToComputeAggregateMeasure::ExactAccumulator(vec![ExactKind::Sum]); + let Some((_, _, _, kind)) = nested_distributive_input(memo, target.aggregate_group) else { + continue; + }; targets[t].fused_computation = Some(FusedComputation { - absorbed_targets: vec![inner], - ways_to_compute: vec![merge], + absorbed_groups: nested.renaming.into_iter().chain([nested.inner]).collect(), + ways_to_compute: vec![HowToComputeAggregateMeasure::ExactAccumulator(vec![kind])], }); } } -/// The input rows, the inner sum and the outer grouping (moved onto the -/// input rows by column, [`Reduction::partitions_over`]) of a nested-sum merge of -/// `target`, or `None` when it does not apply: `target` is a grouped `sum` -/// (not by `without`) of the value column of a per-series or grouped `sum` -/// directly beneath it, neither filtered nor with `HAVING`, and not grouped -/// by the metric name a per-series inner sum drops. -pub(super) fn nested_sum_input( - target: &OperatorNode, -) -> Option<(Rc, AggIntent, Reduction)> { - use asap_types::ir::operator::non_asap::any_measure_filtered; - let Some(NonASAPOp::Aggregate { - child: inner, - reduction: reduction @ Reduction::Reduce(by), +/// The accumulator kind and input column of a distributive measure, one +/// whose value over a union of groups is that of their values: `sum`, `min` +/// and `max`. +fn distributive(intent: &AggIntent) -> Option<(ExactKind, Option)> { + match intent { + AggIntent::Sum { col } => Some((ExactKind::Sum, *col)), + AggIntent::Min { col } => Some((ExactKind::Min, *col)), + AggIntent::Max { col } => Some((ExactKind::Max, *col)), + _ => None, + } +} + +/// An outer grouped aggregate of one measure over the value of a +/// one-measure aggregate beneath it ([`nested_aggregates`]). +pub(crate) struct NestedAggregates<'m> { + /// The outer aggregate's measure. + pub(crate) outer_measure: &'m AggIntent, + /// The outer aggregate's `by` keys, as columns of the inner aggregate's + /// output. + pub(crate) by: Vec, + /// The group of a `Project` between them that only renames or reorders + /// columns (a SQL subquery's), or `None` when the outer aggregate reads + /// the inner one directly. + pub(crate) renaming: Option, + /// The inner aggregate's group. + pub(crate) inner: MemoGroupId, + pub(crate) inner_reduction: &'m Reduction, + pub(crate) inner_measure: &'m AggIntent, + /// The inner aggregate's input. + pub(crate) rows: MemoGroupId, +} + +/// `outer` as a grouped aggregate (not by `without`) of one unfiltered +/// measure without `HAVING`, over the value column of a per-series or +/// grouped (not by `without`) aggregate of one unfiltered measure without +/// `HAVING` beneath it, read directly or through a `Project` that only +/// renames or reorders columns and keeps the key names; not grouped by the +/// value column, nor, over a per-series aggregate, by the metric name. +/// `None` otherwise. +/// +/// A per-series aggregate drops the metric name `__name__`, which the raw +/// rows keep: an outer aggregate grouped by it over the per-series rows has +/// one unnamed group where the same grouping of the raw rows has one per +/// metric, so it is never one aggregate over the raw rows. A key whose +/// column cannot be read is treated as the metric name. +pub(crate) fn nested_aggregates(memo: &Memo, outer: MemoGroupId) -> Option> { + let Operator::NonASAP(NonASAPOp::Aggregate { + child, + reduction: Reduction::Reduce(by), measures, filters, having: None, .. - }) = target.non_asap() + }) = expression(memo, outer) else { return None; }; - let [AggIntent::Sum { col }] = measures.as_slice() else { + let [outer_measure] = measures.as_slice() else { return None; }; - let Some(NonASAPOp::Aggregate { + if by.is_without() || any_measure_filtered(filters) { + return None; + } + // The inner aggregate's column each column the outer one reads is. + let (renaming, inner, inner_column): (Option, MemoGroupId, Vec) = + match expression(memo, *child) { + Operator::NonASAP(NonASAPOp::Project { cols, child: inner }) => ( + Some(*child), + *inner, + cols.iter() + .map(|item| match item.expr { + ScalarExpr::Column(column) => Some(column), + _ => None, + }) + .collect::>()?, + ), + _ => ( + None, + *child, + (0..schema(memo, *child).fields.len()).collect(), + ), + }; + let Operator::NonASAP(NonASAPOp::Aggregate { child: rows, reduction: inner_reduction, measures: inner_measures, filters: inner_filters, having: None, .. - }) = inner.non_asap() + }) = expression(memo, inner) else { return None; }; - let [inner_sum @ AggIntent::Sum { .. }] = inner_measures.as_slice() else { + let [inner_measure] = inner_measures.as_slice() else { return None; }; - if by.is_without() || any_measure_filtered(filters) || any_measure_filtered(inner_filters) { + if any_measure_filtered(inner_filters) { return None; } - // The inner sum's value column: a per-series sum keeps its labels and - // carries the value as the sample value; a grouped one ends with it. + // The inner aggregate's value column: a per-series one keeps its labels + // and carries the value as the sample value; a grouped one ends with it. let value = match inner_reduction { - Reduction::PerEntity => resolve_column_ref(&ColumnRef::SampleValue, &inner.schema).ok()?, + Reduction::PerEntity => { + resolve_column_ref(&ColumnRef::SampleValue, schema(memo, inner)).ok()? + } Reduction::Reduce(keys) if !keys.is_without() => keys.len(), Reduction::Reduce(_) => return None, }; - let summed = match col { - None => resolve_column_ref(&ColumnRef::SampleValue, &inner.schema).ok()?, - Some(column) => *column, + let read = match outer_measure.input_cols().first() { + Some(&column) => column, + None => resolve_column_ref(&ColumnRef::SampleValue, schema(memo, *child)).ok()?, + }; + if inner_column.get(read) != Some(&value) { + return None; + } + let outer_keys = by.keys(); + let by: Vec = outer_keys + .iter() + .map(|&key| inner_column.get(key).copied()) + .collect::>()?; + if by.contains(&value) { + return None; + } + // A renaming keeps the key names, so a state over its rows and one over + // the raw rows have the same columns. + let name = |group: MemoGroupId, column: ColumnId| { + schema(memo, group) + .fields + .get(column) + .map(|field| field.name.as_str()) }; - if summed != value || by.keys().contains(&value) { + if outer_keys + .iter() + .zip(&by) + .any(|(&outer_key, &inner_key)| name(*child, outer_key) != name(inner, inner_key)) + { return None; } - // A per-series sum drops the metric name, which the raw rows keep: - // grouping them by it would name groups the nested sums leave unnamed. if matches!(inner_reduction, Reduction::PerEntity) - && by.keys().iter().any(|&key| { - inner - .schema - .fields - .get(key) - .is_some_and(|f| f.name == "__name__") - }) + && by + .iter() + .any(|&key| name(inner, key).is_none_or(|name| name == "__name__")) { return None; } - let partitions = reduction.partitions_over(&inner.schema, &rows.schema)?; - Some((Rc::clone(rows), inner_sum.clone(), partitions)) + Some(NestedAggregates { + outer_measure, + by, + renaming, + inner, + inner_reduction, + inner_measure, + rows: *rows, + }) +} + +/// The input rows, the inner measure, the outer grouping (moved onto the +/// input rows by column, [`Reduction::partitions_over`]) and the +/// accumulator kind of a nested distributive merge of `target`, or `None` +/// when it does not apply: `target` and the aggregate beneath it +/// ([`nested_aggregates`]) are both `sum`, both `min` or both `max` +/// ([`distributive`]). +pub(crate) fn nested_distributive_input( + memo: &Memo, + target: MemoGroupId, +) -> Option<(MemoGroupId, AggIntent, Reduction, ExactKind)> { + let nested = nested_aggregates(memo, target)?; + let (kind, _) = distributive(nested.outer_measure)?; + if distributive(nested.inner_measure).map(|(inner_kind, _)| inner_kind) != Some(kind) { + return None; + } + let partitions = Reduction::by(nested.by) + .partitions_over(schema(memo, nested.inner), schema(memo, nested.rows))?; + Some((nested.rows, nested.inner_measure.clone(), partitions, kind)) } /// Whole-expression top-k (Example 1's Q2): a top-k over a per-item `sum` /// or `count` that is itself a target gets a fused computation -/// ([`ComputationTarget::fused_computation`]) absorbing the inner target, whose -/// candidates are the top-k's heap summaries (Count-Min and CountSketch -/// with a heap), each one heap over the inner aggregate's input, keyed by -/// the ranked item and weighted by the summed value. Those heaps over the -/// exact per-item result leave the top-k's own candidates: the fused -/// computation replaces them. Over a grouped sum of per-series sums or -/// counts of raw data samples, the heap reads those samples and absorbs the -/// per-series target too. Offered whatever else reads the inner aggregate: -/// it is one more candidate of the top-k's group, and the absorbed groups -/// keep their own candidates for their other consumers. Applied when neither -/// has a filter or `HAVING`, and when the keyed-additive rule realizes it -/// ([`whole_expression_input`]). -fn add_whole_expression_targets( - targets: &mut [ComputationTarget], - logical_nodes: &[Rc], -) { - let aggregate = |target: &ComputationTarget| &logical_nodes[target.aggregate_group.0 as usize]; +/// ([`ComputationTarget::fused_computation`]) absorbing the inner target, +/// whose candidates are the top-k's heap summaries (Count-Min and +/// CountSketch with a heap), each one heap over the inner aggregate's +/// input, keyed by the ranked item and weighted by the summed value. Those +/// heaps over the exact per-item result leave the top-k's own candidates: +/// the fused computation replaces them. Over a grouped sum of per-series +/// sums or counts of raw data samples, the heap reads those samples and +/// absorbs the per-series target too. Offered whatever else reads the inner +/// aggregate: the absorbed groups keep their own candidates for their other +/// consumers. Applied when neither has a filter or `HAVING`, and when the +/// keyed-additive rule realizes it ([`whole_expression_input`]). +fn add_whole_expression_targets(memo: &Memo, targets: &mut [ComputationTarget]) { for t in 0..targets.len() { let target = &targets[t]; - let Some(NonASAPOp::Aggregate { child, .. }) = aggregate(target).non_asap() else { - continue; - }; - let Some(inner) = targets - .iter() - .position(|other| Rc::ptr_eq(aggregate(other), child)) + let Operator::NonASAP(NonASAPOp::Aggregate { child, .. }) = + expression(memo, target.aggregate_group) else { continue; }; - if target.measure_filter.is_some() - || !target.having_filters.is_empty() - || targets[inner].measure_filter.is_some() - || !targets[inner].having_filters.is_empty() - { + if !targets.iter().any(|other| other.aggregate_group == *child) { + continue; + } + // Measure filters: `whole_expression_input` refuses them. + if has_having(memo, target.aggregate_group) || has_having(memo, *child) { continue; } - let Some((input, ..)) = whole_expression_input(aggregate(target)) else { + let Some((input, ..)) = whole_expression_input(memo, target.aggregate_group) else { continue; }; // A heap over the raw data samples beneath a grouped sum of per-series // sums or counts also absorbs the per-series target. - let mut absorbs = vec![inner]; - if let Some(NonASAPOp::Aggregate { + let mut absorbs = vec![*child]; + if let Operator::NonASAP(NonASAPOp::Aggregate { child: per_series, .. - }) = aggregate(&targets[inner]).non_asap() + }) = expression(memo, *child) { - let reads_below = per_series - .children() - .iter() - .any(|&rows| Rc::ptr_eq(rows, &input)); - if reads_below { - absorbs.extend( - targets - .iter() - .position(|other| Rc::ptr_eq(aggregate(other), per_series)), - ); + let reads_below = expression(memo, *per_series).children().contains(&&input); + if reads_below + && targets + .iter() + .any(|other| other.aggregate_group == *per_series) + { + absorbs.push(*per_series); } } let (heaps, own): (Vec<_>, Vec<_>) = @@ -704,8 +583,8 @@ fn add_whole_expression_targets( .iter() .cloned() .partition(|candidate| { - matches!(candidate, HowToComputeAggregateMeasure::Summary(family) - if family.capability().answers(StatisticKind::TopK)) + matches!(candidate, HowToComputeAggregateMeasure::Summary(algorithm) + if algorithm.capability().answers(StatisticKind::TopK)) }); if heaps.is_empty() { continue; @@ -713,7 +592,7 @@ fn add_whole_expression_targets( let target = &mut targets[t]; target.ways_to_compute = own; target.fused_computation = Some(FusedComputation { - absorbed_targets: absorbs, + absorbed_groups: absorbs, ways_to_compute: heaps, }); } @@ -722,14 +601,10 @@ fn add_whole_expression_targets( /// Prunes the own heap candidates of each PromQL top-k: the heap reads /// one row per item, so exact is no costlier; a fused whole-expression /// heap ([`add_whole_expression_targets`]) has already moved out of them. -fn prune_topk_heaps_over_one_row_per_item( - memo: &Memo, - targets: &mut [ComputationTarget], - logical_nodes: &[Rc], -) { +fn prune_topk_heaps_over_one_row_per_item(memo: &Memo, targets: &mut [ComputationTarget]) { for target in targets.iter_mut() { - let Some(NonASAPOp::Aggregate { measures, .. }) = - logical_nodes[target.aggregate_group.0 as usize].non_asap() + let Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) = + expression(memo, target.aggregate_group) else { continue; }; @@ -750,9 +625,9 @@ fn prune_topk_heaps_over_one_row_per_item( { continue; } - prune_own(&mut target.ways_to_compute, |candidate| { - matches!(candidate, HowToComputeAggregateMeasure::Summary(family) - if family.capability().answers(StatisticKind::TopK)) + target.ways_to_compute.retain(|candidate| { + !matches!(candidate, HowToComputeAggregateMeasure::Summary(algorithm) + if algorithm.capability().answers(StatisticKind::TopK)) }); } } @@ -760,50 +635,45 @@ fn prune_topk_heaps_over_one_row_per_item( /// The input, update and partitions of a whole-expression top-k over /// `target`'s inner aggregate, by the keyed-additive rule, or `None` when it /// does not apply. Rows that carry the full series identity rank it as a -/// column, as [`summary_update`] does. The partitions are `target`'s, moved +/// column, as `candidates::summary_update` does. The partitions are `target`'s, moved /// onto the input the heap reads ([`Reduction::partitions_over`]). -pub(super) fn whole_expression_input( - target: &OperatorNode, -) -> Option<(Rc, SummaryUpdate, Reduction)> { - use crate::summary_realization::realize_keyed_additive_summary_input; - let Some(NonASAPOp::Aggregate { +pub(crate) fn whole_expression_input( + memo: &Memo, + target: MemoGroupId, +) -> Option<(MemoGroupId, SummaryUpdate, Reduction)> { + let Operator::NonASAP(NonASAPOp::Aggregate { child, reduction, measures, filters, having: None, .. - }) = target.non_asap() + }) = expression(memo, target) else { return None; }; - let [intent @ AggIntent::TopK { .. }] = measures.as_slice() else { + let child = *child; + let [AggIntent::TopK { .. }] = measures.as_slice() else { return None; }; - if asap_types::ir::operator::non_asap::any_measure_filtered(filters) { + if any_measure_filtered(filters) { return None; } - // The rule reads only the family's algorithm, and rejects Count-Min over - // weights it cannot prove non-negative. Ask with CountSketch so one - // update serves both heap families; plan selection decides whether - // Count-Min is admissible, as for every other Count-Min candidate. - let family = FieldDataType::Sketch(SketchAlgorithm::CountSketchWithHeap); - let realized = realize_keyed_additive_summary_input(intent, &family, reduction, child)?; - let mut input = realized.input; + let (rows, mut input) = realize_keyed_additive_summary_input(memo, reduction, child)?; let per_series = matches!( - child.non_asap(), - Some(NonASAPOp::Aggregate { + expression(memo, child), + Operator::NonASAP(NonASAPOp::Aggregate { reduction: Reduction::PerEntity, .. }) ); - let partitions = reduction.partitions_over(&child.schema, &realized.child.schema)?; - if per_series && realized.child.schema.has_promql_series_identity() { + let partitions = reduction.partitions_over(schema(memo, child), schema(memo, rows))?; + if per_series && schema(memo, rows).has_promql_series_identity() { input.item = Some(asap_types::ir::schema::topk::series_identity_item( - &realized.child.schema, + schema(memo, rows), partitions.group_keys().map_or(&[][..], |keys| keys.keys()), )); - } else if realized.child.schema.closed + } else if schema(memo, rows).closed && matches!(input.item, Some(SummaryInputExpr::EntityIdentity(_))) { // An encoded label set needs an open PromQL schema. PromQL rows that @@ -812,87 +682,5 @@ pub(super) fn whole_expression_input( // keyed heap can consume raw rows without a per-key aggregate first. return None; } - Some((realized.child, input, partitions)) -} - -#[cfg(test)] -mod tests { - - use super::*; - - use asap_types::summary_type::{NonNegativeWeightProof, WeightDomain}; - - use asap_accuracy::test_support::estimate_has_bound; - - use asap_types::summary_type::SketchStatistic; - /// Approximate count keeps one exact option, its accumulator, beside the - /// universal summary; plain exact execution is not offered. - #[test] - fn approximate_count_keeps_one_exact_accumulator_and_universal_choices() { - let choices = computation_candidates_for_intent(&AggIntent::Count).candidates; - assert!(!choices.contains(&HowToComputeAggregateMeasure::Exact)); - assert_eq!( - choices[0], - HowToComputeAggregateMeasure::ExactAccumulator(vec![ExactKind::Count]) - ); - assert!(choices.contains(&HowToComputeAggregateMeasure::Summary( - SketchAlgorithm::UnivMon - ))); - } - - /// Count Sketch's signed counters give no total, so Pass 1 offers no - /// Count Sketch for a count, and every count candidate it offers - /// answers the total. - #[test] - fn a_count_offers_no_count_sketch() { - let choices = computation_candidates_for_intent(&AggIntent::Count).candidates; - assert!(!choices.contains(&HowToComputeAggregateMeasure::Summary( - SketchAlgorithm::CountSketch - ))); - let total = sketch_statistic(&AggIntent::Count).unwrap(); - for choice in &choices { - if let HowToComputeAggregateMeasure::Summary(algorithm) = choice { - assert!( - asap_types::summary_type::SummaryTypeCapability::of(&FieldDataType::Sketch( - *algorithm - )) - .answers(&total), - "{algorithm:?}" - ); - } - } - } - - /// A Count-Min estimate has a bound only over weights proven - /// non-negative: an open requirement (`RawDataSamplesOfMetric`) is not a proof. - #[test] - fn count_min_estimate_has_no_bound_over_an_open_requirement() { - let family = FieldDataType::Sketch(SketchAlgorithm::Cms); - let query = SketchStatistic::PointCount { - key: ColumnRef::SampleValue, - value: None, - }; - let with = |weight_domain| SummaryUpdate { - item: Some(SummaryInputExpr::Column(ColumnRef::SampleValue)), - weight: SummaryInputExpr::Column(ColumnRef::SampleValue), - weight_domain, - }; - assert!(!estimate_has_bound( - &family, - &with(WeightDomain::RawDataSamplesOfMetric { metric: "m".into() }), - &query - )); - assert!(!estimate_has_bound( - &family, - &with(WeightDomain::UnknownOrSigned), - &query - )); - assert!(estimate_has_bound( - &family, - &with(WeightDomain::NonNegative { - proof: NonNegativeWeightProof::CounterRawDataSamples - }), - &query - )); - } + Some((rows, input, partitions)) } diff --git a/crates/stage1-pass1-per-computation-candidates/src/lib.rs b/crates/stage1-pass1-per-computation-candidates/src/lib.rs index 3cb11c46a..0effe69fe 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/lib.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/lib.rs @@ -1,60 +1,73 @@ -//! `asap-stage1-pass1-per-computation-candidates` — #509 Stage 1, Pass 1: -//! per-computation candidate generation and the summary realizations it -//! offers. Its one entry is [`pass1_memo`], which fills the -//! memo groups of Stage 0's [`Memo`](asap_types::stages::Memo) with their -//! initial candidates; Pass 2 extends that memo. +//! `asap-stage1-pass1-per-computation-candidates` — Stage 1, Pass 1: +//! each memo group's initial candidates. Its one entry is [`pass1_memo`], +//! which fills the memo groups of Stage 0's +//! [`Memo`] with their initial candidates (exact, +//! exact accumulator, one summary build per listed parameter configuration +//! with separate readouts, fused builds), every intermediate result its own +//! group; Pass 2 extends that memo. //! //! It depends only on `asap-types` (its input and output memo are in -//! `asap_types::stages`) and the shared accuracy model (`asap-accuracy`). -//! It depends on no other stage crate, and the planner facade calls it -//! after Stage 0. It depends on no query-language frontend either; its own -//! tests lower PromQL through `asap-frontend-promql` (a dev-dependency). -//! The `test-support` feature exports the Pass 1 internals other crates' -//! tests call (`test_support`). +//! `asap_types::stages`) and the shared accuracy model (`asap-accuracy`, +//! for the statistic each intent reads). It depends on no other stage +//! crate, and the planner facade calls it after Stage 0. It depends on no +//! query-language frontend either; its tests build their input memo through +//! `Memo::find_or_add_group` and `Memo::add_query`. //! -//! Accuracy guarantees come from the built-in analytical accuracy rules in -//! `asap-accuracy` (per-family estimators, composition and budget -//! allocation). They derive a machine-readable -//! [`AccuracyGuarantee`](asap_types::accuracy::AccuracyGuarantee) -//! for every finalized value and propagate it through -//! approximate-over-approximate compositions under conservative rules (no -//! independence assumptions, unknown statistics stay unknown). A -//! composition with no rule leaves the guarantee `None` and keeps the -//! candidate. Pass 1 prunes nothing for accuracy; Pass 2 gives each readout -//! its required accuracy and eliminates the candidates no query can use, -//! with the deployment's measured accuracy (`AccuracyEvidence`) read before -//! each summary's theoretical guarantee. +//! Pass 1 reads no accuracy target and sets no input requirement: the error +//! of each build follows from its parameters (`parameter_list`), and Pass 2 +//! gives each readout its required accuracy, decides the logical edges and +//! eliminates the candidates no query can use. -/// Stage 1, Pass 1's computation targets. No execution timing is assigned: that is a Stage 2 -/// materialization decision. Its target list -/// (`PerComputationCandidates`) is Pass 1's working form, public only to -/// tests (`crate::test_support`, feature `test-support`). +/// Stage 1, Pass 1's candidates: each way to compute a group, added to the +/// memo for the computation targets. +mod candidates; +/// Stage 1, Pass 1's computation targets over the memo groups. mod computation_targets; -/// The summary families that can serve an aggregate intent, the input a -/// summary consumes and the column a top-k ranks. +/// How a summary realizes an aggregate intent: the sketch algorithms that +/// serve it, the input a summary consumes and the keyed heap over a larger +/// sub-expression. mod summary_realization; /// Fixtures this crate's own tests share. #[cfg(test)] mod test_fixtures; -/// Test helpers other crates' tests call (feature `test-support`). -#[cfg(any(test, feature = "test-support"))] -pub mod test_support; -/// Frontend-to-Pass-1 acceptance tests over Pass 1's working form. +/// Pass 1's tests over memos built through the `Memo` methods. #[cfg(test)] mod tests; use asap_types::deployment_capabilities::SupportedSummary; -use asap_types::stages::Memo; -use computation_targets::generate_per_computation_candidates; -pub use computation_targets::PerComputationCandidateError; +use asap_types::ir::schema::Schema; +use asap_types::ir::{Operator, SchemaDerivationError}; +use asap_types::stages::{ + CandidateError, LogicalPropertiesError, Memo, MemoGroupError, MemoGroupId, +}; +use thiserror::Error; -/// Why [`pass1_memo`] failed. -#[derive(Debug, thiserror::Error)] -pub enum Pass1Error { - /// A query's DAG cannot be planned: it already holds ASAP or physical - /// annotations, or a measure's accuracy target is invalid. +use candidates::add_pass1_candidates; +use computation_targets::computation_targets; + +/// Why Pass 1 could not add a group's candidates. +#[derive(Debug, Error)] +pub enum PerComputationCandidateError { + /// A query's DAG breaks the node rules (the planner facade's + /// `QueryRoot::validate_structure` before Stage 0). + #[error(transparent)] + Structure(#[from] SchemaDerivationError), + /// A group Pass 1 built is not valid over its input groups + /// (`Memo::find_or_add_group`): a bug in the rule that built it. + #[error(transparent)] + MemoGroup(#[from] MemoGroupError), + #[error("logical candidate input already contains ASAP operators")] + ContainsAsap, + /// A candidate Pass 1 built breaks the node rules or does not output + /// its group's result: a bug in the rule that built it. + #[error(transparent)] + Candidate(#[from] CandidateError), + /// A candidate Pass 1 built has logical properties that cannot go + /// together: a bug in the rule that built it. #[error(transparent)] - PerComputation(#[from] PerComputationCandidateError), + LogicalProperties(#[from] LogicalPropertiesError), + #[error("unsupported substitution in logical ASAP-aware optimization: {0}")] + Unsupported(&'static str), } /// Stage 1, Pass 1: the initial candidates of the memo groups of `memo` @@ -64,14 +77,26 @@ pub enum Pass1Error { /// (`supported_summaries`, the deployment's /// `DeploymentCapabilities::supported_summaries`; `None` supports every /// one), and adds each way to compute a group as candidates, through -/// `Memo::find_or_add_group` and `Memo::add_candidate`. Accuracy prunes -/// nothing here: Pass 2's dead-candidate elimination does. +/// `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. +/// Accuracy prunes nothing here: Pass 2 gives each readout its required +/// accuracy and eliminates the candidates no query can use. pub fn pass1_memo( - memo: Memo, + mut memo: Memo, supported_summaries: Option<&[SupportedSummary]>, -) -> Result { - let per_computation = generate_per_computation_candidates(&memo)? - .without_unsupported_summaries(supported_summaries); - let _ = (memo, per_computation); - todo!("#1207 PR 3: add each way to compute as candidates, one per listed θ") +) -> Result { + let targets = computation_targets(&memo, supported_summaries)?; + add_pass1_candidates(&mut memo, &targets)?; + Ok(memo) +} + +/// The expression of group `group`. +fn expression(memo: &Memo, group: MemoGroupId) -> &Operator { + &memo.groups()[group.0 as usize].expression +} + +/// The output schema of group `group`. +fn schema(memo: &Memo, group: MemoGroupId) -> &Schema { + &memo.groups()[group.0 as usize].group_properties.schema } diff --git a/crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs b/crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs index 9736265d2..4d86fa54a 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/summary_realization.rs @@ -1,28 +1,33 @@ -//! Summary realization helpers of Pass 1 (`computation_targets`): -//! which sketch kinds can serve an intent, -//! the column/tuple a summary consumes, the column a top-k ranks, and the -//! keyed-additive rule for a heap sketch that reads a larger sub-DAG. +//! How a summary realizes an aggregate intent in Pass 1: the sketch +//! algorithms that serve the intent, what a measure's state reads from each +//! row and the update each row contributes, the column a top-k ranks, and +//! the keyed-additive rule for a heap sketch that reads a larger +//! sub-expression. use asap_types::ir::operator::agg_intent::AggIntent; +use asap_types::ir::operator::non_asap::any_measure_filtered; use asap_types::ir::operator::Reduction; -use asap_types::ir::scalar::column_resolution::resolve_column_ref; +use asap_types::ir::scalar::column_resolution::{resolve_column_ref, ResolveError}; use asap_types::ir::scalar::expr_ir::ColumnRef; -use asap_types::ir::schema::{Field, FieldDataType}; -use asap_types::ir::{NonASAPOp, OperatorNode}; -#[cfg(test)] -use asap_types::ir::{Operator, ScalarExpr}; +use asap_types::ir::schema::{DataType, Field, FieldDataType, Schema}; +use asap_types::ir::{NonASAPOp, Operator, OperatorResultKind, Predicate, ScalarExpr}; +use asap_types::stages::{ + ranked_column_of_group, raw_data_samples_of_metric_of_group, Memo, MemoGroupId, +}; use asap_types::summary_type::{ EntityIdentity, NonNegativeWeightProof, SketchAlgorithm, SummaryInputExpr, SummaryTypeCapability, SummaryUpdate, WeightDomain, }; -use std::rc::Rc; use asap_accuracy::sizing::sketch_statistic; -/// The sketch families the planner sizes and offers, in the order Pass 1 -/// offers those that answer an intent's statistic: the specialized families +use crate::computation_targets::nested_aggregates; +use crate::{expression, schema, PerComputationCandidateError}; + +/// The sketch algorithms the planner sizes and offers, in the order Pass 1 +/// offers those that answer an intent's statistic: the specialized algorithms /// before the universal UnivMon. -const FAMILY_PREFERENCE: &[SketchAlgorithm] = &[ +const ALGORITHM_PREFERENCE: &[SketchAlgorithm] = &[ SketchAlgorithm::Kll, SketchAlgorithm::DDSketch, SketchAlgorithm::Hll, @@ -40,88 +45,103 @@ const FAMILY_PREFERENCE: &[SketchAlgorithm] = &[ /// count. Empty for an intent no sketch /// statistic serves. pub(crate) fn summary_candidates(intent: &AggIntent) -> Vec { - candidates_by(intent, |algorithm| { - SummaryTypeCapability::of(&FieldDataType::Sketch(*algorithm)) - }) -} - -/// [`summary_candidates`] with each algorithm's table row read from `capability`. -fn candidates_by( - intent: &AggIntent, - capability: impl Fn(&SketchAlgorithm) -> SummaryTypeCapability, -) -> Vec { let Some(statistic) = sketch_statistic(intent) else { return Vec::new(); }; // A distinct-tuple count hashes the whole tuple as one item // (`SummaryInputExpr::Tuple`), which the distinct-count sketches take // unchanged. UnivMon is dropped there: it estimates frequency moments - // over a single value stream, and `realize_value_frequency_summary_input` - // would feed it one column of the tuple. + // over a single value stream, and would be fed one column of the tuple. let tuple = matches!(intent, AggIntent::Cardinality { cols, .. } if cols.len() > 1); - FAMILY_PREFERENCE + ALGORITHM_PREFERENCE .iter() - .filter(|family| capability(family).answers(&statistic)) - .filter(|family| !(tuple && **family == SketchAlgorithm::UnivMon)) + .filter(|algorithm| { + SummaryTypeCapability::of(&FieldDataType::Sketch(**algorithm)).answers(&statistic) + }) + .filter(|algorithm| !(tuple && **algorithm == SketchAlgorithm::UnivMon)) .cloned() .collect() } -/// The physical input consumed by one summary realization. Most summaries -/// consume the logical aggregate's immediate child and summarize its declared -/// input value. Composite realizations can instead consume a larger -/// logical sub-DAG and bind a different key or value. -pub(crate) struct PhysicalSummaryInput { - pub(crate) child: Rc, - pub(crate) input: SummaryUpdate, +/// The column a top-k ranks group `child` by ([`ranked_column_of_group`]), +/// as a reference: the sample value when it is that column, else the column +/// by name. +pub(crate) fn ranked_value(memo: &Memo, child: MemoGroupId) -> Result { + let ranked = ranked_column_of_group(memo, child)?; + Ok( + match resolve_column_ref(&ColumnRef::SampleValue, schema(memo, child)) { + Ok(value) if value == ranked => ColumnRef::SampleValue, + _ => schema(memo, child).fields[ranked].column_ref(), + }, + ) } -/// Realize the composite heavy-hitter realization for -/// `TopK(Count GROUP BY key)`. The heap sketch consumes the raw keyed stream; -/// it does not consume an independently materialized Count result. `None` -/// when the rule does not apply or the shape is unsupported (each reason is -/// noted where it returns). -pub(crate) fn realize_keyed_additive_summary_input( +/// What the summary consumes per input row. An intent that reads one column +/// feeds that column by name, or the sample value when it reads none or its +/// column is outside the child schema; `COUNT(DISTINCT a, b)` feeds the whole +/// tuple as one item, so the distinct-count sketch hashes `(a, b)` rather +/// than `a` — the difference between tuple cardinality and single-column +/// cardinality. +/// +/// A tuple leg outside the child schema gives `None` rather than the +/// sample-value fallback: a leg has no sample-value reading, and silently +/// dropping one would under-count. +pub(crate) fn summarised_input( intent: &AggIntent, - family: &FieldDataType, - output_reduction: &Reduction, - child: &Rc, -) -> Option { - if !matches!(intent, AggIntent::TopK { .. }) { - return None; + child_schema: &Schema, +) -> Option { + let cols = intent.input_cols(); + if cols.len() < 2 { + let column = cols + .first() + .and_then(|id| child_schema.fields.get(*id)) + .map_or(ColumnRef::SampleValue, Field::column_ref); + return Some(SummaryInputExpr::Column(column)); } - let FieldDataType::Sketch(kind) = family else { - return None; - }; - let heap_algorithm = kind; - if !matches!( - heap_algorithm, - SketchAlgorithm::CmsWithHeap | SketchAlgorithm::CountSketchWithHeap - ) { - return None; - } - let Some(NonASAPOp::Aggregate { + let legs = cols + .iter() + .map(|id| child_schema.fields.get(*id).map(Field::column_ref)) + .collect::>>()?; + Some(SummaryInputExpr::Tuple( + legs.into_iter().map(SummaryInputExpr::Column).collect(), + )) +} + +/// The keyed-additive rule for a heap top-k over aggregate group `child` +/// (`TopK(Count GROUP BY key)`, `TopK(Sum GROUP BY key)`): the group the heap +/// reads and its update, one keyed heap over the raw rows rather than over +/// an independently materialized per-item result. The update serves both +/// heap algorithms; whether Count-Min is admissible over its weights is plan +/// selection's question. `None` when the rule does not apply or the shape is +/// unsupported (each reason is noted where it returns). +pub(crate) fn realize_keyed_additive_summary_input( + memo: &Memo, + output_reduction: &Reduction, + child: MemoGroupId, +) -> Option<(MemoGroupId, SummaryUpdate)> { + let Operator::NonASAP(NonASAPOp::Aggregate { reduction, measures, filters, having: None, child: raw_child, .. - }) = child.non_asap() + }) = expression(memo, child) else { return None; }; + let raw_child = *raw_child; // The heap sketch consumes every raw row; a filtered measure counts only - // some of them (#466). - if asap_types::ir::operator::non_asap::any_measure_filtered(filters) { + // some of them. + if any_measure_filtered(filters) { return None; } // A grouped sum of per-series `rate`/`increase`/`irate` values: the // metric they derive from, whose declared type decides their sign. - let derivative_of = match (measures.as_slice(), raw_child.non_asap()) { + let derivative_of = match (measures.as_slice(), expression(memo, raw_child)) { ( [AggIntent::Sum { .. }], - Some(NonASAPOp::Aggregate { + Operator::NonASAP(NonASAPOp::Aggregate { measures: derivative, child: samples, .. @@ -131,9 +151,7 @@ pub(crate) fn realize_keyed_additive_summary_input( [AggIntent::Rate | AggIntent::Increase | AggIntent::IRate] ) => { - Some(asap_accuracy::propagation::raw_data_samples_of_metric( - samples, - )) + Some(raw_data_samples_of_metric_of_group(memo, *samples)) } _ => None, }; @@ -141,7 +159,7 @@ pub(crate) fn realize_keyed_additive_summary_input( // `sum by (G) (sum_over_time(m[W]))` or `... count_over_time ...`: the // grouped sum of per-series sums (counts) of raw data samples is their sum // (count) by `G`, so the heap reads those samples. - let samples = summed_per_series_samples(child); + let samples = summed_per_series_samples(memo, child); // A raw data sample's count or a count's row weighs one. let counted = match &samples { Some((_, inner)) => matches!(inner, AggIntent::Count), @@ -154,7 +172,11 @@ pub(crate) fn realize_keyed_additive_summary_input( } [AggIntent::Sum { col }] => SummaryInputExpr::Column(match col { None => ColumnRef::SampleValue, - Some(index) => match raw_child.schema.fields.get(*index).map(Field::column_ref) { + Some(index) => match schema(memo, raw_child) + .fields + .get(*index) + .map(Field::column_ref) + { Some(column) => column, None => { // Unsupported: sum-ranked Top-K value column is outside the raw input schema. @@ -171,20 +193,16 @@ pub(crate) fn realize_keyed_additive_summary_input( Some(Some(metric)) => WeightDomain::CounterDerivativeOfMetric { metric }, _ => WeightDomain::UnknownOrSigned, }; - if matches!(heap_algorithm, SketchAlgorithm::CmsWithHeap) - && !matches!( - weight_domain, - WeightDomain::NonNegative { .. } | WeightDomain::CounterDerivativeOfMetric { .. } - ) - { - // Unsupported: value-weighted CMS requires non-negative update evidence; use CountSketch for arbitrary values. - return None; - } let subpopulation_columns = match output_reduction { Reduction::PerEntity => vec![], Reduction::Reduce(keys) => keys .iter() - .filter_map(|index| child.schema.fields.get(*index).map(Field::column_ref)) + .filter_map(|index| { + schema(memo, child) + .fields + .get(*index) + .map(Field::column_ref) + }) .collect(), }; let item = match reduction { @@ -194,7 +212,12 @@ pub(crate) fn realize_keyed_additive_summary_input( Reduction::Reduce(keys) if !keys.is_without() && !keys.is_empty() => { let Some(columns) = keys .iter() - .map(|index| raw_child.schema.fields.get(*index).map(Field::column_ref)) + .map(|index| { + schema(memo, raw_child) + .fields + .get(*index) + .map(Field::column_ref) + }) .collect::>>() else { // Unsupported: ranked item column is outside the raw input schema. @@ -223,176 +246,228 @@ pub(crate) fn realize_keyed_additive_summary_input( return None; } }; - Some(PhysicalSummaryInput { - child: samples.map_or_else(|| Rc::clone(raw_child), |(rows, _)| rows), - input: SummaryUpdate { + Some(( + samples.map_or(raw_child, |(rows, _)| rows), + SummaryUpdate { item: Some(item), weight, weight_domain, }, - }) + )) } /// The raw data sample rows and the per-series `sum` or `count` over them when -/// `grouped` is a grouped `sum` (not by `without`, nor by the metric name -/// the per-series result drops) of the value of a per-series `sum` or -/// `count` of raw data samples (`sum by (G) (sum_over_time(m[W]))`), neither -/// filtered nor with `HAVING`; `None` otherwise. The grouped sum is then the -/// sum (count) of those samples by `G`. -fn summed_per_series_samples(grouped: &OperatorNode) -> Option<(Rc, AggIntent)> { - use asap_types::ir::operator::non_asap::any_measure_filtered; - let Some(NonASAPOp::Aggregate { - reduction: Reduction::Reduce(by), - measures, - filters, - having: None, - child: per_series, - .. - }) = grouped.non_asap() - else { - return None; - }; - let [AggIntent::Sum { col }] = measures.as_slice() else { - return None; - }; - let Some(NonASAPOp::Aggregate { - reduction: Reduction::PerEntity, - measures: inner, - filters: inner_filters, - having: None, - child: rows, - .. - }) = per_series.non_asap() - else { - return None; - }; - let [inner @ (AggIntent::Sum { col: None } | AggIntent::Count)] = inner.as_slice() else { - return None; - }; - if by.is_without() - || any_measure_filtered(filters) - || any_measure_filtered(inner_filters) - || matches!(rows.non_asap(), Some(NonASAPOp::Aggregate { .. })) +/// `grouped` is a grouped `sum` of the value of a per-series `sum` or +/// `count` of raw data samples (`sum by (G) (sum_over_time(m[W]))`), read +/// directly ([`nested_aggregates`]); `None` otherwise. The grouped sum is +/// then the sum (count) of those samples by `G`. +fn summed_per_series_samples( + memo: &Memo, + grouped: MemoGroupId, +) -> Option<(MemoGroupId, AggIntent)> { + let nested = nested_aggregates(memo, grouped)?; + if nested.renaming.is_some() + || !matches!(nested.outer_measure, AggIntent::Sum { .. }) + || !matches!(nested.inner_reduction, Reduction::PerEntity) + || !matches!( + nested.inner_measure, + AggIntent::Sum { col: None } | AggIntent::Count + ) + || matches!( + expression(memo, nested.rows), + Operator::NonASAP(NonASAPOp::Aggregate { .. }) + ) { return None; } - // The grouped sum reads the per-series value. - let value = resolve_column_ref(&ColumnRef::SampleValue, &per_series.schema).ok()?; - if col.is_some_and(|col| col != value) || by.keys().contains(&value) { - return None; - } - if by.keys().iter().any(|&key| { - per_series - .schema - .fields - .get(key) - .is_none_or(|field| field.name == "__name__") - }) { - return None; - } - Some((Rc::clone(rows), inner.clone())) + Some((nested.rows, nested.inner_measure.clone())) } -#[cfg(test)] -mod tests { - use super::*; - use crate::test_fixtures::metric_scan; - use asap_types::ir::scalar::{CompareOpKind, ScalarValue}; - use asap_types::ir::{ExprSemantics, Predicate}; - - /// A heap sketch consumes every raw row, so the keyed input rule refuses - /// a TopK over a filtered count. - #[test] - fn keyed_heap_input_refuses_a_filtered_count() { - let count_by_job = |filter: Option| { - OperatorNode::new_shared(Operator::NonASAP(NonASAPOp::Aggregate { - reduction: Reduction::by(vec![2]), - measures: vec![AggIntent::Count], - output_names: vec![], - filters: vec![filter], - having: None, - child: metric_scan(&["job"]), - })) - .unwrap() - }; - let intent = AggIntent::TopK { k: 5 }; - let family = FieldDataType::Sketch(SketchAlgorithm::CmsWithHeap); - let output = Reduction::Reduce(asap_types::ir::operator::arguments::GroupKeys::none()); - assert!(realize_keyed_additive_summary_input( - &intent, - &family, - &output, - &count_by_job(None) - ) - .is_some()); - let value_above_one = Predicate(ScalarExpr::Compare { - left: Box::new(ScalarExpr::Column(1)), - op: CompareOpKind::Gt, - right: Box::new(ScalarExpr::Literal(ScalarValue::Float64(1.0))), - semantics: ExprSemantics::Promql, - }); - assert!(realize_keyed_additive_summary_input( - &intent, - &family, - &output, - &count_by_job(Some(value_above_one)) - ) - .is_none()); +/// `update` with the open requirement that its weights are samples of +/// `metric` ([`WeightDomain::RawDataSamplesOfMetric`]), when it is a keyed heap +/// update whose weights are not otherwise proven. +pub(crate) fn with_raw_data_samples_requirement( + mut update: SummaryUpdate, + metric: Option<&str>, +) -> SummaryUpdate { + if let Some(metric) = metric { + if update.item.is_some() && update.weight_domain == WeightDomain::UnknownOrSigned { + update.weight_domain = WeightDomain::RawDataSamplesOfMetric { + metric: metric.to_string(), + }; + } } + update +} - /// Each approximable intent is offered the families it was offered when - /// the list was written by hand, in the same order; a non-sketch intent - /// is offered none. - #[test] - fn summary_candidates_keep_the_hand_written_lists() { - use SketchAlgorithm as S; - let cardinality = |cols: Vec| AggIntent::Cardinality { cols }; - let cases = [ - ( - AggIntent::Quantile { col: None, q: 0.99 }, - vec![S::Kll, S::DDSketch], - ), - (cardinality(vec![]), vec![S::Hll, S::Kmv, S::UnivMon]), - (cardinality(vec![1]), vec![S::Hll, S::Kmv, S::UnivMon]), - (cardinality(vec![1, 2]), vec![S::Hll, S::Kmv]), - (AggIntent::FrequencyL2 { col: None }, vec![S::UnivMon]), - (AggIntent::FrequencyEntropy { col: None }, vec![S::UnivMon]), - ( - AggIntent::TopK { k: 10 }, - vec![S::CmsWithHeap, S::CountSketchWithHeap], - ), - (AggIntent::Count, vec![S::Cms, S::UnivMon]), - (AggIntent::Sum { col: None }, vec![]), - ]; - for (intent, want) in cases { - assert_eq!(summary_candidates(&intent), want, "{intent:?}"); +/// What a measure's state reads from each row of `input`, resolvable there. +/// A SQL `count` reads [`counted_column`]; any other measure, a PromQL count +/// included, reads its input column (the sample value when it names none). +pub(crate) fn measure_input( + intent: &AggIntent, + memo: &Memo, + input: MemoGroupId, + filter: Option<&Predicate>, +) -> Result { + let schema = schema(memo, input); + let read = match intent { + AggIntent::Count + if memo.groups()[input.0 as usize].group_properties.result_kind + == OperatorResultKind::Relation => + { + SummaryInputExpr::Column(counted_column(schema, filter)?) + } + // A top-k ranks its child's aggregate output, not a column of its own. + AggIntent::TopK { .. } => { + SummaryInputExpr::Column(ranked_value(memo, input).map_err(|_| { + PerComputationCandidateError::Unsupported("Top-K has no ranked column") + })?) } + _ => summarised_input(intent, schema).ok_or(PerComputationCandidateError::Unsupported( + "input column outside child schema", + ))?, + }; + if let SummaryInputExpr::Column(column) = &read { + resolve_column_ref(column, schema).map_err(|_| { + PerComputationCandidateError::Unsupported("summary input column does not resolve") + })?; } + Ok(read) +} - /// Dropping a readout from a family's table row drops the family from - /// the candidates of the intents that read it, with no other edit. - #[test] - fn a_dropped_readout_drops_the_family() { - // Count-Min-with-heap answered from Count-Min's row: no top-k readout. - let heap_without_top_k = |family: &SketchAlgorithm| { - SummaryTypeCapability::of(&FieldDataType::Sketch(match family { - SketchAlgorithm::CmsWithHeap => SketchAlgorithm::Cms, - other => *other, - })) - }; - let top_k = AggIntent::TopK { k: 10 }; - assert_eq!( - candidates_by(&top_k, heap_without_top_k), - vec![SketchAlgorithm::CountSketchWithHeap] - ); +/// The column a SQL `count` state updates on. The runtime skips NULL updates, +/// so it is a column non-null on every counted row: one the measure filter +/// proves non-null (`count(col)` lowers to the filter `col IS NOT NULL`), else +/// a non-nullable one, Float64 first (the runtime's numeric update). +fn counted_column( + schema: &Schema, + filter: Option<&Predicate>, +) -> Result { + fn not_null(expr: &ScalarExpr) -> Vec { + match expr { + ScalarExpr::IsNotNull(inner) => match **inner { + ScalarExpr::Column(column) => vec![column], + _ => vec![], + }, + ScalarExpr::BoolAnd(conjuncts) => conjuncts.iter().flat_map(not_null).collect(), + _ => vec![], + } } + let non_nullable = |float: bool| { + schema + .fields + .iter() + .enumerate() + .filter_map(move |(id, field)| { + (!field.nullable + && (!float || field.dtype == FieldDataType::Plain(DataType::Float64))) + .then_some(id) + }) + }; + let reference = |id: usize| { + schema + .fields + .get(id) + .map(asap_types::ir::schema::Field::column_ref) + }; + filter + .map_or_else(Vec::new, |filter| not_null(&filter.0)) + .into_iter() + .chain(non_nullable(true)) + .chain(non_nullable(false)) + .find_map(|id| { + reference(id).filter(|column| resolve_column_ref(column, schema).ok() == Some(id)) + }) + .ok_or(PerComputationCandidateError::Unsupported( + "SQL count over rows with no column known to be non-null", + )) +} - /// The preference order names each family it offers once. - #[test] - fn preference_order_names_each_family_once() { - let mut seen = std::collections::HashSet::new(); - for family in FAMILY_PREFERENCE { - assert!(seen.insert(family), "{family:?} twice"); +/// What each input row contributes, given what the measure reads +/// ([`measure_input`]): a heap sketch ranks one item per row (the series +/// identity, the columns outside the partition and the ranked value, or the +/// PromQL label set outside the partition), weighted by the ranked value; +/// UnivMon and a Count-Min count count each value once; every other summary +/// type reads the measure's input. +pub(crate) fn summary_update( + intent: &AggIntent, + summary_type: &FieldDataType, + reduction: &Reduction, + child: &Schema, + weight: SummaryInputExpr, +) -> Result { + let algorithm = match summary_type { + FieldDataType::Sketch(kind) => Some(kind), + _ => None, + }; + Ok(match (intent, algorithm) { + (AggIntent::TopK { .. }, Some(_)) => { + if reduction.group_keys().is_some_and(|keys| keys.is_without()) { + return Err(PerComputationCandidateError::Unsupported( + "Top-K partitions given by `without`", + )); + } + let groups: Vec = reduction + .group_keys() + .into_iter() + .flat_map(|keys| keys.iter().copied()) + .collect(); + let item = if child.has_promql_series_identity() { + asap_types::ir::schema::topk::series_identity_item(child, &groups) + } else if child.closed { + // A closed child (an aggregate's output, say) lists every + // column: the item is its columns outside the partition and + // the ranked value. + let SummaryInputExpr::Column(ranked) = &weight else { + return Err(PerComputationCandidateError::Unsupported( + "Top-K ranked value is not a column", + )); + }; + let value = resolve_column_ref(ranked, child).map_err(|_| { + PerComputationCandidateError::Unsupported("Top-K ranked value does not resolve") + })?; + let items: Vec<_> = child + .fields + .iter() + .enumerate() + .filter(|(index, _)| *index != value && !groups.contains(index)) + .map(|(_, field)| SummaryInputExpr::Column(field.column_ref())) + .collect(); + if items.is_empty() { + return Err(PerComputationCandidateError::Unsupported( + "Top-K item has no label outside its partition", + )); + } + SummaryInputExpr::Tuple(items) + } else { + let excluding = groups + .iter() + .filter_map(|&index| child.fields.get(index)) + .map(asap_types::ir::schema::Field::column_ref) + .collect(); + SummaryInputExpr::EntityIdentity(EntityIdentity::PromqlLabelSet { excluding }) + }; + SummaryUpdate { + item: Some(item), + // The ranked value ([`measure_input`]). + weight, + // Not proven non-negative; selection decides whether CMS is admissible. + weight_domain: WeightDomain::UnknownOrSigned, + } } - } + (_, Some(SketchAlgorithm::UnivMon)) | (AggIntent::Count, Some(SketchAlgorithm::Cms)) => { + SummaryUpdate { + item: Some(weight), + weight: SummaryInputExpr::Constant(1.0), + weight_domain: WeightDomain::NonNegative { + proof: NonNegativeWeightProof::UnitCount, + }, + } + } + _ => SummaryUpdate { + item: None, + weight, + weight_domain: WeightDomain::UnknownOrSigned, + }, + }) } diff --git a/crates/stage1-pass1-per-computation-candidates/src/test_fixtures.rs b/crates/stage1-pass1-per-computation-candidates/src/test_fixtures.rs index 2199f7894..bb0ec22e0 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/test_fixtures.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/test_fixtures.rs @@ -1,49 +1,57 @@ -//! Fixtures this crate's own tests share. Every builder returns an -//! `Rc` whose schema is derived by `OperatorNode::new_shared`, -//! so a fixture is exactly what a front end would hand the planner. +//! Fixtures this crate's own tests share. The memo builders add Stage 0's +//! groups through `Memo::find_or_add_group` and `Memo::add_query`, as +//! Stage 0 does, so no test calls another stage crate. The expressions +//! come from `asap_types::test_support::memo_fixtures`; its scans list Utf8 +//! labels. -use std::rc::Rc; +use asap_types::ir::operator::arguments::Reduction; +use asap_types::ir::operator::AggIntent; +use asap_types::ir::schema::series_identity::with_promql_series_identity; +use asap_types::ir::schema::DataType; +use asap_types::ir::{NonASAPOp, Operator, OperatorNode, Predicate, QueryRoot}; +use asap_types::stages::{Memo, MemoGroupId, MemoQuery}; +use asap_types::test_support::memo_fixtures::{aggregate_with, scan}; -use asap_types::ir::operator::arguments::Source; -use asap_types::ir::schema::{ColumnId, DataType, Field, Schema}; -use asap_types::ir::{NonASAPOp, OperatorNode}; - -/// A `TimeSeries("m")` scan over `[ts(0), value(1), labels...]`, time index 0, -/// no unique key. -pub fn metric_scan(labels: &[&str]) -> Rc { - metric_scan_with_keys(labels, vec![]) +/// The group of `operator`, added as Stage 0 adds it. +pub fn group(memo: &mut Memo, operator: Operator) -> MemoGroupId { + memo.find_or_add_group(operator).unwrap() } -/// [`metric_scan`] with explicit `unique_keys` (a `[[0]]` key makes CSE -/// willing to hoist the scan). -pub fn metric_scan_with_keys(labels: &[&str], unique_keys: Vec>) -> Rc { - let mut columns = vec![ - Field::plain("ts", DataType::Timestamp, false), - Field::plain("value", DataType::Float64, false), - ]; - columns.extend( - labels - .iter() - .map(|n| Field::plain(*n, DataType::Utf8, true)), - ); - scan("m", Schema::with_time_index(columns, 0, unique_keys)) +/// The group of a `TimeSeries(metric)` scan listing `labels`, its series +/// identity realized as the planner realizes it before Stage 0 +/// (`with_promql_series_identity`): a closed schema whose last column is +/// `$promql_series_identity`, keyed by it and the timestamp. +pub fn scan_group(memo: &mut Memo, metric: &str, labels: &[&str]) -> MemoGroupId { + let labels: Vec<(&str, DataType)> = labels.iter().map(|l| (*l, DataType::Utf8)).collect(); + let mut operator = scan(metric, &labels, vec![]); + let open = + OperatorNode::new_shared(operator.map_children(|_| unreachable!("a scan has no input"))) + .unwrap(); + let realized = with_promql_series_identity(&open).unwrap().schema.clone(); + if let Operator::NonASAP(NonASAPOp::Scan { schema, .. }) = &mut operator { + *schema = realized; + } + group(memo, operator) } -/// A predicate-free `TimeSeries(metric)` scan with the given schema. -pub fn scan(metric: &str, schema: Schema) -> Rc { - scan_from( - Source::TimeSeries { - metric: metric.into(), - }, - schema, - ) +/// The group of an `Aggregate` of `measures` (unnamed, unfiltered) over +/// `child`, grouped by `reduction`, with `having`. +pub fn aggregate_group( + memo: &mut Memo, + child: MemoGroupId, + reduction: Reduction, + measures: Vec, + having: Option>, +) -> MemoGroupId { + let measures = measures.into_iter().map(|m| (m, None)).collect(); + group(memo, aggregate_with(reduction, measures, having, child)) } -pub fn scan_from(source: Source, schema: Schema) -> Rc { - OperatorNode::new_shared(asap_types::ir::Operator::NonASAP(NonASAPOp::Scan { - source, - predicates: vec![], - schema, - })) - .unwrap() +/// Adds a query whose root is group `root`. +pub fn query(memo: &mut Memo, root: MemoGroupId) -> usize { + memo.add_query(MemoQuery { + root: QueryRoot::Operator(root), + accuracy_target: None, + number_of_values_per_query_evaluation: None, + }) } diff --git a/crates/stage1-pass1-per-computation-candidates/src/test_support.rs b/crates/stage1-pass1-per-computation-candidates/src/test_support.rs deleted file mode 100644 index 0e3b166a7..000000000 --- a/crates/stage1-pass1-per-computation-candidates/src/test_support.rs +++ /dev/null @@ -1,4 +0,0 @@ -//! The Pass 1 internals other crates' tests call (feature `test-support`): -//! Pass 1's working form and single-candidate composition. - -pub use crate::computation_targets::generate_per_computation_candidates; diff --git a/crates/stage1-pass1-per-computation-candidates/src/tests.rs b/crates/stage1-pass1-per-computation-candidates/src/tests.rs index 0d20b156e..272151b8a 100644 --- a/crates/stage1-pass1-per-computation-candidates/src/tests.rs +++ b/crates/stage1-pass1-per-computation-candidates/src/tests.rs @@ -1,13 +1,1094 @@ -//! Frontend-to-Pass-1 acceptance: candidate discovery precedes empirical selection. -use crate::computation_targets::computation_candidates_for_intent; +//! Pass 1's tests. Each builds its input memo through `Memo::find_or_add_group` +//! and `Memo::add_query`, as Stage 0 does, and reads the candidates +//! [`pass1_memo`](crate::pass1_memo) adds; no other stage crate is called. +use std::fmt::Write as _; +use std::time::Duration; + +use asap_types::ir::operator::arguments::{BinaryOpKind, Reduction, Source}; use asap_types::ir::operator::AggIntent; -use asap_types::summary_type::SketchAlgorithm; +use asap_types::ir::scalar::expr_ir::ArithmeticOpKind; +use asap_types::ir::scalar::{ColumnRef, CompareOpKind, ScalarValue}; +use asap_types::ir::schema::{DataType, Field, FieldDataType, Schema, PROMQL_SERIES_IDENTITY}; +use asap_types::ir::{ + ASAPOp, BinaryOperator, ExprSemantics, NonASAPOp, Operator, Predicate, ScalarExpr, + TimeRangeKind, +}; +use asap_types::stages::{CandidateForMemoGroup, LogicalRequirements, Memo, MemoGroupId}; +use asap_types::summary_type::{parameter_list, SummaryTypeCapability}; +use asap_types::summary_type::{ + ExactKind, SketchAlgorithm, SketchParams, SketchStatistic, SummaryInputExpr, SummaryUpdate, + WeightDomain, +}; + +use crate::candidates::{add_measure_way, key_only_having, Pending, SingleMeasure}; +use crate::computation_targets::{ + computation_candidates_for_intent, computation_targets, HowToComputeAggregateMeasure, +}; +use crate::summary_realization::{ + realize_keyed_additive_summary_input, summarised_input, summary_candidates, +}; +use crate::test_fixtures::{aggregate_group, group, query, scan_group}; +use crate::{pass1_memo, PerComputationCandidateError}; +use asap_types::test_support::memo_fixtures::scan; +use asap_types::workload::DataWorkload; + +/// A compact printout of every group and its candidates: the expression's +/// operator, then per candidate its operator, input groups, θ and fused +/// groups. +fn memo_printout(memo: &Memo) -> String { + let mut out = String::new(); + for (index, group) in memo.groups().iter().enumerate() { + let _ = writeln!(out, "G{index}: {}", label(&group.expression)); + for (position, candidate) in group.candidates.iter().enumerate() { + let inputs: Vec = candidate + .expression + .operator + .children() + .iter() + .map(|g| format!("G{}", g.0)) + .collect(); + let mut line = format!( + " [{position}] {} inputs=[{}]", + label(&candidate.expression.operator), + inputs.join(", ") + ); + if let Some(parameters) = candidate.logical_properties.parameters() { + let _ = write!(line, " θ={parameters:?}"); + } + if !candidate.fused_groups.is_empty() { + let _ = write!(line, " fused_groups={:?}", candidate.fused_groups); + } + let _ = writeln!(out, "{line}"); + } + } + out +} + +fn label(operator: &Operator) -> String { + match operator { + Operator::ASAP(ASAPOp::SummaryAgg { summary_type, .. }) => { + format!("SummaryAgg[{summary_type:?}]") + } + Operator::ASAP(ASAPOp::SummaryEstimate { query, .. }) => { + format!("SummaryEstimate[{query:?}]") + } + Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) => { + let names: Vec = measures + .iter() + .map(|m| { + format!("{m:?}") + .split([' ', '{']) + .next() + .unwrap_or("") + .to_string() + }) + .collect(); + format!("Aggregate[{}]", names.join(", ")) + } + operator => operator.kind_name().to_string(), + } +} + +fn candidates(memo: &Memo, group: MemoGroupId) -> &[CandidateForMemoGroup] { + &memo.groups()[group.0 as usize].candidates +} + +/// The groups of `memo` whose expression matches `pattern`. +fn groups_where(memo: &Memo, pattern: impl Fn(&Operator) -> bool) -> Vec { + memo.groups() + .iter() + .enumerate() + .filter(|(_, group)| pattern(&group.expression)) + .map(|(index, _)| MemoGroupId(index as u32)) + .collect() +} + +/// The state group of `algorithm` in `memo`, and its build's update. +fn state_group(memo: &Memo, algorithm: SketchAlgorithm) -> (MemoGroupId, SummaryUpdate) { + let found = groups_where( + memo, + |expression| matches!(expression, Operator::ASAP(ASAPOp::SummaryAgg { summary_type: FieldDataType::Sketch(a), .. }) if *a == algorithm), + ); + let [state] = found[..] else { + panic!( + "one {algorithm:?} state group: {found:?}\n{}", + memo_printout(memo) + ) + }; + let Operator::ASAP(ASAPOp::SummaryAgg { input, .. }) = + &memo.groups()[state.0 as usize].expression + else { + unreachable!() + }; + (state, input.clone()) +} + +fn quantile(q: f64) -> AggIntent { + AggIntent::Quantile { col: None, q } +} + +fn sum() -> AggIntent { + AggIntent::Sum { col: None } +} + +fn topk(k: usize) -> AggIntent { + AggIntent::TopK { k } +} + +/// `metric[5m]` (`Range`) or `metric` (`Instant`, which a cross-series +/// aggregate reads): a selector over `metric{labels}`. +fn selector(memo: &mut Memo, kind: TimeRangeKind, metric: &str, labels: &[&str]) -> MemoGroupId { + let scan = scan_group(memo, metric, labels); + group( + memo, + Operator::NonASAP(NonASAPOp::TimeRange { + range: Duration::from_secs(300), + kind, + child: scan, + }), + ) +} + +/// `column op literal` over an aggregate's output. +fn compare(column: usize, op: CompareOpKind, value: ScalarValue) -> Predicate { + Predicate(ScalarExpr::Compare { + left: Box::new(ScalarExpr::Column(column)), + op, + right: Box::new(ScalarExpr::Literal(value)), + semantics: ExprSemantics::Promql, + }) +} + +/// `Filter(pred)` over `child`, added as Stage 0 adds a consumer `Filter`. +fn filter(memo: &mut Memo, child: MemoGroupId, pred: Predicate) -> MemoGroupId { + group(memo, Operator::NonASAP(NonASAPOp::Filter { pred, child })) +} + +// ── Running example (concepts doc, section 1) ────────────────────────────── + +/// The doc's running example: query A reads p95 of `latency`, query B +/// reads p99 / p50 of it. KLL state group holds one build per θ of KLL's +/// list, DDSketch's state group likewise; the p95, p99 and p50 groups each +/// read either state through their own readout groups. The metric rule +/// (B's relative ratio cannot read KLL's rank error) drops edges in Pass 2, +/// so Pass 1 offers both algorithms to every quantile group. +#[test] +fn running_example_gives_one_build_per_theta_and_separate_readouts() { + let mut memo = Memo::new(&DataWorkload::default()); + let g1 = selector(&mut memo, TimeRangeKind::Instant, "latency", &[]); + let g3 = aggregate_group( + &mut memo, + g1, + Reduction::by(vec![]), + vec![quantile(0.95)], + None, + ); + let g4 = aggregate_group( + &mut memo, + g1, + Reduction::by(vec![]), + vec![quantile(0.99)], + None, + ); + let g5 = aggregate_group( + &mut memo, + g1, + Reduction::by(vec![]), + vec![quantile(0.5)], + None, + ); + let g6 = group( + &mut memo, + Operator::NonASAP(NonASAPOp::BinaryOp { + operator: BinaryOperator { + checked_relative_division: false, + checked_finite_division: false, + kind: BinaryOpKind::Arithmetic(ArithmeticOpKind::Div), + vector_match: None, + }, + return_bool: false, + lhs: g4, + rhs: g5, + }), + ); + query(&mut memo, g3); + query(&mut memo, g6); + let memo = pass1_memo(memo, None).unwrap(); + println!("{}", memo_printout(&memo)); + let (kll, _) = state_group(&memo, SketchAlgorithm::Kll); + let (ddsketch, _) = state_group(&memo, SketchAlgorithm::DDSketch); + for (state, algorithm) in [ + (kll, SketchAlgorithm::Kll), + (ddsketch, SketchAlgorithm::DDSketch), + ] { + let thetas: Vec = candidates(&memo, state) + .iter() + .map(|candidate| candidate.logical_properties.parameters().unwrap().clone()) + .collect(); + assert_eq!(thetas, parameter_list(algorithm)); + // θ is a property, never an operator argument: every build has the + // group's own expression. + assert!(candidates(&memo, state).iter().all(|candidate| { + candidate.expression.operator == memo.groups()[state.0 as usize].expression + })); + } + // Each quantile group: its exact aggregate and one readout per algorithm, + // each through a readout group of its own over the state group. + for (result, q) in [(g3, 0.95), (g4, 0.99), (g5, 0.5)] { + let readouts: Vec = candidates(&memo, result)[1..] + .iter() + .map(|candidate| *candidate.expression.operator.children()[0]) + .collect(); + assert_eq!(readouts.len(), 2, "G{}", result.0); + for (readout, state) in readouts.iter().zip([kll, ddsketch]) { + assert_eq!( + memo.groups()[readout.0 as usize].expression, + Operator::ASAP(ASAPOp::SummaryEstimate { + summary_input: state, + query: SketchStatistic::Quantile { q }, + }) + ); + assert!(candidates(&memo, *readout)[0] + .logical_properties + .parameters() + .is_none()); + } + } + // The ratio's group keeps its one candidate, its own expression. + assert_eq!(candidates(&memo, g6).len(), 1); +} + +// ── Series identity ──────────────────────────────────────────────────────── + +/// `quantile_over_time(0.9, latency[5m])` over series whose identity is +/// realized as a column (as the planner does before Stage 0): each readout +/// candidate outputs the per-series aggregate's exact schema, the +/// `$promql_series_identity` column included, so every readout keeps the +/// series it answers for. +#[test] +fn per_series_readouts_keep_the_series_identity() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Range, "latency", &["job"]); + let per_series = aggregate_group( + &mut memo, + rows, + Reduction::PerEntity, + vec![quantile(0.9)], + None, + ); + query(&mut memo, per_series); + let memo = pass1_memo(memo, None).unwrap(); + let output = &memo.groups()[per_series.0 as usize].group_properties.schema; + assert!(output.closed && output.has_promql_series_identity()); + let readouts = &candidates(&memo, per_series)[1..]; + assert_eq!(readouts.len(), 2, "{}", memo_printout(&memo)); + for readout in readouts { + let Operator::NonASAP(NonASAPOp::Project { child, cols, .. }) = + &readout.expression.operator + else { + panic!("a renaming Project: {:?}", readout.expression.operator) + }; + let estimate = &memo.groups()[child.0 as usize].group_properties.schema; + assert!(estimate.has_promql_series_identity()); + let identity = output + .fields + .iter() + .position(|field| field.name == PROMQL_SERIES_IDENTITY) + .unwrap(); + let read = estimate + .fields + .iter() + .position(|field| field.name == PROMQL_SERIES_IDENTITY) + .unwrap(); + assert_eq!(cols[identity].expr, ScalarExpr::Column(read)); + } +} + +/// Without a realized identity the per-series aggregate's schema is open: +/// its rows carry labels it does not list. A renaming `Project` would drop +/// them, so no readout is offered; the group keeps its own expression. +#[test] +fn an_open_per_series_aggregate_offers_no_renamed_readout() { + let mut memo = Memo::new(&DataWorkload::default()); + let scan = group( + &mut memo, + scan("latency", &[("job", DataType::Utf8)], vec![]), + ); + let rows = group( + &mut memo, + Operator::NonASAP(NonASAPOp::TimeRange { + range: Duration::from_secs(300), + kind: TimeRangeKind::Range, + child: scan, + }), + ); + let per_series = aggregate_group( + &mut memo, + rows, + Reduction::PerEntity, + vec![quantile(0.9)], + None, + ); + query(&mut memo, per_series); + let memo = pass1_memo(memo, None).unwrap(); + assert!( + !memo.groups()[per_series.0 as usize] + .group_properties + .schema + .closed + ); + assert_eq!(candidates(&memo, per_series).len(), 1); +} + +// ── Target discovery ─────────────────────────────────────────────────────── + +/// Each measure of a multi-measure aggregate is its own target; a measure +/// whose only realization is its exact accumulator is still a target. +#[test] +fn multi_measure_aggregate_has_one_target_per_measure() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let both = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![2]), + vec![sum(), quantile(0.9)], + None, + ); + query(&mut memo, both); + let targets = computation_targets(&memo, None).unwrap(); + let measures: Vec<(MemoGroupId, usize)> = targets + .iter() + .map(|target| (target.aggregate_group, target.measure_index)) + .collect(); + assert_eq!(measures, vec![(both, 0), (both, 1)]); +} + +/// An aggregate with no realization besides exact execution (no +/// accumulator, no summary: `stddev`) is not a target. +#[test] +fn aggregate_without_realization_is_not_a_target() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &[]); + let stddev = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![]), + vec![AggIntent::StdDev { + col: None, + population: true, + }], + None, + ); + query(&mut memo, stddev); + assert!(computation_targets(&memo, None).unwrap().is_empty()); + let memo = pass1_memo(memo, None).unwrap(); + assert_eq!(candidates(&memo, stddev).len(), 1); +} + +/// An aggregate several queries read, or a scalar root reads twice, is one +/// target per measure: Pass 1 walks the groups. +#[test] +fn an_aggregate_read_by_several_roots_is_one_target() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &[]); + let p = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![]), + vec![quantile(0.9)], + None, + ); + query(&mut memo, p); + query(&mut memo, p); + assert_eq!(computation_targets(&memo, None).unwrap().len(), 1); +} + +/// A memo whose groups already hold ASAP operators fails at the stage +/// boundary. +#[test] +fn asap_input_is_rejected() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &[]); + let state = group( + &mut memo, + Operator::ASAP(ASAPOp::SummaryAgg { + child: rows, + summary_type: FieldDataType::exact(ExactKind::Sum), + input: SummaryUpdate::column(ColumnRef::SampleValue), + reduction: Reduction::PerEntity, + filter: None, + }), + ); + query(&mut memo, state); + assert!(matches!( + pass1_memo(memo, None), + Err(PerComputationCandidateError::ContainsAsap) + )); +} + +/// The summaries the deployment does not support are not offered. +#[test] +fn unsupported_summaries_are_not_offered() { + 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); + let memo = pass1_memo(memo, Some(&[])).unwrap(); + assert_eq!(candidates(&memo, p).len(), 1); + assert!(groups_where(&memo, |e| matches!(e, Operator::ASAP(_))).is_empty()); +} + +// ── Candidate composition ────────────────────────────────────────────────── + +/// Every group has its own expression as a candidate, with no θ: plain +/// exact execution. +#[test] +fn every_group_offers_its_own_expression() { + let mut memo = Memo::new(&DataWorkload::default()); + 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); + let stage0 = memo.groups().len(); + let memo = pass1_memo(memo, None).unwrap(); + for index in 0..stage0 { + let group = &memo.groups()[index]; + let own = &group.candidates[0]; + assert_eq!(own.expression.operator, group.expression); + assert!(own.logical_properties.parameters().is_none()); + } +} + +/// An exact accumulator is a state group (`SummaryAgg` of the exact +/// summary type, no θ) read by a `FinalizeExactAccumulator` group, which the +/// aggregate's group reads through a renaming `Project`. +#[test] +fn exact_accumulator_is_a_state_group_and_a_finalize() { + let mut memo = Memo::new(&DataWorkload::default()); + 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); + let memo = pass1_memo(memo, None).unwrap(); + let states = groups_where(&memo, |e| { + matches!( + e, + Operator::ASAP(ASAPOp::SummaryAgg { + summary_type: FieldDataType::ExactAggregate(ExactKind::Sum, _), + .. + }) + ) + }); + let [state] = states[..] else { + panic!("{}", memo_printout(&memo)) + }; + assert_eq!(candidates(&memo, state).len(), 1); + assert!(candidates(&memo, state)[0] + .logical_properties + .parameters() + .is_none()); + // The aggregate reads it through a `FinalizeExactAccumulator`, renamed + // to the aggregate's columns when its names differ. + let finalize = Operator::ASAP(ASAPOp::FinalizeExactAccumulator { child: state }); + let finalize_groups = groups_where(&memo, |e| *e == finalize); + assert!(candidates(&memo, s).iter().any(|c| { + c.expression.operator == finalize + || c.expression + .operator + .children() + .iter() + .any(|g| finalize_groups.contains(g)) + })); +} + +/// A multi-measure aggregate's candidate joins the measures' own groups +/// (one single-measure aggregate each, with its own candidates) on the +/// group keys. +#[test] +fn multi_measure_candidate_joins_single_measure_groups() { + let mut memo = Memo::new(&DataWorkload::default()); + // A SQL table `flows(src Utf8, bytes Float64)`. + let rows = group( + &mut memo, + Operator::NonASAP(NonASAPOp::Scan { + source: Source::Table { + table_ref: "flows".into(), + }, + predicates: vec![], + schema: Schema::new(vec![ + Field::plain("src", DataType::Utf8, false), + Field::plain("bytes", DataType::Float64, false), + ]), + }), + ); + let both = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![0]), + vec![ + AggIntent::Sum { col: Some(1) }, + AggIntent::Quantile { + col: Some(1), + q: 0.9, + }, + ], + None, + ); + query(&mut memo, both); + let memo = pass1_memo(memo, None).unwrap(); + let single = groups_where( + &memo, + |e| matches!(e, Operator::NonASAP(NonASAPOp::Aggregate { measures, .. }) if measures.len() == 1), + ); + assert_eq!(single.len(), 2, "{}", memo_printout(&memo)); + // The quantile measure's group has its exact aggregate and two readouts. + assert!(single.iter().any(|g| candidates(&memo, *g).len() == 3)); + let joins = groups_where(&memo, |e| { + matches!(e, Operator::NonASAP(NonASAPOp::Join { .. })) + }); + assert_eq!(joins.len(), 1); + assert_eq!(candidates(&memo, both).len(), 2); +} + +/// Pass 1 sets no input requirement, a top-k readout's included: each +/// candidate has one empty requirement per input group, and Pass 2 sets +/// the readouts' required accuracy (a top-k's `heap_size` ≥ k among it). +#[test] +fn pass1_sets_no_input_requirement() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Range, "m", &["job"]); + let per_series = aggregate_group(&mut memo, rows, Reduction::PerEntity, vec![sum()], None); + let by_job = aggregate_group( + &mut memo, + per_series, + Reduction::by(vec![2]), + vec![sum()], + None, + ); + let ranked = aggregate_group( + &mut memo, + by_job, + Reduction::by(vec![]), + vec![topk(15)], + None, + ); + let samples = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let p = aggregate_group( + &mut memo, + samples, + Reduction::by(vec![]), + vec![quantile(0.9)], + None, + ); + query(&mut memo, ranked); + query(&mut memo, p); + let memo = pass1_memo(memo, None).unwrap(); + // The top-k readout is offered, and has no input requirement either. + assert!(!groups_where(&memo, |e| matches!( + e, + Operator::ASAP(ASAPOp::SummaryEstimate { + query: SketchStatistic::TopK { k: 15 }, + .. + }) + )) + .is_empty()); + for group in memo.groups() { + for candidate in &group.candidates { + assert_eq!( + candidate.input_requirements, + vec![ + LogicalRequirements::default(); + candidate.expression.operator.children().len() + ] + ); + } + } +} + +// ── HAVING placement ─────────────────────────────────────────────────────── + +/// The aggregate's input with a key-only predicate pushed below it: a +/// `Filter` group over `rows`. +fn pushed_below(memo: &Memo, rows: MemoGroupId) -> Vec { + groups_where( + memo, + |e| matches!(e, Operator::NonASAP(NonASAPOp::Filter { child, .. }) if *child == rows), + ) +} + +/// A key-only `HAVING` (a consumer `Filter` over the group keys) gets +/// candidates in the `Filter`'s group that push it below the aggregate: a +/// `Filter` on the input rows, which the states read. The aggregate's own +/// group keeps its unfiltered candidates for its other consumers. +#[test] +fn key_only_having_is_pushed_below_into_the_filter_group() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let by_job = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![2]), + vec![quantile(0.9)], + None, + ); + let having = filter( + &mut memo, + by_job, + compare(0, CompareOpKind::Eq, ScalarValue::Utf8("a".into())), + ); + query(&mut memo, having); + query(&mut memo, by_job); + let memo = pass1_memo(memo, None).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 + // over states built from the filtered rows. + assert_eq!(candidates(&memo, having).len(), 3); + assert_eq!(candidates(&memo, by_job).len(), 3); +} + +/// A `HAVING` over an aggregate value stays above the output: nothing is +/// pushed below, and the `Filter` group keeps its own expression only. +#[test] +fn value_having_stays_above() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let by_job = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![2]), + vec![quantile(0.9)], + None, + ); + let having = filter( + &mut memo, + by_job, + compare(1, CompareOpKind::Gt, ScalarValue::Float64(10.0)), + ); + query(&mut memo, having); + let memo = pass1_memo(memo, None).unwrap(); + assert!(pushed_below(&memo, rows).is_empty()); + assert_eq!(candidates(&memo, having).len(), 1); +} + +/// A global aggregate's `HAVING` stays above even when it is constant: the +/// one output row exists with no input row. +#[test] +fn global_aggregate_having_stays_above() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &[]); + let p = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![]), + vec![quantile(0.9)], + None, + ); + let having = filter( + &mut memo, + p, + Predicate(ScalarExpr::Literal(ScalarValue::Boolean(false))), + ); + query(&mut memo, having); + let memo = pass1_memo(memo, None).unwrap(); + assert!(pushed_below(&memo, rows).is_empty()); +} + +/// Which `HAVING` conjuncts of a grouped aggregate (`by (job)`) are pushed +/// below it: a key conjunct, and a column-free one built of literals and +/// comparison and boolean operators (`1 = 0`); not a column-free one with a +/// function call, which may be volatile (`random() < 0.5`, built in the IR +/// directly: the frontends and schema derivation reject `random`), nor +/// one over the aggregate's value, nor any of a global aggregate's. +#[test] +fn key_only_having_pushes_keys_and_constants_but_no_function_call() { + let literal = |value| Box::new(ScalarExpr::Literal(value)); + let one_equals_zero = ScalarExpr::Compare { + left: literal(ScalarValue::Int64(1)), + op: CompareOpKind::Eq, + right: literal(ScalarValue::Int64(0)), + semantics: ExprSemantics::Sql, + }; + let random_below_half = ScalarExpr::Compare { + left: Box::new(ScalarExpr::FunctionCall { + name: "random".into(), + args: vec![], + }), + op: CompareOpKind::Lt, + right: literal(ScalarValue::Float64(0.5)), + semantics: ExprSemantics::Sql, + }; + let job_is_a = compare(0, CompareOpKind::Eq, ScalarValue::Utf8("a".into())).0; + let value_above_ten = compare(1, CompareOpKind::Gt, ScalarValue::Float64(10.0)).0; + let by_job = Reduction::by(vec![2]); + assert!(key_only_having(&by_job, &job_is_a)); + assert!(key_only_having(&by_job, &one_equals_zero)); + assert!(key_only_having( + &by_job, + &ScalarExpr::Not(Box::new(one_equals_zero.clone())) + )); + assert!(!key_only_having(&by_job, &random_below_half)); + assert!(!key_only_having(&by_job, &value_above_ten)); + let global = Reduction::by(vec![]); + assert!(!key_only_having(&global, &one_equals_zero)); +} + +/// A grouped aggregate's constant `HAVING 1 = 0` is pushed below it. +#[test] +fn a_constant_having_of_a_grouped_aggregate_is_pushed_below() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let by_job = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![2]), + vec![quantile(0.9)], + None, + ); + let having = filter( + &mut memo, + by_job, + Predicate(ScalarExpr::Compare { + left: Box::new(ScalarExpr::Literal(ScalarValue::Int64(1))), + op: CompareOpKind::Eq, + right: Box::new(ScalarExpr::Literal(ScalarValue::Int64(0))), + semantics: ExprSemantics::Sql, + }), + ); + query(&mut memo, having); + let memo = pass1_memo(memo, None).unwrap(); + assert_eq!( + pushed_below(&memo, rows).len(), + 1, + "{}", + memo_printout(&memo) + ); + assert_eq!(candidates(&memo, having).len(), 3); +} + +/// The aggregate's own value `having` is a `Filter` above each readout: +/// the aggregate group's summary candidates are `Filter`s over a readout. +#[test] +fn own_value_having_filters_each_readout() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let by_job = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![2]), + vec![quantile(0.9)], + Some(compare(1, CompareOpKind::Gt, ScalarValue::Float64(10.0))), + ); + query(&mut memo, by_job); + let memo = pass1_memo(memo, None).unwrap(); + let kinds: Vec<&str> = candidates(&memo, by_job) + .iter() + .map(|c| c.expression.operator.kind_name()) + .collect(); + assert_eq!(kinds, ["Aggregate", "Filter", "Filter"]); +} + +// ── Fused heaps, whole-expression top-k, ranked items, raw-data signs ────── + +/// `topk(5, sum by (job) (sum_over_time(m[5m])))`: the top-k gets heaps +/// over the range's raw data samples, keyed by `job` (the ranked item), +/// weighted by the sample value with the open requirement that the samples +/// of `m` are non-negative (`RawDataSamplesOfMetric`). Each heap build +/// lists the absorbed sums' groups in `fused_groups`, and the top-k's own +/// heaps over its one-row-per-item input are pruned. +#[test] +fn whole_expression_topk_heaps_read_the_raw_samples() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Range, "m", &["job"]); + let per_series = aggregate_group(&mut memo, rows, Reduction::PerEntity, vec![sum()], None); + let by_job = aggregate_group( + &mut memo, + per_series, + Reduction::by(vec![2]), + vec![sum()], + None, + ); + let ranked = aggregate_group( + &mut memo, + by_job, + Reduction::by(vec![]), + vec![topk(5)], + None, + ); + query(&mut memo, ranked); + let memo = pass1_memo(memo, None).unwrap(); + for algorithm in [ + SketchAlgorithm::CmsWithHeap, + SketchAlgorithm::CountSketchWithHeap, + ] { + let (state, update) = state_group(&memo, algorithm); + assert_eq!( + *memo.groups()[state.0 as usize].expression.children()[0], + rows + ); + assert_eq!( + update.item, + Some(SummaryInputExpr::Column(ColumnRef::Named("job".into()))) + ); + assert_eq!( + update.weight_domain, + WeightDomain::RawDataSamplesOfMetric { metric: "m".into() } + ); + for build in candidates(&memo, state) { + let mut fused = build.fused_groups.clone(); + fused.sort(); + assert_eq!(fused, vec![per_series, by_job]); + } + assert_eq!( + candidates(&memo, state).len(), + parameter_list(algorithm).len() + ); + } +} + +/// `topk(5, sum by (job) (sum_over_time(m[5m])))`: the whole-expression +/// heap's candidates, built through the readout and output path every +/// summary way takes. The top-k group gets one `Project` per heap +/// algorithm, ranking the estimate read from that heap's state; only the +/// state's builds list the absorbed groups. +#[test] +fn whole_expression_topk_heap_candidates() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Range, "m", &["job"]); + let per_series = aggregate_group(&mut memo, rows, Reduction::PerEntity, vec![sum()], None); + let by_job = aggregate_group( + &mut memo, + per_series, + Reduction::by(vec![2]), + vec![sum()], + None, + ); + let ranked = aggregate_group( + &mut memo, + by_job, + Reduction::by(vec![]), + vec![topk(5)], + None, + ); + query(&mut memo, ranked); + let memo = pass1_memo(memo, None).unwrap(); + // The top-k group's own expression, then one ranked `Project` per heap. + let ranked_candidates = candidates(&memo, ranked); + let kinds: Vec<&str> = ranked_candidates + .iter() + .map(|c| c.expression.operator.kind_name()) + .collect(); + assert_eq!( + kinds, + ["Aggregate", "Project", "Project"], + "{}", + memo_printout(&memo) + ); + for (project, algorithm) in ranked_candidates[1..].iter().zip([ + SketchAlgorithm::CmsWithHeap, + SketchAlgorithm::CountSketchWithHeap, + ]) { + assert!(project.fused_groups.is_empty()); + let estimate = *project.expression.operator.children()[0]; + let [estimate_candidate] = candidates(&memo, estimate) else { + panic!("one readout candidate: {}", memo_printout(&memo)); + }; + assert!(matches!( + estimate_candidate.expression.operator, + Operator::ASAP(ASAPOp::SummaryEstimate { .. }) + )); + assert!(estimate_candidate.fused_groups.is_empty()); + let (state, _) = state_group(&memo, algorithm); + assert_eq!(*estimate_candidate.expression.operator.children()[0], state); + assert_eq!( + candidates(&memo, state).len(), + parameter_list(algorithm).len() + ); + for build in candidates(&memo, state) { + assert_eq!(build.fused_groups, [by_job, per_series]); + } + } + // Scan, range, the two sums, the top-k, the sums' two accumulator + // states, and per heap its state and readout: no other group. + assert_eq!(memo.groups().len(), 11, "{}", memo_printout(&memo)); +} + +/// A top-k over a `count` ranks the counted items with unit weight, proven +/// non-negative. +#[test] +fn count_ranked_topk_counts_with_unit_weight() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let counts = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![2]), + vec![AggIntent::Count], + None, + ); + let ranked = aggregate_group( + &mut memo, + counts, + Reduction::by(vec![]), + vec![topk(5)], + None, + ); + query(&mut memo, ranked); + let memo = pass1_memo(memo, None).unwrap(); + let (_, update) = state_group(&memo, SketchAlgorithm::CmsWithHeap); + assert_eq!(update.weight, SummaryInputExpr::Constant(1.0)); + assert!(matches!( + update.weight_domain, + WeightDomain::NonNegative { .. } + )); +} + +/// The ranked item over several group keys is their tuple; the top-k's own +/// partition keys partition the heap and stay out of the tuple. +#[test] +fn ranked_item_is_the_keys_outside_the_partition() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Range, "m", &["job", "host"]); + let per_series = aggregate_group(&mut memo, rows, Reduction::PerEntity, vec![sum()], None); + let by_both = aggregate_group( + &mut memo, + per_series, + Reduction::by(vec![2, 3]), + vec![sum()], + None, + ); + let ranked = aggregate_group( + &mut memo, + by_both, + Reduction::by(vec![0]), + vec![topk(5)], + None, + ); + query(&mut memo, ranked); + let memo = pass1_memo(memo, None).unwrap(); + let (_, update) = state_group(&memo, SketchAlgorithm::CountSketchWithHeap); + assert_eq!( + update.item, + Some(SummaryInputExpr::Column(ColumnRef::Named("host".into()))) + ); +} + +// ── Nested distributive merges ───────────────────────────────────────────── + +/// `sum by (job) (sum_over_time(m[5m]))`, and likewise `min` of `min` and +/// `max` of `max`, gets a merged build: one exact accumulator of that kind +/// over the raw samples grouped by `job`, a candidate of the outer +/// aggregate's own accumulator state group, listing the inner aggregate's +/// group in `fused_groups`. +#[test] +fn nested_distributive_aggregate_merges_into_the_outer_state_group() { + for (intent, kind) in [ + (sum(), ExactKind::Sum), + (AggIntent::Min { col: None }, ExactKind::Min), + (AggIntent::Max { col: None }, ExactKind::Max), + ] { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Range, "m", &["job"]); + let per_series = aggregate_group( + &mut memo, + rows, + Reduction::PerEntity, + vec![intent.clone()], + None, + ); + let by_job = aggregate_group( + &mut memo, + per_series, + Reduction::by(vec![2]), + vec![intent], + None, + ); + query(&mut memo, by_job); + let memo = pass1_memo(memo, None).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), + ); + let [outer_state] = outer_state[..] else { + panic!("{kind:?}: {}", memo_printout(&memo)) + }; + let builds = candidates(&memo, outer_state); + assert_eq!(builds.len(), 2, "{kind:?}: {}", memo_printout(&memo)); + let merged = &builds[1]; + assert_eq!(merged.expression.operator.children(), vec![&rows]); + assert_eq!(merged.fused_groups, vec![per_series]); + } +} + +/// The merge needs the same distributive aggregate twice: a `sum` over a +/// `max`, or a `min` over a `max`, gets none. +#[test] +fn nested_merge_needs_the_same_distributive_aggregate() { + for outer in [sum(), AggIntent::Min { col: None }] { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Range, "m", &["job"]); + let per_series = aggregate_group( + &mut memo, + rows, + Reduction::PerEntity, + vec![AggIntent::Max { col: None }], + None, + ); + let by_job = aggregate_group( + &mut memo, + per_series, + Reduction::by(vec![2]), + vec![outer], + None, + ); + query(&mut memo, by_job); + let memo = pass1_memo(memo, None).unwrap(); + assert!(memo + .groups() + .iter() + .flat_map(|g| &g.candidates) + .all(|c| c.fused_groups.is_empty())); + } +} -use asap_types::stages::HowToComputeAggregateMeasure; +// ── Stream norms (update weights) ────────────────────────────────────────── -fn candidates_for(intent: AggIntent) -> Vec { - computation_candidates_for_intent(&intent).candidates +/// A Count-Min count adds one per row (bounded by the row count); a sum's +/// state reads the raw value column (bounded by the source's norm). +#[test] +fn update_weights_follow_the_measure() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = selector(&mut memo, TimeRangeKind::Instant, "m", &["job"]); + let counts = aggregate_group( + &mut memo, + rows, + Reduction::by(vec![2]), + vec![AggIntent::Count], + None, + ); + query(&mut memo, counts); + let memo = pass1_memo(memo, None).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); + let memo = pass1_memo(memo, None).unwrap(); + let state = groups_where( + &memo, + |e| matches!(e, Operator::ASAP(ASAPOp::SummaryAgg { input, .. }) if input.weight == SummaryInputExpr::Column(ColumnRef::SampleValue)), + ); + assert_eq!(state.len(), 1); } + +// ── Intents ──────────────────────────────────────────────────────────────── + fn algorithms(choices: &[HowToComputeAggregateMeasure]) -> Vec { choices .iter() @@ -18,11 +1099,14 @@ fn algorithms(choices: &[HowToComputeAggregateMeasure]) -> Vec .collect() } -/// Example 2 preserves specialized distinct summaries and the universal alternative. +/// Example 2 preserves specialized distinct summaries and the universal +/// alternative; plain exact execution is the group's own expression. #[test] -fn cardinality_keeps_exact_specialized_and_universal_candidates() { - let choices = candidates_for(AggIntent::Cardinality { cols: vec![0] }); - assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); +fn cardinality_keeps_specialized_and_universal_summaries() { + let choices = computation_candidates_for_intent(&AggIntent::Cardinality { cols: vec![0] }); + assert!(choices + .iter() + .all(|choice| matches!(choice, HowToComputeAggregateMeasure::Summary(_)))); assert_eq!( algorithms(&choices), vec![ @@ -31,28 +1115,31 @@ fn cardinality_keeps_exact_specialized_and_universal_candidates() { SketchAlgorithm::UnivMon ] ); - let tuple = candidates_for(AggIntent::Cardinality { cols: vec![0, 1] }); + let tuple = computation_candidates_for_intent(&AggIntent::Cardinality { cols: vec![0, 1] }); assert!(!algorithms(&tuple).contains(&SketchAlgorithm::UnivMon)); } -/// Frequency moments retain exact execution and a universal sketch without certification. +/// Frequency moments offer a universal sketch without certification. #[test] fn frequency_statistics_keep_universal_choices() { for intent in [ AggIntent::FrequencyL2 { col: Some(0) }, AggIntent::FrequencyEntropy { col: Some(0) }, ] { - let choices = candidates_for(intent); - assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); - assert_eq!(algorithms(&choices), vec![SketchAlgorithm::UnivMon]); + let choices = computation_candidates_for_intent(&intent); + assert_eq!( + choices, + [HowToComputeAggregateMeasure::Summary( + SketchAlgorithm::UnivMon + )] + ); } } /// TopK keeps both declared heap substrates without choosing an implementation. #[test] fn topk_keeps_both_specialized_heap_choices() { - let choices = candidates_for(AggIntent::TopK { k: 10 }); - assert_eq!(choices[0], HowToComputeAggregateMeasure::Exact); + let choices = computation_candidates_for_intent(&topk(10)); assert_eq!( algorithms(&choices), vec![ @@ -62,10 +1149,243 @@ fn topk_keeps_both_specialized_heap_choices() { ); } -/// Summary candidates are unsized, so they do not depend on the requested error. +/// Approximate count lists its exact accumulator first, beside the +/// summaries (the plain aggregate is the group's own expression). +#[test] +fn approximate_count_lists_its_accumulator_and_summaries() { + let choices = computation_candidates_for_intent(&AggIntent::Count); + assert_eq!( + choices[0], + HowToComputeAggregateMeasure::ExactAccumulator(vec![ExactKind::Count]) + ); + assert!(choices.contains(&HowToComputeAggregateMeasure::Summary( + SketchAlgorithm::UnivMon + ))); +} + +/// Count Sketch's signed counters give no total, so Pass 1 offers no Count +/// Sketch for a count. +#[test] +fn a_count_offers_no_count_sketch() { + assert!( + !computation_candidates_for_intent(&AggIntent::Count).contains( + &HowToComputeAggregateMeasure::Summary(SketchAlgorithm::CountSketch) + ) + ); +} + +// ── Summary realization ────────────────────────────────────────────────────── + +/// A quantile outside [0, 1] is answered -Inf or +Inf: it gets no summary, +/// so no way besides the plain exact aggregate. +#[test] +fn a_quantile_outside_the_unit_interval_offers_no_summary() { + let choices = computation_candidates_for_intent(&AggIntent::Quantile { col: None, q: 1.5 }); + assert!(choices.is_empty()); +} + +/// A heap sketch consumes every raw row, so the keyed input rule refuses +/// a TopK over a filtered count. +#[test] +fn keyed_heap_input_refuses_a_filtered_count() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = scan_group(&mut memo, "m", &["job"]); + let mut count_by_job = |filter: Option>| { + group( + &mut memo, + Operator::NonASAP(NonASAPOp::Aggregate { + reduction: Reduction::by(vec![2]), + measures: vec![AggIntent::Count], + output_names: vec![String::new()], + filters: vec![filter], + having: None, + child: rows, + }), + ) + }; + let unfiltered = count_by_job(None); + let value_above_one = Predicate(ScalarExpr::Compare { + left: Box::new(ScalarExpr::Column(1)), + op: CompareOpKind::Gt, + right: Box::new(ScalarExpr::Literal(ScalarValue::Float64(1.0))), + semantics: ExprSemantics::Promql, + }); + let filtered = count_by_job(Some(value_above_one)); + let output = Reduction::Reduce(asap_types::ir::operator::arguments::GroupKeys::none()); + assert!(realize_keyed_additive_summary_input(&memo, &output, unfiltered).is_some()); + assert!(realize_keyed_additive_summary_input(&memo, &output, filtered).is_none()); +} + +/// A summary reads the intent's own input columns: one column by name, +/// none as the sample value, several as one hashed tuple. +#[test] +fn summarised_input_reads_the_intents_columns() { + // Columns [ts=0, value=1, job=2]. + let Operator::NonASAP(NonASAPOp::Scan { schema, .. }) = + scan("m", &[("job", DataType::Utf8)], vec![]) + else { + unreachable!("a scan") + }; + let column = |name: &str| SummaryInputExpr::Column(ColumnRef::Named(name.into())); + let cases = [ + (vec![2], column("job")), + (vec![1], column("value")), + (vec![], SummaryInputExpr::Column(ColumnRef::SampleValue)), + ( + vec![1, 2], + SummaryInputExpr::Tuple(vec![column("value"), column("job")]), + ), + ]; + for (cols, want) in cases { + let intent = AggIntent::Cardinality { cols: cols.clone() }; + assert_eq!( + summarised_input(&intent, &schema), + Some(want), + "wrong summarised input for cols={cols:?}" + ); + } +} + +/// Each approximable intent is offered the algorithms it was offered when +/// the list was written by hand, in the same order; a non-sketch intent +/// is offered none. +#[test] +fn summary_candidates_keep_the_hand_written_lists() { + use SketchAlgorithm as S; + let cardinality = |cols: Vec| AggIntent::Cardinality { cols }; + let cases = [ + ( + AggIntent::Quantile { col: None, q: 0.99 }, + vec![S::Kll, S::DDSketch], + ), + (cardinality(vec![]), vec![S::Hll, S::Kmv, S::UnivMon]), + (cardinality(vec![1]), vec![S::Hll, S::Kmv, S::UnivMon]), + (cardinality(vec![1, 2]), vec![S::Hll, S::Kmv]), + (AggIntent::FrequencyL2 { col: None }, vec![S::UnivMon]), + (AggIntent::FrequencyEntropy { col: None }, vec![S::UnivMon]), + ( + AggIntent::TopK { k: 10 }, + vec![S::CmsWithHeap, S::CountSketchWithHeap], + ), + (AggIntent::Count, vec![S::Cms, S::UnivMon]), + (AggIntent::Sum { col: None }, vec![]), + ]; + for (intent, want) in cases { + assert_eq!(summary_candidates(&intent), want, "{intent:?}"); + } +} + +/// An algorithm is offered for an intent exactly when its capability table +/// row answers the intent's statistic: Count-Min's row has no top-k readout, +/// so a top-k is offered only the heap variants, whose rows have one. +#[test] +fn an_algorithm_without_the_readout_is_not_offered() { + let top_k = AggIntent::TopK { k: 10 }; + let statistic = SketchStatistic::TopK { k: 10 }; + let answers = |algorithm| { + SummaryTypeCapability::of(&FieldDataType::Sketch(algorithm)).answers(&statistic) + }; + assert!(!answers(SketchAlgorithm::Cms)); + assert!(answers(SketchAlgorithm::CmsWithHeap)); + let offered = summary_candidates(&top_k); + assert!(!offered.contains(&SketchAlgorithm::Cms)); + assert!(offered.iter().all(|algorithm| answers(*algorithm))); +} + +// ── Unsupported ways add nothing ───────────────────────────────────────────── + +/// Offers `measure` by `way` to `result_group`, expecting `Unsupported`, and +/// checks the memo is unchanged: its groups, each group's candidates and +/// its hash-consing index (all in the memo's `Debug`). +fn assert_unsupported_way_adds_nothing( + memo: &mut Memo, + measure: &SingleMeasure<'_>, + way: HowToComputeAggregateMeasure, + result_group: MemoGroupId, +) { + let groups = memo.groups().len(); + let before = format!("{memo:?}"); + let added = add_measure_way(memo, Pending::new(memo), measure, &way, result_group, None); + assert!( + matches!(added, Err(PerComputationCandidateError::Unsupported(_))), + "{added:?}" + ); + assert_eq!(memo.groups().len(), groups); + assert_eq!(format!("{memo:?}"), before); +} + +/// A heap top-k whose estimate lacks a column of the result group (it +/// partitions `host` rows; the group ranks `job`): `ranked_as_topk` finds no +/// `job` in the pending estimate, so neither the heap's state group nor its +/// estimate group is added. #[test] -fn summary_candidates_are_unsized() { - let loose = candidates_for(AggIntent::Count); - let tight = candidates_for(AggIntent::Count); - assert_eq!(loose, tight); +fn a_heap_estimate_without_the_groups_columns_adds_nothing() { + let mut memo = Memo::new(&DataWorkload::default()); + let by_job = scan_group(&mut memo, "m", &["job"]); + let by_host = scan_group(&mut memo, "n", &["host"]); + let ranked = aggregate_group( + &mut memo, + by_job, + Reduction::by(vec![2]), + vec![topk(5)], + None, + ); + let reduction = Reduction::by(vec![2]); + let intent = topk(5); + let measure = SingleMeasure { + input: by_host, + unfiltered_input: by_host, + reduction: &reduction, + intent: &intent, + filter: None, + raw_data_samples_of: None, + }; + assert_unsupported_way_adds_nothing( + &mut memo, + &measure, + HowToComputeAggregateMeasure::Summary(SketchAlgorithm::CountSketchWithHeap), + ranked, + ); +} + +/// A readout of an open per-series aggregate would need a renaming +/// `Project`, which drops the labels an open schema does not list: the +/// KLL state and readout groups are not added. +#[test] +fn a_readout_an_open_group_cannot_rename_adds_nothing() { + let mut memo = Memo::new(&DataWorkload::default()); + let scanned = group( + &mut memo, + scan("latency", &[("job", DataType::Utf8)], vec![]), + ); + let rows = group( + &mut memo, + Operator::NonASAP(NonASAPOp::TimeRange { + range: Duration::from_secs(300), + kind: TimeRangeKind::Range, + child: scanned, + }), + ); + let intent = quantile(0.9); + let per_series = aggregate_group( + &mut memo, + rows, + Reduction::PerEntity, + vec![intent.clone()], + None, + ); + let measure = SingleMeasure { + input: rows, + unfiltered_input: rows, + reduction: &Reduction::PerEntity, + intent: &intent, + filter: None, + raw_data_samples_of: None, + }; + assert_unsupported_way_adds_nothing( + &mut memo, + &measure, + HowToComputeAggregateMeasure::Summary(SketchAlgorithm::Kll), + per_series, + ); } diff --git a/crates/types/src/ir/operator/asap.rs b/crates/types/src/ir/operator/asap.rs index 1793cbbd6..edac475a3 100644 --- a/crates/types/src/ir/operator/asap.rs +++ b/crates/types/src/ir/operator/asap.rs @@ -1057,10 +1057,10 @@ fn topk_schema_of_build( let complete_item_identity = matches!( input.item.as_ref()?, SummaryInputExpr::Column(_) | SummaryInputExpr::Tuple(_) - ) || child_schema.closed - || columns.iter().any(|&index| { - child_schema.fields[index].name == crate::ir::schema::PROMQL_SERIES_IDENTITY - }); + ) || crate::ir::schema::topk::item_identity_is_complete( + child_schema, + columns.iter().copied(), + ); let mut fields: Vec = state_schema .fields .iter() @@ -1077,12 +1077,12 @@ fn topk_schema_of_build( } // One row per (partition, item), not one row per partition. Preserve this // key through the ranked-row projection used by the logical TopK result. - let unique_keys = if complete_item_identity && !fields.is_empty() { - vec![(0..fields.len()).collect()] + fields.push(Field::plain("topk", DataType::Float64, false)); + let unique_keys = if complete_item_identity { + crate::ir::schema::topk::ranked_rows_unique_keys(fields.len(), fields.len() - 1) } else { Vec::new() }; - fields.push(Field::plain("topk", DataType::Float64, false)); Some(Schema { fields, unique_keys, diff --git a/crates/types/src/ir/operator/non_asap.rs b/crates/types/src/ir/operator/non_asap.rs index 892ce65fb..d2eafe2db 100644 --- a/crates/types/src/ir/operator/non_asap.rs +++ b/crates/types/src/ir/operator/non_asap.rs @@ -588,11 +588,17 @@ impl NonASAPOp { let name = crate::ir::schema::topk::topk_output_name(*k, output_names); let cols = crate::ir::schema::topk::ranked_row_projection(child, reduction, &name)?; - return NonASAPOp::Project { + let mut output = NonASAPOp::Project { cols, child: child.clone(), } - .output_schema(); + .output_schema()?; + output.unique_keys = crate::ir::schema::topk::exact_topk_unique_keys( + child, + reduction.group_keys().map_or(0, |keys| keys.len()), + &output, + ); + return Ok(output); } let mut output = aggregate_output_schema(child.schema(), reduction, measures, output_names)?; @@ -1326,7 +1332,7 @@ fn default_proj_name( } /// Whether any aggregate measure has its own input predicate. -pub fn any_measure_filtered(filters: &[Option]) -> bool { +pub fn any_measure_filtered(filters: &[Option>]) -> bool { filters.iter().any(Option::is_some) } diff --git a/crates/types/src/ir/schema/topk.rs b/crates/types/src/ir/schema/topk.rs index 685e1aa5b..a8c82c122 100644 --- a/crates/types/src/ir/schema/topk.rs +++ b/crates/types/src/ir/schema/topk.rs @@ -14,9 +14,31 @@ use crate::ir::{ASAPOp, NonASAPOp, Operator, ScalarExpr}; /// `FinalizeExactAccumulator` or `SummaryEstimate`, under the `Project` /// restoring its names (a renaming) and a value `HAVING`'s `Filter`. Over /// per-series rows (PromQL `topk by (..) (k, rows)`) it is the sample value. -pub fn ranked_column(child: &I) -> Result { +pub(crate) fn ranked_column(child: &I) -> Result { + match ranked_source(child) { + RankedSource::TopK(reduction) => Ok(reduction.group_keys().map_or(0, |keys| keys.len())), + RankedSource::OneRowPerItem(Reduction::Reduce(_)) => Ok(child.schema().fields.len() - 1), + RankedSource::OneRowPerItem(Reduction::PerEntity) | RankedSource::Rows => { + resolve_column_ref(&ColumnRef::SampleValue, child.schema()) + } + } +} + +/// What a top-k's input rows are, seen through a renaming `Project`, a +/// value `HAVING`'s `Filter`, a finalize or a summary readout. +enum RankedSource { + /// Another top-k's ranked rows, grouped by this reduction. + TopK(Reduction), + /// One row per item: a one-measure aggregate (or a summary build), per + /// group of this reduction or per series. + OneRowPerItem(Reduction), + /// Any other rows, possibly several per item. + Rows, +} + +fn ranked_source(child: &I) -> RankedSource { let mut node = child.clone(); - let reduction = loop { + loop { match node.operator() { // Only a renaming keeps the measure last. Operator::NonASAP(NonASAPOp::Project { cols, child, .. }) @@ -36,23 +58,73 @@ pub fn ranked_column(child: &I) -> Result node = child, - Operator::ASAP(ASAPOp::SummaryAgg { reduction, .. }) => break Some(reduction), + Operator::ASAP(ASAPOp::SummaryAgg { reduction, .. }) => { + return RankedSource::OneRowPerItem(reduction) + } Operator::NonASAP(NonASAPOp::Aggregate { reduction, measures, .. }) if measures.len() == 1 => { if matches!(measures[0], crate::ir::operator::AggIntent::TopK { .. }) { - return Ok(reduction.group_keys().map_or(0, |keys| keys.len())); + return RankedSource::TopK(reduction); } - break Some(reduction); + return RankedSource::OneRowPerItem(reduction); } - _ => break None, + _ => return RankedSource::Rows, } - }; - match reduction { - Some(Reduction::Reduce(_)) => Ok(child.schema().fields.len() - 1), - _ => resolve_column_ref(&ColumnRef::SampleValue, child.schema()), + } +} + +/// Whether the item columns `item_columns` of `input` identify each item +/// completely: `input` lists every column its rows carry (it is closed), or +/// the items include the realized PromQL series identity. An open PromQL +/// label set may carry unlisted labels, so its listed columns cannot. +pub(crate) fn item_identity_is_complete( + input: &crate::ir::schema::Schema, + item_columns: impl IntoIterator, +) -> bool { + input.closed + || item_columns + .into_iter() + .any(|index| input.fields[index].name == PROMQL_SERIES_IDENTITY) +} + +/// The unique key of ranked rows (one row per partition and item) with +/// `columns` columns, the ranked value at `value`: every other column. The +/// one rule for a top-k's ranked rows, exact or a heap's readout. +pub(crate) fn ranked_rows_unique_keys(columns: usize, value: ColumnId) -> Vec> { + let key: Vec = (0..columns).filter(|&column| column != value).collect(); + if key.is_empty() { + Vec::new() + } else { + vec![key] + } +} + +/// The unique keys of an exact top-k's ranked rows (`output`, the +/// projection [`ranked_row_projection`] gives, its ranked value after the +/// `partitions` keys) over `child`: one row per (partition, item) when +/// `child` has one row per item whose identity is complete +/// ([`item_identity_is_complete`]); else the projection's own keys. +pub(crate) fn exact_topk_unique_keys( + child: &I, + partitions: usize, + output: &crate::ir::schema::Schema, +) -> Vec> { + let item_columns = (0..child.schema().fields.len()).filter(|&index| { + output + .fields + .iter() + .skip(partitions + 1) + .any(|field| field.name == child.schema().fields[index].name) + }); + if matches!(ranked_source(child), RankedSource::OneRowPerItem(_)) + && item_identity_is_complete(child.schema(), item_columns) + { + ranked_rows_unique_keys(output.fields.len(), partitions) + } else { + output.unique_keys.clone() } } @@ -153,3 +225,108 @@ pub fn series_identity_item( SummaryInputExpr::Tuple(items) } } + +#[cfg(test)] +mod tests { + use std::rc::Rc; + use std::time::Duration; + + use crate::ir::operator::arguments::{Reduction, Source}; + use crate::ir::operator::AggIntent; + use crate::ir::scalar::ColumnRef; + use crate::ir::schema::series_identity::with_promql_series_identity; + use crate::ir::schema::{DataType, Field, FieldDataType, Schema}; + use crate::ir::{ + ASAPOp, NonASAPOp, Operator, OperatorNode, ProjectItem, ScalarExpr, TimeRangeKind, + }; + use crate::summary_type::{SketchAlgorithm, SketchStatistic, SummaryUpdate, WeightDomain}; + + fn node(operator: Operator) -> Rc { + OperatorNode::new_shared(operator).unwrap() + } + + /// `topk by (job) (10, sum_over_time(m[1m]))` over series whose identity + /// is realized: the exact top-k and a heap's ranked readout of the same + /// rows (a `Project` naming the estimate's columns as the top-k's) + /// derive the same unique keys, one row per (job, series). + #[test] + fn exact_topk_and_heap_readout_derive_the_same_unique_keys() { + let open = Schema::with_time_index( + vec![ + Field::plain("ts", DataType::Timestamp, false), + Field::plain("value", DataType::Float64, false), + Field::plain("job", DataType::Utf8, true), + ], + 0, + vec![], + ); + let rows = with_promql_series_identity(&node(Operator::NonASAP(NonASAPOp::Scan { + source: Source::TimeSeries { metric: "m".into() }, + predicates: vec![], + schema: open, + }))) + .unwrap(); + let window = node(Operator::NonASAP(NonASAPOp::TimeRange { + range: Duration::from_secs(60), + kind: TimeRangeKind::Range, + child: rows, + })); + let per_series = node(Operator::NonASAP(NonASAPOp::Aggregate { + child: Rc::clone(&window), + reduction: Reduction::PerEntity, + measures: vec![AggIntent::Sum { col: None }], + output_names: vec![String::new()], + filters: vec![None], + having: None, + })); + let exact = node(Operator::NonASAP(NonASAPOp::Aggregate { + child: per_series, + reduction: Reduction::by(vec![2]), + measures: vec![AggIntent::TopK { k: 10 }], + output_names: vec![String::new()], + filters: vec![None], + having: None, + })); + let heap = node(Operator::ASAP(ASAPOp::SummaryAgg { + summary_type: FieldDataType::Sketch(SketchAlgorithm::CountSketchWithHeap), + input: SummaryUpdate { + item: Some(super::series_identity_item(&window.schema, &[2])), + weight: crate::summary_type::SummaryInputExpr::Column(ColumnRef::SampleValue), + weight_domain: WeightDomain::UnknownOrSigned, + }, + reduction: Reduction::by(vec![2]), + filter: None, + child: window, + })); + let estimate = node(Operator::ASAP(ASAPOp::SummaryEstimate { + summary_input: heap, + query: SketchStatistic::TopK { k: 10 }, + })); + let estimated = estimate.schema.fields.len() - 1; + let cols = exact + .schema + .fields + .iter() + .enumerate() + .map(|(index, field)| ProjectItem { + alias: Some(field.name.clone()), + expr: ScalarExpr::Column(if index == 1 { + estimated + } else { + estimate + .schema + .fields + .iter() + .position(|input| input.name == field.name) + .unwrap() + }), + }) + .collect(); + let readout = node(Operator::NonASAP(NonASAPOp::Project { + cols, + child: estimate, + })); + assert!(!exact.schema.unique_keys.is_empty()); + assert_eq!(exact.schema.unique_keys, readout.schema.unique_keys); + } +} diff --git a/crates/types/src/stages/logical/candidate.rs b/crates/types/src/stages/logical/candidate.rs index fe85898aa..fd561c7e6 100644 --- a/crates/types/src/stages/logical/candidate.rs +++ b/crates/types/src/stages/logical/candidate.rs @@ -27,8 +27,12 @@ pub struct CandidateForMemoGroup { /// `expression.operator`, in [`Operator::children`] order. Changed only /// through [`Memo::set_candidate_input_requirements`](crate::stages::Memo::set_candidate_input_requirements). pub input_requirements: Vec, - /// The groups a fused computation also implements, beyond the group - /// whose candidate it is; empty otherwise. + /// A fused candidate computes, as one operator, a sub-DAG pattern of + /// several operators in one appearance of the sub-expression (a top-k + /// over an aggregate as one heap summary; a sum over a sum as one + /// aggregate): the groups of the operators it replaces. Empty otherwise. + /// Reuse across appearances is Pass 2's, not fusion (concepts doc §3, + /// "Fused groups"). pub fused_groups: Vec, /// Which rule added it. Not in the formulation: kept for /// `stage_pipeline --text` and the viewer (approved 2026-11-05). diff --git a/crates/types/src/stages/logical/group.rs b/crates/types/src/stages/logical/group.rs index 4fdde2aaf..44fa2f849 100644 --- a/crates/types/src/stages/logical/group.rs +++ b/crates/types/src/stages/logical/group.rs @@ -7,7 +7,9 @@ use super::aggregate_coverage::{aggregate_coverage, AggregateCoverage, CoverageE use super::column_properties::{column_lineage_and_signs, ColumnLineage, ValueSign}; use crate::ir::operator::arguments::{AtModifier, Source, TimeShift}; use crate::ir::operator::input::OperatorInput; -use crate::ir::schema::Schema; +use crate::ir::scalar::column_resolution::ResolveError; +use crate::ir::schema::topk::ranked_column; +use crate::ir::schema::{ColumnId, Schema}; use crate::ir::ASAPOp; use crate::ir::SchemaDerivationError; use crate::ir::{NonASAPOp, ScalarExpr}; @@ -221,3 +223,25 @@ impl OperatorInput for MemoGroupAsInput<'_> { self.group().group_properties.scanned_sources.clone() } } + +/// The column a top-k reading memo group `group` ranks it by +/// ([`ranked_column`](crate::ir::schema::topk) over the group as an input). +pub fn ranked_column_of_group(memo: &Memo, group: MemoGroupId) -> Result { + ranked_column(&MemoGroupAsInput { + memo, + group_id: group, + }) +} + +/// [`raw_data_samples_of_metric`](crate::summary_type::raw_data_samples_of_metric) +/// of memo group `group`: the metric whose raw data samples, or plain sums of +/// them, are every value the group outputs. +pub fn raw_data_samples_of_metric_of_group(memo: &Memo, group: MemoGroupId) -> Option { + crate::summary_type::raw_data_samples_of_metric(&MemoGroupAsInput { + memo, + group_id: group, + }) +} + +#[cfg(test)] +mod tests; diff --git a/crates/types/src/stages/logical/group/tests.rs b/crates/types/src/stages/logical/group/tests.rs new file mode 100644 index 000000000..59878ff41 --- /dev/null +++ b/crates/types/src/stages/logical/group/tests.rs @@ -0,0 +1,51 @@ +//! The group-scope helpers over a memo group: the column a top-k ranks +//! ([`ranked_column_of_group`]) and the metric whose raw data samples a +//! group outputs ([`raw_data_samples_of_metric_of_group`]). + +use super::*; +use crate::ir::operator::arguments::Reduction; +use crate::ir::operator::AggIntent; +use crate::ir::schema::DataType; +use crate::test_support::memo_fixtures::{aggregate, range, scan}; +use crate::workload::DataWorkload; + +/// A top-k over a one-measure grouped aggregate ranks its value, the last +/// column; over per-series rows, the sample value. +#[test] +fn ranked_column_of_group_is_the_measure_or_the_sample_value() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = memo + .find_or_add_group(scan("m", &[("job", DataType::Utf8)], vec![])) + .unwrap(); + let by_job = memo + .find_or_add_group(aggregate( + Reduction::by(vec![2]), + AggIntent::Sum { col: None }, + rows, + )) + .unwrap(); + assert_eq!(ranked_column_of_group(&memo, by_job), Ok(1)); + assert_eq!(ranked_column_of_group(&memo, rows), Ok(1)); +} + +/// The raw data samples of `m` reach a group through a range and a plain +/// sum, not through a rate. +#[test] +fn raw_data_samples_of_metric_of_group_follows_ranges_and_plain_sums() { + let mut memo = Memo::new(&DataWorkload::default()); + let rows = memo.find_or_add_group(scan("m", &[], vec![])).unwrap(); + let window = memo.find_or_add_group(range(60_000, rows)).unwrap(); + let summed = memo + .find_or_add_group(aggregate( + Reduction::PerEntity, + AggIntent::Sum { col: None }, + window, + )) + .unwrap(); + let rated = memo + .find_or_add_group(aggregate(Reduction::PerEntity, AggIntent::Rate, window)) + .unwrap(); + let metric = |group| raw_data_samples_of_metric_of_group(&memo, group); + assert_eq!(metric(summed), Some("m".to_string())); + assert_eq!(metric(rated), None); +} diff --git a/crates/types/src/stages/logical/memo/mod.rs b/crates/types/src/stages/logical/memo/mod.rs index 69443a586..517fb9d32 100644 --- a/crates/types/src/stages/logical/memo/mod.rs +++ b/crates/types/src/stages/logical/memo/mod.rs @@ -11,6 +11,8 @@ use super::group::{ MemoGroupError, }; use crate::accuracy::AccuracyTarget; +use crate::ir::operator::input::InputOrTemporaryBuild; +use crate::ir::schema::Schema; use crate::ir::Operator; use crate::ir::QueryRoot; use crate::stages::{ @@ -148,6 +150,52 @@ impl Memo { Ok(id) } + /// The output schema `expression` would have as a new group, without + /// adding anything: the dry run of [`Self::find_or_add_group`], which a + /// rule calls to decide whether a way to compute a group can be built + /// before it adds any of the way's groups. `expression` reads memo + /// groups or pending expressions, not yet in the memo: the input + /// `MemoGroupId(n + k)`, `n` the memo's group count, is + /// `pending[k]`, the id it would get as a new group, with its output + /// schema (from earlier calls). The expression's output schema must + /// derive and its inputs pass validation. + /// + /// It mirrors `validate_expression_over_input_groups`, minus the merge + /// coverage check, which runs when a merge is added. + /// + /// # Panics + /// + /// When a pending expression reads one at or after it. + pub fn output_schema_of_pending_expression( + &self, + pending: &[(Operator, Schema)], + expression: &Operator, + ) -> Result { + fn input<'m>( + memo: &'m Memo, + built: &[InputOrTemporaryBuild>], + group_id: MemoGroupId, + ) -> InputOrTemporaryBuild> { + match (group_id.0 as usize).checked_sub(memo.groups.len()) { + None => InputOrTemporaryBuild::Input(MemoGroupAsInput { memo, group_id }), + Some(index) => built + .get(index) + .expect("a pending expression reads only earlier ones") + .clone(), + } + } + let mut built = Vec::with_capacity(pending.len()); + for (pending_expression, schema) in pending { + let operator = + pending_expression.map_children(|&group_id| input(self, &built, group_id)); + built.push(InputOrTemporaryBuild::with_schema(operator, schema.clone())); + } + let operator = expression.map_children(|&group_id| input(self, &built, group_id)); + let schema = operator.output_schema()?; + operator.validate_inputs()?; + Ok(schema) + } + /// Adds `candidate` to `group`'s candidates and returns its id, unless /// the group already has a candidate with the same expression /// (`same_expression`) and logical properties: then that candidate's diff --git a/crates/types/src/stages/logical/memo/tests.rs b/crates/types/src/stages/logical/memo/tests.rs index 69f81a7b1..136f71d57 100644 --- a/crates/types/src/stages/logical/memo/tests.rs +++ b/crates/types/src/stages/logical/memo/tests.rs @@ -12,7 +12,7 @@ use crate::ir::{ExprSemantics, NonASAPOp, Predicate, ScalarExpr}; use crate::stages::logical::group::MemoGroupAsInput; use crate::stages::{CandidateExpression, LogicalProperties, OriginOfCandidateForMemoGroup}; use crate::summary_type::{SketchAlgorithm, SketchParams, SketchStatistic}; -use crate::test_support::memo_fixtures::{aggregate_where, readout, scan, state}; +use crate::test_support::memo_fixtures::{aggregate_with, readout, scan, state}; /// An unordered `LIMIT 10` over `input`, whose copies may return /// different rows. @@ -411,10 +411,10 @@ fn quantile_agg( filter: Option>, ) -> impl FnOnce(&mut Memo) -> MemoGroupId { over_scan(move |child| { - aggregate_where( + aggregate_with( Reduction::by(by), - AggIntent::Quantile { col, q }, - filter, + vec![(AggIntent::Quantile { col, q }, filter)], + None, child, ) }) @@ -580,3 +580,48 @@ fn signed_zero_and_non_finite_literals_are_different_groups() { } assert!(one_group(literal(f64::INFINITY), literal(f64::INFINITY))); } + +/// A KLL state over the latency scan and its p99 readout, both pending: the +/// readout's schema is the one its group gets once both are added, and +/// nothing is added while deriving it. +#[test] +fn output_schema_of_a_pending_expression_is_its_groups_schema() { + let mut memo = Memo::new(&DataWorkload::default()); + let latency = memo + .find_or_add_group(scan("latency", &[], vec![])) + .unwrap(); + let state_expression = state(FieldDataType::Sketch(SketchAlgorithm::Kll), latency); + let pending_state = MemoGroupId(memo.groups().len() as u32); + let readout_expression = readout(SketchStatistic::Quantile { q: 0.99 }, pending_state); + let before = format!("{memo:?}"); + let state_schema = memo + .output_schema_of_pending_expression(&[], &state_expression) + .unwrap(); + let readout_schema = memo + .output_schema_of_pending_expression( + &[(state_expression.clone(), state_schema.clone())], + &readout_expression, + ) + .unwrap(); + assert_eq!(format!("{memo:?}"), before); + let state_group = memo.find_or_add_group(state_expression).unwrap(); + let readout_group = memo + .find_or_add_group(readout(SketchStatistic::Quantile { q: 0.99 }, state_group)) + .unwrap(); + let schema_of = |group: MemoGroupId| &memo.groups()[group.0 as usize].group_properties.schema; + assert_eq!(schema_of(state_group), &state_schema); + assert_eq!(schema_of(readout_group), &readout_schema); +} + +/// A pending expression whose schema does not derive (a readout of a scan, +/// not of a summary state) is an error, as `find_or_add_group` gives it. +#[test] +fn output_schema_of_a_pending_expression_rejects_what_find_or_add_group_rejects() { + let mut memo = Memo::new(&DataWorkload::default()); + let latency = memo + .find_or_add_group(scan("latency", &[], vec![])) + .unwrap(); + let bad = readout(SketchStatistic::Quantile { q: 0.99 }, latency); + assert!(memo.output_schema_of_pending_expression(&[], &bad).is_err()); + assert!(memo.find_or_add_group(bad).is_err()); +} diff --git a/crates/types/src/stages/logical/mod.rs b/crates/types/src/stages/logical/mod.rs index 0658f80a5..b75e6594d 100644 --- a/crates/types/src/stages/logical/mod.rs +++ b/crates/types/src/stages/logical/mod.rs @@ -18,7 +18,10 @@ pub use candidate::{ }; pub use column_properties::{ColumnLineage, ValueSign}; pub use edge::LogicalEdge; -pub use group::{GroupProperties, MemoGroup, MemoGroupError, MemoGroupId}; +pub use group::{ + ranked_column_of_group, raw_data_samples_of_metric_of_group, GroupProperties, MemoGroup, + MemoGroupError, MemoGroupId, +}; pub use memo::{Memo, MemoQuery}; pub use memo_candidates::LogicalASAPMemoCandidates; pub use requirements::{LogicalRequirements, RequiredAccuracy}; diff --git a/crates/types/src/stages/mod.rs b/crates/types/src/stages/mod.rs index 8a6bdd5e2..aafdbf2ab 100644 --- a/crates/types/src/stages/mod.rs +++ b/crates/types/src/stages/mod.rs @@ -8,20 +8,17 @@ //! live here. mod logical; -mod per_computation_logical_memo_candidates; mod physical; mod pruning; pub use logical::{ - view_coverage, AggregateCoverage, AggregateDefinition, CandidateError, CandidateExpression, - CandidateForMemoGroup, CandidateForMemoGroupId, ColumnLineage, CoverageError, GroupProperties, + ranked_column_of_group, raw_data_samples_of_metric_of_group, view_coverage, AggregateCoverage, + AggregateDefinition, CandidateError, CandidateExpression, CandidateForMemoGroup, + CandidateForMemoGroupId, ColumnLineage, CoverageError, GroupProperties, LogicalASAPMemoCandidates, LogicalEdge, LogicalProperties, LogicalPropertiesError, LogicalRequirements, Memo, MemoGroup, MemoGroupError, MemoGroupId, MemoQuery, OriginOfCandidateForMemoGroup, RequiredAccuracy, ValueSign, }; -pub use per_computation_logical_memo_candidates::{ - ComputationTarget, FusedComputation, HavingEntry, HavingPlacement, HowToComputeAggregateMeasure, -}; pub use physical::{ output_references, producer_satisfies_physical_requirements, EvaluationGrid, ExecutionContext, ExecutionContextId, Lifetime, PhysicalASAPMemoCandidates, PhysicalCandidate, diff --git a/crates/types/src/stages/per_computation_logical_memo_candidates.rs b/crates/types/src/stages/per_computation_logical_memo_candidates.rs deleted file mode 100644 index 5361b3f12..000000000 --- a/crates/types/src/stages/per_computation_logical_memo_candidates.rs +++ /dev/null @@ -1,135 +0,0 @@ -//! The computation-target types Stage 1, Pass 1 builds its candidates from. - -use std::rc::Rc; - -use super::MemoGroupId; -use crate::ir::{OperatorNode, Predicate}; -use crate::summary_type::{ExactKind, SketchAlgorithm}; - -/// How one Pass 1 target is computed: exact or a summary. -/// -/// Each target has exactly one exact option: `ExactAccumulator` when the -/// intent has an exact mergeable state and it can be built, otherwise -/// `Exact`. The plain form would duplicate "accumulator, not materialized"; -/// Stage 2/3 decide materialization and sharing. Which computation is -/// computed is the target's ([`ComputationTarget`]) or its fused -/// computation's ([`FusedComputation`]). -#[derive(Debug, Clone, PartialEq)] -pub enum HowToComputeAggregateMeasure { - /// Plain exact execution of the original sub-DAG; the exact option only - /// when the intent has no exact accumulator form or that form is pruned. - Exact, - /// One or more exact mergeable accumulator states, by accumulator kind, - /// finalized and combined into the measure: one state for `sum`, - /// `count`, `min`, `max`, `rate`, `irate` and `increase`; `[Sum, Count]`, - /// divided, for `avg`. - ExactAccumulator(Vec), - /// An unsized summary family; sized for the measure's accuracy when Pass 1 - /// attaches it to its memo group. - Summary(SketchAlgorithm), -} - -/// Where a target's `HAVING` is applied. Composition (#575) applies it. -/// -/// Only the adjacent form is recorded for push-down: the aggregate's own -/// `having`, or a `Filter` directly above the aggregate (the form the SQL -/// frontend lowers `HAVING` to). A value predicate anywhere above an -/// approximate output gets `guarantee = None` through guarantee propagation -/// (#575); multi-level push-down is tracked in #664. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum HavingPlacement { - /// The predicate reads only group keys and every consumer of the - /// aggregate applies it, so it is pushed below the aggregate as a row - /// predicate (a `Filter` on its input, which drops the group). - BelowAggregate, - /// The predicate reads aggregate values, so it stays a `Filter` above the - /// finalize/estimate output; approximate candidates of this target carry - /// `guarantee = None`, since membership near the threshold may change. - AboveOutput, -} - -/// One `HAVING` over a target's aggregate output. -#[derive(Debug, Clone, PartialEq)] -pub struct HavingEntry { - /// The consumer `Filter` that applies it; `None` for the aggregate's own - /// `having`, which every consumer reads. - pub filter: Option>, - pub predicate: Predicate, - pub placement: HavingPlacement, -} - -/// One measure of an aggregate with at least one realization besides exact -/// execution. The target retains source, grouping, filters, input -/// expressions and evaluation context. -#[derive(Debug, Clone)] -pub struct ComputationTarget { - /// The memo group of the `Aggregate` the measure belongs to. - pub aggregate_group: MemoGroupId, - /// Index into the aggregate's measures. - pub measure_index: usize, - /// The measure's unranked ways to compute it, the exact option first. - pub ways_to_compute: Vec, - /// The measure's own filter; only rows that pass it update the state - /// (`SummaryAgg.filter`). - pub measure_filter: Option, - /// The aggregate's own `having`, then one entry per consumer `Filter` - /// directly above the aggregate. - pub having_filters: Vec, - /// The fused computation of this measure together with the target - /// directly beneath it, offered beside this target's own candidates; - /// `None` when no fusion applies. - pub fused_computation: Option, -} - -/// A target's measure computed together with the targets beneath it, which -/// it absorbs (they are not computed): the whole-expression top-k over a -/// per-item `sum` or `count` (`Summary` of a heap family), or the nested -/// sum, a grouped `sum` over a `sum` (`ExactAccumulator([Sum])`). It has the -/// outer target's aggregate, measure, filter and `HAVING`. -#[derive(Debug, Clone, PartialEq)] -pub struct FusedComputation { - /// Indices, into Pass 1's computation-target list, of the targets it - /// absorbs: the one directly beneath, then, for a whole-expression - /// heap over the raw data samples beneath a grouped sum of per-series sums or - /// counts (`topk(k, sum by (G) (sum_over_time(m[W])))`), the per-series - /// target beneath that, then the targets any of these targets' own fused - /// computations absorb. None of them is computed when this is picked. - pub absorbed_targets: Vec, - /// How the fused computation is computed: exact or a summary. Empty - /// when Pass 1 pruned every one (today only for a family the deployment - /// does not support); the fusion is then not offered. - pub ways_to_compute: Vec, -} - -impl ComputationTarget { - /// How many values this target's digit of a whole-workload choice - /// takes: its own candidates, then its fused computation's. - pub fn choice_count(&self) -> usize { - self.ways_to_compute.len() - + self - .fused_computation - .as_ref() - .map_or(0, |fused| fused.ways_to_compute.len()) - } - - /// How the measure is computed when this target's digit of a - /// whole-workload choice is `index`: the candidate, and the targets it - /// absorbs when the candidate is the fused computation's (past this - /// target's own candidates). `None` past [`Self::choice_count`]. - pub fn computation_for( - &self, - index: usize, - ) -> Option<(&HowToComputeAggregateMeasure, Option<&[usize]>)> { - let own = self.ways_to_compute.len(); - match self.ways_to_compute.get(index) { - Some(candidate) => Some((candidate, None)), - None => { - let fused = self.fused_computation.as_ref()?; - Some(( - fused.ways_to_compute.get(index - own)?, - Some(fused.absorbed_targets.as_slice()), - )) - } - } - } -} diff --git a/crates/types/src/summary_type/mod.rs b/crates/types/src/summary_type/mod.rs index 37c693d90..1ce1ec778 100644 --- a/crates/types/src/summary_type/mod.rs +++ b/crates/types/src/summary_type/mod.rs @@ -22,6 +22,6 @@ pub use parameters::{ StatModelParams, WaveletKind, WaveletParams, EXACT_ACCUMULATOR_STATE_BYTES, KLL_MAX_K, }; pub use statistic::{ - EntityIdentity, NonNegativeWeightProof, SketchStatistic, SummaryInputExpr, SummaryUpdate, - WeightDomain, + raw_data_samples_of_metric, EntityIdentity, NonNegativeWeightProof, SketchStatistic, + SummaryInputExpr, SummaryUpdate, WeightDomain, }; diff --git a/crates/types/src/summary_type/parameter_lists.rs b/crates/types/src/summary_type/parameter_lists.rs index f87db5dbe..5ca4c3b62 100644 --- a/crates/types/src/summary_type/parameter_lists.rs +++ b/crates/types/src/summary_type/parameter_lists.rs @@ -8,7 +8,7 @@ use super::{SketchAlgorithm, SketchParams}; /// (`asap_accuracy::theoretical_guarantee`). /// /// The widths, `k`s, precisions, `alpha`s and heap sizes are today's sizing -/// (`asap_accuracy`'s test-only `size_params`) over the errors ε = 0.1, +/// (`asap_accuracy`'s test-only `guarantee::sizing_oracle`) over the errors ε = 0.1, /// 0.05, 0.02, 0.01, 0.005, 0.002 and 0.001, smallest first, without /// repeats; an `asap_accuracy` test keeps them equal. Distinct counts (KMV, /// and UnivMon's distinct-count shapes) stop at ε = 0.01. Where δ is set by diff --git a/crates/types/src/summary_type/statistic.rs b/crates/types/src/summary_type/statistic.rs index 90e4d3aaf..3dc78475f 100644 --- a/crates/types/src/summary_type/statistic.rs +++ b/crates/types/src/summary_type/statistic.rs @@ -2,7 +2,11 @@ use serde::{Deserialize, Serialize}; +use crate::ir::operator::arguments::Source; +use crate::ir::operator::input::OperatorInput; +use crate::ir::operator::AggIntent; use crate::ir::scalar::ColumnRef; +use crate::ir::{NonASAPOp, Operator}; /// One summary-state update. `item` identifies a keyed item when the family /// is keyed; `weight` is the observation/update expression applied to state. @@ -134,9 +138,95 @@ pub enum SketchStatistic { TopK { k: usize }, } +/// The metric whose raw data samples, or plain sums of them, are every value +/// `input` outputs, or `None`: walking down through a time range, an +/// `offset`-only time shift (it moves the window, not the samples) and a +/// plain `sum`, to a time-series scan. Any other operator (rate and +/// arithmetic included) ends it. The metric's type is not read here: whether +/// its samples are non-negative is plan selection's question +/// ([`WeightDomain::RawDataSamplesOfMetric`]). +pub fn raw_data_samples_of_metric(input: &I) -> Option { + let Operator::NonASAP(operator) = input.operator() else { + return None; + }; + match operator { + NonASAPOp::Scan { + source: Source::TimeSeries { metric }, + .. + } => Some(metric), + NonASAPOp::TimeRange { child, .. } => raw_data_samples_of_metric(&child), + NonASAPOp::TimeShift { shift, child } if shift.at.is_none() => { + raw_data_samples_of_metric(&child) + } + NonASAPOp::Aggregate { + measures, child, .. + } if matches!(measures.as_slice(), [AggIntent::Sum { col: None }]) => { + raw_data_samples_of_metric(&child) + } + _ => None, + } +} + #[cfg(test)] mod tests { use super::*; + use crate::ir::operator::arguments::Reduction; + use crate::ir::schema::{DataType, Field, Schema}; + use crate::ir::{OperatorNode, TimeRangeKind}; + use std::rc::Rc; + use std::time::Duration; + + /// The raw data samples of `m` reach a node through a range, an + /// `offset`-only time shift and a plain `sum`; a rate ends them. + #[test] + fn raw_data_samples_of_metric_follows_ranges_shifts_and_plain_sums() { + let node = + |operator: Operator>| OperatorNode::new_shared(operator).unwrap(); + let rows = node(Operator::NonASAP(NonASAPOp::Scan { + source: Source::TimeSeries { metric: "m".into() }, + predicates: vec![], + schema: Schema::with_time_index( + vec![ + Field::plain("ts", DataType::Timestamp, false), + Field::plain("value", DataType::Float64, false), + ], + 0, + vec![], + ), + })); + let window = node(Operator::NonASAP(NonASAPOp::TimeRange { + range: Duration::from_secs(60), + kind: TimeRangeKind::Range, + child: rows, + })); + let per_series = |measure: AggIntent| { + node(Operator::NonASAP(NonASAPOp::Aggregate { + child: Rc::clone(&window), + reduction: Reduction::PerEntity, + measures: vec![measure], + output_names: vec![String::new()], + filters: vec![], + having: None, + })) + }; + assert_eq!(raw_data_samples_of_metric(&window), Some("m".to_string())); + let shifted = node(Operator::NonASAP(NonASAPOp::TimeShift { + shift: crate::ir::operator::arguments::TimeShift { + offset_ms: 60_000, + at: None, + }, + child: Rc::clone(&window), + })); + assert_eq!(raw_data_samples_of_metric(&shifted), Some("m".to_string())); + assert_eq!( + raw_data_samples_of_metric(&per_series(AggIntent::Sum { col: None })), + Some("m".to_string()) + ); + assert_eq!( + raw_data_samples_of_metric(&per_series(AggIntent::Rate)), + None + ); + } #[test] fn keyed_summary_input_and_topk_evaluation_round_trip() { diff --git a/crates/types/src/test_support/memo_fixtures.rs b/crates/types/src/test_support/memo_fixtures.rs index 5da450b33..4e494efa0 100644 --- a/crates/types/src/test_support/memo_fixtures.rs +++ b/crates/types/src/test_support/memo_fixtures.rs @@ -100,23 +100,28 @@ pub fn aggregate( measure: AggIntent, child: MemoGroupId, ) -> Operator { - aggregate_where(reduction, measure, None, child) + aggregate_with(reduction, vec![(measure, None)], None, child) } -/// `Aggregate(reduction; measure)` over `child`, the measure over the rows -/// `filter` keeps (`None`: every row). -pub fn aggregate_where( +/// `Aggregate(reduction; measures)` over `child` with `having`: each measure +/// unnamed, over the rows its filter keeps (`None`: every row). With no +/// filter the filter list is empty, as the frontends write it. +pub fn aggregate_with( reduction: Reduction, - measure: AggIntent, - filter: Option>, + measures: Vec<(AggIntent, Option>)>, + having: Option>, child: MemoGroupId, ) -> Operator { + let (measures, mut filters): (Vec<_>, Vec<_>) = measures.into_iter().unzip(); + if filters.iter().all(Option::is_none) { + filters.clear(); + } Operator::NonASAP(NonASAPOp::Aggregate { reduction, - measures: vec![measure], - output_names: vec![], - filters: filter.map_or_else(Vec::new, |filter| vec![Some(filter)]), - having: None, + output_names: vec![String::new(); measures.len()], + measures, + filters, + having, child, }) } diff --git a/docs/design_docs/concepts/accuracy-models.md b/docs/design_docs/concepts/accuracy-models.md index 12004cb8b..b1f7c8b2e 100644 --- a/docs/design_docs/concepts/accuracy-models.md +++ b/docs/design_docs/concepts/accuracy-models.md @@ -188,8 +188,9 @@ another implementation with the same algorithm name. In particular, a named empirical calibration is different from an arbitrary benchmark's maximum observed error; both its confidence and applicability must remain explicit. -Default sizing is `asap_accuracy::sizing::default_size_params`, which dispatches to the -estimator modules; a summary shared by several readers is sized with each +Sizing is each algorithm's predefined parameter list, `parameter_list` +(`crates/types/src/summary_type/parameter_lists.rs`), which a test keeps equal +to the estimator modules' closed-form sizing over an error grid; a summary shared by several readers is sized with each parameter's largest value among them. Where an error bound grows as the failure probability shrinks (a KLL's `k`, a distinct-count UnivMon's heap), each reader's parameter is first resized to the readers' smallest failure diff --git a/docs/design_docs/decisions/concat-unique-keys.md b/docs/design_docs/decisions/concat-unique-keys.md index 4e18cd28f..995eb99a6 100644 --- a/docs/design_docs/decisions/concat-unique-keys.md +++ b/docs/design_docs/decisions/concat-unique-keys.md @@ -75,7 +75,7 @@ Both current `Concat`-constructing call sites, and every consumer of test fixtures) — none of them builds a fresh `Concat` with a `Dedup` on top that this feature could remove. - **Every consumer of `Schema::unique_keys`** in the DAG, to check for a - cost beyond "a literal `Dedup` node": `share_common_sub_dags` (crate-private in `asap_stage0_memo`, `cse.rs`) + cost beyond "a literal `Dedup` node": `share_common_sub_dags` (now `Memo::find_or_add_group`, `crates/types/src/stages/logical/memo/hash_consing.rs`) (gates CSE producer-sharing on `Schema::has_unique_key()`) and `asap_aware_mapping::rollup::is_legal_rollup_source` (gates rollup-source legality the same way, on an *`Aggregate`'s* own output schema). Neither diff --git a/docs/design_docs/decisions/cse-cost-model.md b/docs/design_docs/decisions/cse-cost-model.md index 45d757f58..641fbbdaa 100644 --- a/docs/design_docs/decisions/cse-cost-model.md +++ b/docs/design_docs/decisions/cse-cost-model.md @@ -16,7 +16,9 @@ elimination) to identify eligible, structurally identical computations. A shared logical node records an opportunity for reuse; selecting maintained state or independent execution is a separate planning decision. -[`share_common_sub_dags`](../../../crates/stage0-memo/src/cse.rs) +`share_common_sub_dags` (now Stage 0's +[`memo_of_queries`](../../../crates/stage0-memo/src/lib.rs), hash-consing through +`Memo::find_or_add_group`) (issue #223 stages 1-2, PR #235) already *detects* every structurally-identical, legally-shareable (`Schema::unique_keys`-gated) sub-DAG and shares it **unconditionally** — there is no cost gate on top of legality. This document @@ -75,7 +77,8 @@ same way a real cost-based optimizer would. ## Layering constraint -`share_common_sub_dags` lives in `asap-types::pre_asap` — a lower layer that +`share_common_sub_dags` (now `memo_of_queries` in `asap_stage0_memo`, with +`Memo::find_or_add_group` in `asap_types::stages`) lives in `asap-types::pre_asap` — a lower layer that `asap-aware-mapping` (which owns `CostModel`) depends on, never the reverse. Detection therefore cannot consult cost even if it wanted to. This is why stage 1/2's detection stays unconditional (correctly, as a legality-only diff --git a/docs/design_docs/proposals/joint-planning-implementation-plan.md b/docs/design_docs/proposals/joint-planning-implementation-plan.md index 30fa4bfca..39119c768 100644 --- a/docs/design_docs/proposals/joint-planning-implementation-plan.md +++ b/docs/design_docs/proposals/joint-planning-implementation-plan.md @@ -12,7 +12,7 @@ Preserve supported accuracy semantics, physical eligibility, cost objectives, sc | Scope | Current implementation | Responsibility | | --- | --- | --- | -| Logical identity | `stage0-memo/src/lib.rs`; `types/src/stages/` | `DagOfLogicalMemoGroups`, `MemoGroup` (`asap_types::stages`; built by `memo_of_queries`), stable initial query/group references. | +| Logical identity | `stage0-memo/src/lib.rs`; `types/src/stages/` | `Memo`, `MemoGroup` (`asap_types::stages`; built by `memo_of_queries`, hash-consed by `Memo::find_or_add_group`), stable initial query/group references. | | Computation and sharing rules | `stage1-pass2-reuse-candidates/src/{lib.rs,rules.rs,rules/}` | Populate groups, retain local candidates, expose shared states and compatible rewrites. | | Physical legality | `stage2-physical-optimization` | Executable operators, timing and materialization eligibility. | | Candidate dependency inventory | `stage2-physical-optimization/src/lib.rs`; `types/src/stages/physical` | Local `PhysicalCandidate`, `ProducerRequirement` (`asap_types::stages`), compatible producers, structural pruning; Stage 3 builds the selected plan (`PhysicalASAPDAG`) directly. Stage 2 makes no execution-scope copies; today's Stage 3 engine makes its own (`stage3-plan-selection/src/search/candidates/scopes.rs`). | diff --git a/docs/design_docs/proposals/joint-planning-search.md b/docs/design_docs/proposals/joint-planning-search.md index 937f21269..907766621 100644 --- a/docs/design_docs/proposals/joint-planning-search.md +++ b/docs/design_docs/proposals/joint-planning-search.md @@ -630,7 +630,7 @@ After selection, the planner reconstructs the DAG and evaluates accuracy, latenc ## 8. Implementation and Evaluation -The implementation uses `DagOfLogicalMemoGroups` and `MemoGroup` for initial identities, and `Memo` / `CandidateForMemoGroup` for logical expansion. Local `PhysicalCandidate` choices have explicit producer requirements and compatible connections. Selection reconstructs a `PhysicalWorkloadPlan` and validates its resulting graph through the configured evaluators. The sole production engine is `CandidateConnections`; bounded and exhaustive modes use the same candidate representation and solver. Existing supported runtime operators determine which configurations can be generated. +The implementation uses `Memo` and `MemoGroup` (Stage 0's `memo_of_queries`) for initial identities, and `Memo` / `CandidateForMemoGroup` for logical expansion. Local `PhysicalCandidate` choices have explicit producer requirements and compatible connections. Selection reconstructs a `PhysicalWorkloadPlan` and validates its resulting graph through the configured evaluators. The sole production engine is `CandidateConnections`; bounded and exhaustive modes use the same candidate representation and solver. Existing supported runtime operators determine which configurations can be generated. The candidate memo and its Pass 2 rules belong in `stage1-pass2-reuse-candidates`; physical eligibility remains authoritative in `stage2-physical-optimization`. Within selection, candidate inventory/reconstruction, MILP construction, evaluator refinement, pricing support, and route orchestration have separate scopes. State-local choices belong in candidates; cross-candidate decisions use connections and constraints. The retired `CouplingSite` selector representation and legacy search routes are removed rather than retained under new names. diff --git a/docs/design_docs/proposals/planner-layering-example2-acceptance.md b/docs/design_docs/proposals/planner-layering-example2-acceptance.md index b0d35a810..34b77fbec 100644 --- a/docs/design_docs/proposals/planner-layering-example2-acceptance.md +++ b/docs/design_docs/proposals/planner-layering-example2-acceptance.md @@ -67,18 +67,22 @@ workload itself. | Invariant | Test | Status | |---|---|---| -| Once recognized, the SQL workload has the stand-in's Pass 1 options | `stage1_logical_asap_optimization_sql_has_the_standin_options` | passes | -| Each statistic has an exact and a UnivMon option | `stage1_logical_asap_optimization_pass1_offers_exact_and_univmon_for_each_statistic` | passes | -| Q1 has a specialized distinct-count summary (HLL or KMV) | `stage1_logical_asap_optimization_pass1_offers_a_distinct_count_summary` | passes | -| Q2 and Q3 have a specialized entropy and norm summary | `stage1_logical_asap_optimization_pass1_offers_specialized_entropy_and_l2_summaries` | ignored: needs Pass 1 specialized entropy and L2 summary families (#444) | -| Every combination of the queries' own options is kept, with no shared summary | `stage1_logical_asap_optimization_keeps_every_independent_combination` | passes | -| A candidate has one UnivMon build read by all three queries, feeding a distinct-count, an entropy and an L2 estimate | `stage1_logical_asap_optimization_summary_capability_adds_one_univmon_for_all_three` | passes | -| For each pair, a candidate shares one UnivMon between the two while the third takes each of its own options | `stage1_logical_asap_optimization_summary_capability_adds_pairwise_shared_univmons` | passes | -| A shared UnivMon takes each parameter's largest value among its consumers, each sized alone | `stage1_logical_asap_optimization_shared_univmon_takes_each_parameters_largest_own_size` | passes | -| UnivMon is sized per target: Q3's (ε = 0.01) is larger than Q2's (ε = 0.05) | `stage1_logical_asap_optimization_univmon_is_sized_per_accuracy_target` | passes | -| Only a UnivMon is ever shared across statistics | `stage1_logical_asap_optimization_only_univmon_is_shared_across_statistics` | passes | -| Stage 1 does not read the distinct bound; Q1's HLL failure probability stays symbolic in the source's bound | `stage1_logical_asap_optimization_leaves_the_hll_failure_probability_symbolic` | passes | -| Candidates are valid DAGs with unique ids | `stage1_logical_asap_optimization_candidates_are_valid_and_uniquely_named` | passes | +| Once recognized, the SQL workload has the stand-in's Pass 1 options | `stage1_logical_asap_optimization_sql_has_the_standin_options` | deleted | +| Each statistic has an exact and a UnivMon option | `stage1_logical_asap_optimization_pass1_offers_exact_and_univmon_for_each_statistic` | deleted | +| Q1 has a specialized distinct-count summary (HLL or KMV) | `stage1_logical_asap_optimization_pass1_offers_a_distinct_count_summary` | deleted | +| Q2 and Q3 have a specialized entropy and norm summary | `stage1_logical_asap_optimization_pass1_offers_specialized_entropy_and_l2_summaries` | deleted | +| Every combination of the queries' own options is kept, with no shared summary | `stage1_logical_asap_optimization_keeps_every_independent_combination` | deleted | +| A candidate has one UnivMon build read by all three queries, feeding a distinct-count, an entropy and an L2 estimate | `stage1_logical_asap_optimization_summary_capability_adds_one_univmon_for_all_three` | deleted | +| For each pair, a candidate shares one UnivMon between the two while the third takes each of its own options | `stage1_logical_asap_optimization_summary_capability_adds_pairwise_shared_univmons` | deleted | +| A shared UnivMon takes each parameter's largest value among its consumers, each sized alone | `stage1_logical_asap_optimization_shared_univmon_takes_each_parameters_largest_own_size` | deleted | +| UnivMon is sized per target: Q3's (ε = 0.01) is larger than Q2's (ε = 0.05) | `stage1_logical_asap_optimization_univmon_is_sized_per_accuracy_target` | deleted | +| Only a UnivMon is ever shared across statistics | `stage1_logical_asap_optimization_only_univmon_is_shared_across_statistics` | deleted | +| Stage 1 does not read the distinct bound; Q1's HLL failure probability stays symbolic in the source's bound | `stage1_logical_asap_optimization_leaves_the_hll_failure_probability_symbolic` | deleted | +| Candidates are valid DAGs with unique ids | `stage1_logical_asap_optimization_candidates_are_valid_and_uniquely_named` | deleted | + +The tests in this table no longer exist. Pass 1 is tested over memo groups instead: the +Pass 1 crate's `tests.rs`, and `pass1_candidates.rs` and `pass1_candidates_sql.rs` in +`crates/integration-tests/tests/`. ### Physical ASAP-aware optimization diff --git a/docs/design_docs/proposals/planner-layering.md b/docs/design_docs/proposals/planner-layering.md index 52bd0b1ba..eedea2fb3 100644 --- a/docs/design_docs/proposals/planner-layering.md +++ b/docs/design_docs/proposals/planner-layering.md @@ -271,19 +271,19 @@ lists each stage's input and output types. | Component | Code | What it is | |---|---|---| -| Memo group | `MemoGroup`, numbered by `MemoGroupId` | One distinct logical sub-expression: its logical node, its child groups, the groups that read it (`parent_groups()`) and the queries that reach it (`reached_by_queries()`). Groups are numbered children first; `DagOfLogicalMemoGroups::query_roots` holds each query's root over groups. | -| DAG of logical memo groups | `DagOfLogicalMemoGroups` | Stage 0's groups, before any implementation choice: the workload's logical DAG hash-consed (below). | -| Memo | `Memo` | The groups, each query's root over them, and the candidates for each memo group (`candidates[group]`). Pass 1 creates it from the DAG of logical memo groups; the Pass 2 rules add candidates and groups. | -| Candidate for a memo group | `CandidateForMemoGroup` | One way to implement a group over child groups. `fused_groups`: for a fused computation, the groups it absorbs beyond the group whose candidate it is; empty otherwise. `root_node`: its own nodes, down to the nodes of the groups it reads. `input_groups`: the groups it reads, whose implementations are chosen separately. `origin`: the rule that made it (`OriginOfCandidateForMemoGroup`, below). `accuracy_budget_parts`: the number of equal shares of the accuracy budget its summaries are sized for, 1 for the whole budget and `n` when it is one of `n` approximate inputs of a query. | +| Memo group | `MemoGroup`, numbered by `MemoGroupId` | One distinct logical sub-expression: its logical node, its child groups, the groups that read it (`parent_groups()`) and the queries that reach it (`reached_by_queries()`). Groups are numbered children first; `Memo::queries` holds each query's root over groups (`MemoQuery::root`), `Memo::root_groups` the groups the roots read and `Memo::queries_rooted_at` the queries whose root reads a group. | +| Memo | `Memo` | The groups, each query's root over them, and the candidates for each memo group (`MemoGroup::candidates`). Stage 0 creates it without candidates, before any implementation choice: the workload's logical DAG hash-consed (below). Pass 1 adds each group's initial candidates and the groups they read; the Pass 2 rules add candidates and groups. | +| Candidate for a memo group | `CandidateForMemoGroup` | One way to implement a group over child groups. `expression`: one operator, with its arguments, whose children are the groups it reads, whose implementations are chosen separately. `logical_properties`: its summary build's parameters, one configuration of the algorithm's predefined list (`parameter_list`); none for an exact operator. `input_requirements`: one per group it reads; Pass 1 leaves them empty. `fused_groups`: for a fused computation, the groups it absorbs beyond the group whose candidate it is; empty otherwise. `origin`: the rule that made it (`OriginOfCandidateForMemoGroup`, below). | | Concrete summary-state group | a `MemoGroup` whose node is a `SummaryAgg` or a `SummaryTumblingWindowChain` | One summary state at one size, or one tumbling-window chain at one layout, that several readers may share. A choice several groups depend on, such as a shared size or a tumbling-window grid, is one concrete group per value, when two or more readers may read that value, and each of them gets a candidate reading that group: of two readers needing a KLL with `k ≥ 345` and `k ≥ 200`, both may read a group `KLL(345)`, and the second may also keep its own private `KLL(200)`. Choosing a value is choosing a group, so the memo has no separate type for such a choice. The other Pass 2 rules add groups too (below). | **Stage 0: hash-consing.** Hash-consing merges structurally equal nodes into one. It makes no implementation choice, so this section counts it as Stage 0 (its output); the code runs it as Stage 1 starts, which is why [Stage inputs and outputs](#stage-inputs-and-outputs-whole-workload-candidates-and-memo) -lists `memo_of_queries` with Pass 1. `memo_of_queries` runs -`share_common_sub_dags` (`crates/stage0-memo/src/cse.rs`) over the frontends' -roots and numbers the shared nodes as groups. Two structurally equal nodes +lists `memo_of_queries` with Pass 1. `memo_of_queries` +(`crates/stage0-memo/src/lib.rs`) visits the frontends' roots children first +and finds or adds each node's group with `Memo::find_or_add_group`, whose +expression equality is in `crates/types/src/stages/logical/memo/hash_consing.rs`. Two structurally equal nodes become one group only when sharing them is legal, that is, when every reader of the shared node reads the rows it would read alone. Equal nodes are interned children first, so they always read one input, and a node is legal @@ -310,7 +310,7 @@ rule's origin, and gives each reader a candidate that reads that group. | `OriginOfCandidateForMemoGroup` | Added by | Candidates | |---|---|---| -| `Pass1` | `try_populate_pass1` (`pass1/memo_population.rs`) | Every Pass 1 choice of the group's measures: exact, exact accumulator, each summary family and size, and fused computations. Each summary choice comes at every `accuracy_budget_parts` from 1 to the most approximate inputs a query reaching the group has. A fused candidate implements the groups it absorbs only when no other reader needs them; otherwise they stay groups of their own. | +| `Pass1` | `pass1_memo` (`stage1-pass1-per-computation-candidates`: `computation_targets.rs`, `candidates/`) | Every Pass 1 way to compute the group's measures: exact, exact accumulator, each summary algorithm with one build per configuration of its predefined list (`parameter_list`), and fused computations. A fused candidate lists the groups of the operators it replaces in `fused_groups`; those groups keep their own candidates for their other readers. | | `TumblingWindows` | Window composition: `add_local_window_composition` and `extend_local_window_composition` (`pass2/memo/window_candidates.rs`) | A window summary computed from tumbling windows, at each tumbling-window width the reader's evaluation grid allows. The tumbling-window chain stays private to the candidate. | | `WidenedScans` | Scan widening: `add_scan_label_candidates` (`pass2/memo/rules/scan_labels.rs`) | A reader of a metric's scans widened to a shared label set, read through a `Project`. | | `SummaryInput` | `factor_summary_inputs` (`pass2/memo/rules/summary_inputs.rs`) | Canonical value preprocessing feeding a summary build. | @@ -330,8 +330,8 @@ instead of whole candidates: | Stage | Over the memo | |---|---| -| 0 | Hash-conses the frontends' roots into groups (`DagOfLogicalMemoGroups`). | -| 1, Pass 1 | Emits the candidates for each memo group: exact, exact accumulator, each summary family and size, fused computations. | +| 0 | Hash-conses the frontends' roots into groups: a `Memo` without candidates (`memo_of_queries`). | +| 1, Pass 1 | Emits the candidates for each memo group: exact, exact accumulator, each summary family with one build per configuration of its `parameter_list`, fused computations. | | 1, Pass 2 | Each rule adds candidates to groups. Identical expression is group identity (nothing to add). Summary capability: a reader reading a concrete summary-state group shared with other groups, one group per shared size. Window composition: tumbling windows, and the newest tumbling windows of a shared chain, one concrete group per chain layout (grid, longest window, size). Rollup and exact top-k reuse: a candidate that reads another group (a finer grouping, a ranking). Scan widening: a reader of a metric's scans widened to a shared label set. | | 2 | Chooses each candidate's materialization, once for a group however many parents read it. A scan read through one window is built once; one read through different windows may also be read per reader. | | 3 | Chooses one candidate per needed group, and costs each candidate's own nodes, per node, given its readers; plan-level charges are added once per plan. A source's retained raw data is a concrete group `raw window(S, H)`, one per distinct lookback `H` of the source's query-time readers (a window plus any offset); its storage of `H` of raw data is charged once when it is chosen (planned). | @@ -364,28 +364,36 @@ operands. A unique key is not needed (the PromQL planning path happens to give this output one, series identity and timestamp); an unordered `LIMIT` would stay one group per reader. -**Step 2, Stage 1 Pass 1.** `try_populate_pass1` gives G2 and G4 seven -candidates each. G0, G1, G3 and G5 get one each, their own node. G6 gets -one: `avg` computed from exact sum and count accumulators. The memo now has -19 candidates. +**Step 2, Stage 1 Pass 1.** `pass1_memo` adds 12 groups, 19 in all, with +36 candidates. Every group of step 1 keeps its own expression as its exact +candidate. Each summary state is a group with one build per configuration of +its algorithm's `parameter_list`, and each readout is a group over it: -| Candidate of G2 or G4 | `accuracy_budget_parts` | -|---|---| -| Exact | 1 | -| KLL, `k` 345 (`failure_probability` 0.001) | 1 | -| KLL, `k` 746 (`failure_probability` 0.0005) | 2 | -| DDSketch, `alpha` 0.01 | 1 | -| DDSketch, `alpha` 0.004963 | 2 | -| KLL, `k` 567 (`failure_probability` 1e-7) | 1 | -| KLL, `k` 1184 (`failure_probability` 5e-8) | 2 | - -The query has two approximate inputs (G2 and G4), so each summary comes -sized for the whole accuracy budget and for a half of it. Pass 1 offers each -KLL at two scopes: per value (the first two KLL candidates) and for the -whole result (the last two), where the per-value `failure_probability` is the -target's 0.001 divided over the source's 10,000 series. The memo stands for 7 × 7 = 49 candidate DAGs, all different: -- 16 = 4 × 4 use only `accuracy_budget_parts` 1. -- 33 size at least one operand's summary for half of the budget. +| Group | Logical sub-expression | Reads | Candidates | +|---|---|---|---| +| G7 | KLL state, per series (`SummaryAgg`) | G1 | 7 builds: `k` 26, 52, 132, 269, 547, 1404, 2863 | +| G8, G11 | KLL readouts `quantile 0.5` and `quantile 0.9` (`SummaryEstimate`) | G7 | 1 each | +| G9 | DDSketch state, per series (`SummaryAgg`) | G1 | 7 builds: `alpha` 0.1, 0.05, 0.02, 0.01, 0.005, 0.002, 0.001 | +| G10, G12 | DDSketch readouts `quantile 0.5` and `quantile 0.9` | G9 | 1 each | +| G13, G14 | exact `sum` and `count` accumulator states by `job` (`SummaryAgg`) | G5 | 1 each | +| G15, G16 | their readouts (`FinalizeExactAccumulator`) | G13, G14 | 1 each | +| G17 | G16's count cast to `Float64` (`Project`) | G16 | 1 | +| G18 | `G15 / G17` | G15, G17 | 1 | + +G2 and G4 get 3 candidates each: exact, and a `Project` renaming the KLL or +the DDSketch readout (G8 or G10, G11 or G12) to the group's columns. G6 gets +2: exact, and a `Project` over G18, `avg` computed from exact `sum` and +`count` accumulators. G0, G1, G3 and G5 keep their one. Pass 1 reads no +accuracy target: each build's error follows from its parameters, and Pass 2 +gives each readout its required accuracy. Both quantiles read one KLL state +group and one DDSketch state group, so a candidate DAG builds each family +at most once. Choosing one candidate per group a DAG reaches, the memo +stands for 282 = 2 × (1 + 2 × 7 + 2 × 7 + 7 + 7 + 2 × 7 × 7) candidate +DAGs: G6 exact or from accumulators, times G2 and G4 both exact, one exact +and the other from KLL or DDSketch, both from one family, or one from each. + +Steps 3 and 4, and their rows in the table after step 4, predate this Pass 1 +sizing; their counts are not recomputed here. **Step 3, Stage 1 Pass 2: window composition.** The groups stay the same 7. G2 and G4 get 120 `TumblingWindows` candidates each (6 summary candidates × 20 tumbling window @@ -402,10 +410,9 @@ all; the memo has 259 candidates. accumulators; and 2 `FinalizeExactAccumulator` groups (G6's sum and count readouts). - 1738 candidates. G2 and G4 have 691 each: 10 `Pass1` (the 7 above and - 3 copies of the `accuracy_budget_parts` 1 KLL `k` 567 that the state-configuration - rule rewrote to the shared configurations with `k` 567, 1156 and 1184; each - keeps `accuracy_budget_parts` 1, and the `k` 1184 one composes the same DAG as the - `accuracy_budget_parts` 2 KLL), + 3 copies of the KLL `k` 567 that the state-configuration + rule rewrote to the shared configurations with `k` 567, 1156 and 1184; the + `k` 1184 one composes the same DAG as the KLL `k` 1184), 336 `TumblingWindows` and 345 `SharedBuild`. G6 has 3: `Pass1`, `SummaryResult` and `SharedBuild`. - Enumeration stops at the former `stage_pipeline`'s default limit of 1,000 candidate @@ -414,17 +421,17 @@ all; the memo has 259 candidates. | After | Groups | Candidates for memo groups | Candidate DAGs | |---|---|---|---| | Stage 0 | 7 | – (each group is its own node) | 1 | -| Stage 1, Pass 1 | 7 | 19 | 49 = 16 whole-budget + 33 budget-share variants | +| Stage 1, Pass 1 | 19 | 36 | 282 | | Stage 1, Pass 2 window composition | 7 | 259 | over 1,000 (enumeration stopped at its limit) | | Stage 1, Pass 2 rules and concrete summary-state groups | 354 | 1738 | over 1,000 (enumeration stopped at its limit) | These numbers are the production planner's, read from the stage-pipeline document `tools/dag-viewer/examples/memo-ratio-of-quantiles.json` (made by the former `stage_pipeline` from `tools/dag-viewer/memo-examples/promql/ratio-of-quantiles-5m.json`, -with accuracy guarantees enforced and the `aws-fargate-us-east-1` cost model). -`crates/integration-tests/tests/memo_enumeration.rs` lowers the query as -production does (with the series-identity column) and reads the memo from the -production run. It asserts the Stage 0 and Pass 1 numbers above. The last +with accuracy guarantees enforced and the `aws-fargate-us-east-1` cost model). The Stage 1, Pass 1 row is +`memo_of_queries` then `pass1_memo` run on that workload with the +executor's summary families, at the current Pass 1 sizing. No test asserts +these numbers. The last step is Pass 2's memo over the complete tumbling-window-width domain, which gives 438 groups and 2158 candidates. @@ -473,18 +480,16 @@ that vector. | Group needed only under some choices | A group joins the choice only when a chosen candidate reads it. | A `SummaryTumblingWindowChain` group is needed only when a `SharedBuild` candidate reading it is chosen; a choice of `Pass1` candidates needs none of the 347 added groups. | | Fused candidate | The groups a fused candidate implements are computed inside it and never become pending. | None (the example has no fused computation). | -In Pass 1 of the example the count happens to be a product, 7 × 7, -because only G2 and G4 have more than one candidate and both read only G1. +In Pass 1 of the example the count is not a product either: G2 and G4 +read the KLL state group G7 and the DDSketch state group G9 through their +readouts, so a choice that reads one family for both picks its build once +(step 2). **Correctness.** Every recorded choice composes unless the memo has a -construction bug (`ChildNotInCandidate`). For Pass 1 of the example -each of the 49 choices composes a different DAG. The whole-budget -choices and the whole-workload plans are not the same set: 9 of the 27 -whole-workload plans are memo DAGs (those that give both `quantile 0.5` the -same choice, since the memo has one group for them), and 7 of the 16 -whole-budget choices take the KLL sized for the whole result, which the -whole-workload inventory does not offer. `memo_enumeration.rs` checks this -(also on a three-query workload). `enumerate` counts +construction bug (`ChildNotInCandidate`). For Pass 1 of the example, +`memo_enumeration.rs` checked that each choice composes a different DAG +(also on a three-query workload); that check predates the current Pass 1 +sizing. `enumerate` counts choices, not DAGs: two candidates of a group that differ only in what recomposing re-derives compose equal DAGs. It does not check validity: input contracts, accuracy at the query roots, Stage 2 legality and Stage 3 @@ -521,12 +526,12 @@ candidates is in `crates/stage3-plan-selection/src/` (`lib.rs`, `groups/`, `milp | Step | Entry point | Path | |---|---|---| -| Stage 0 | `memo_of_queries` → `DagOfLogicalMemoGroups`, `MemoGroup`, `MemoGroupId` | `stage0.rs` (the types: `asap_types::stages`); hash-consing is `share_common_sub_dags` in `stage0/cse.rs` | -| Pass 1 | `pass1_memo` → `PerComputationLogicalMemoCandidates` (its `Memo` and its `PrunedCandidate`s; `ComputationTarget` is Pass 1's working type, in `asap_types::stages`), the one entry: inside it, the computation targets (walking the memo groups), the summaries the deployment does not support and those no query can use pruned, the candidates attached to the groups (`try_populate_pass1`), then the accuracy-scoped sizes | `stage1-pass1-per-computation-candidates/src/lib.rs`; `computation_targets.rs`; `pass1/memo_population.rs` | -| Memo types | `DagOfLogicalMemoGroups`, `PerComputationLogicalMemoCandidates`, `HowToComputeAggregateMeasure`, Pass 1's working types (`ComputationTarget`, `FusedComputation`, `HavingEntry`, `HavingPlacement`), `Memo`, `CandidateForMemoGroup`, `OriginOfCandidateForMemoGroup`, `LogicalASAPMemoCandidates`, `CandidateGenerationTimeout`, `root_groups`, `queries_rooted_at` | `crates/types/src/stages/` (`asap_types::stages`) | +| 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.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) | +| 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. window composition for every legal tumbling-window width (`add_local_window_composition`); 2–9. the rules in `pass2/memo/rules/`: scan widening, summary inputs, top-k reuse, finer aggregate, rollup, window rollup, summary results, state configurations; 10. `add_shared_summary_state_groups`, the shared builds | `stage1-pass2-reuse-candidates/src/lib.rs` (`LogicalASAPMemoCandidates` itself: `asap_types::stages`); `pass2/memo/window_candidates.rs`, `pass2/memo/rules/`, `pass2/memo/state_groups.rs`, `pass2/memo/shared_configurations.rs` | | Memo to candidate DAGs | `enumerate`, `build_logical_asap_dags_from_chosen_candidates`, `ChosenCandidatePerMemoGroup`, `AllChosenCandidatesPerMemoGroup`, `ErrorBuildingLogicalASAPDagsFromChosenCandidates` | `pass2/memo/enumeration.rs` (re-exported at the crate root) | -| Production memo build and search | The facade's `run_planning` builds the DAG of logical memo groups and runs Pass 1 (`pass1_memo`) once; then `generate_logical_asap_memo_candidates`, `generate_physical_asap_memo_candidates` and Stage 3's `select_plan`, once each; `select_plan` builds the plan. Behind `select_plan`: the group selection MILP (#1095), `groups/` and `milp/` | `crates/planner/src/run.rs`; `crates/stage3-plan-selection/src/lib.rs` | +| 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 group selection MILP (#1095), `groups/` and `milp/` | `crates/planner/src/run.rs`; `crates/stage3-plan-selection/src/lib.rs` | ## ASAPPlanner Detailed Design: Planning Stages and their decisions/Strategies @@ -563,7 +568,7 @@ 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 | what the measure or the deployment cannot compute: `RequiresExact`, `NullableAvgInput`, `NoRelationalCountSketchRealization`, `UnsupportedByDeployment`, `QuantileOutsideUnitInterval`, `TopKHeapOverOneRowPerItem`; and, only when the deployment's accuracy model and evidence cannot accept an output without its guarantee, a summary no query reading it can use: `NoErrorBoundForQueryTarget` | `PerComputationLogicalMemoCandidates::pruned_candidates`, each on its aggregate's memo group | the way to compute the measure (`HowToComputeAggregateMeasure`) | +| 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 2 | nothing: it only adds candidates | — | — | | 2 | what cannot be built or materialized: `NoIngestionPipeline`, `RawDataNotRetained` (a query-time scan of raw data the deployment does not keep), `QueryTimeResultsNotRetained`, `InputHasNoBuildableProducer`, `ReachesNoQueryOutput`; the planner does not check executor support | `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, cluster capacity) | its own `RejectionCause` | — | @@ -574,10 +579,8 @@ candidates are renumbered after pruning and a pruned one has no timing and lifetime, and makes no copies of it, so (`operator_node`, `properties`) is unique. Operator nodes are kept whole, so `operator_node` indexes the output's -`operator_nodes_of_candidates_for_memo_groups`. Pass 1's accuracy pruning -(`NoErrorBoundForQueryTarget`) runs inside Pass 1's entry, before the -candidates are attached to the memo groups, and records a `PrunedCandidate` -like every other Pass 1 prune. +`operator_nodes_of_candidates_for_memo_groups`. Pass 1 records no pruned +candidate: a way it cannot compute is not offered. `asap_planner` writes both lists as `pruned_candidates` under `stage1_logical_asap_optimization` and `stage2_physical_asap_optimization`, @@ -595,7 +598,7 @@ 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 (`PerComputationCandidates`, now Pass 1's crate-private working form) | Logical roots → `DagOfLogicalMemoGroups` (hash-consed `MemoGroup`s); with the Pass 1 inventory, less the summaries the deployment does not support and those no query reading them can use → `PerComputationLogicalMemoCandidates`: the `Memo` (each group's `CandidateForMemoGroup`s, with the accuracy-scoped sizes) and the pruned candidates (`PrunedCandidate`) | `memo_of_queries`, `pass1_memo` | +| 1, Pass 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 2 | One Pass 1 choice per computation → that choice rewritten by each sharing rule, every subset of sharing choices (no longer in the code) | `Memo`; the entries' recurrence and range steps → the same memo with each rule's candidates added to the groups they implement | the memo rules (`pass2/memo/rules/`), `pass2::memo::window_candidates` | | 1, concrete summary-state groups | (part of Pass 2) | `Memo` → the memo with concrete summary-state groups: one group per shared size or tumbling-window layout that readers can read | `add_shared_summary_state_groups`, Pass 2's last step; the Pass 2 output is `LogicalASAPMemoCandidates` (`generate_logical_asap_memo_candidates`) | | 2 | One whole-workload logical candidate; entries (recurrence, predictability), `DataWorkload`, query-time retention → its physical candidates, one per physical properties assignment | `LogicalASAPMemoCandidates`; entries, `DataWorkload`, query-time and raw-data retention → `PhysicalASAPMemoCandidates`: every operator node of every candidate with each allowed timing and lifetime (one physical candidate each, no copies), the producers of each input, reader constraints (each applied to every selected run of its candidate), and the pruned candidates (`PrunedCandidate`) | `generate_physical_asap_memo_candidates` (`asap_stage2_physical_optimization`) | @@ -832,22 +835,19 @@ Output: Out — candidate replacement sub-DAGs for s Every size is decided in Stage 1; Stage 3 only checks the composed accuracy. Algorithm 1 checks whether a family can meet `acc(s)` at all and -yields the family unsized (`HowToComputeAggregateMeasure::Summary`). When -Pass 1 attaches the family to its memo group, it creates one sized candidate -per split of the accuracy budget: `accuracy_budget_parts` from 1 to the most -approximate inputs of a query reaching the group, each sized by the accuracy -model for its share. Pass 2 never resizes a summary for its own readers: a +yields the algorithm unsized (Pass 1's `HowToComputeAggregateMeasure::Summary`). +When Pass 1 adds the algorithm to its memo group, it adds one build per +configuration of the algorithm's predefined list (`parameter_list`); Pass 2 +decides which builds each reader can use. Pass 2 never resizes a summary for its own readers: a tumbling-window chain inherits the size of the build it replaces (a merge of equal-size tumbling windows keeps the guarantee when the family's merged error is `Exact` or `AsIfBuiltOverUnion`), and a build shared by several readers takes the -strictest reader's size, one state group per distinct size. The failure -probability is part of Pass 1's size too -(`pass1_memo`): each approximate input -of a candidate with `n` budget parts is sized for `δ / (n · V)`, the smallest -over the queries reaching its group, where `V` is the number of values the -query's accuracy scope covers (1 per value, at most `⌊1 / share⌋` for a record -share, and `G` from the workload-derived bounds for the whole result), and a -classic HLL's precision is raised for its source's declared distinct bound. +strictest reader's size, one state group per distinct size. Pass 1 +(`pass1_memo`) reads no accuracy target, so no failure probability sizes its +builds: each build's error follows from its configuration, and Pass 2 gives +each readout its required accuracy, turning a whole-result failure +probability into a per-value one with the number of values one evaluation +returns. Stage 3 never resizes: a candidate whose sizes miss the composed accuracy target is rejected. Pass 1 creates no merge nodes: each candidate summarizes exactly its own diff --git a/docs/develop_docs/asap-aware-mapping-architecture.md b/docs/develop_docs/asap-aware-mapping-architecture.md index 44656b0bb..340e25183 100644 --- a/docs/develop_docs/asap-aware-mapping-architecture.md +++ b/docs/develop_docs/asap-aware-mapping-architecture.md @@ -46,10 +46,10 @@ asap-types ◄── asap-executor (Stage 4; no stage crate depends on it) ```text QueryRoots (Stage 0) - │ asap_stage0_memo::memo_of_queries → DagOfLogicalMemoGroups, then + │ asap_stage0_memo::memo_of_queries → Memo (groups, no candidates), then │ asap_stage1_pass1_per_computation_candidates::pass1_memo ▼ Stage 1, Pass 1 -PerComputationLogicalMemoCandidates (Memo + pruned_candidates) +Memo (each group's initial candidates) │ asap_stage1_pass2_reuse_candidates::generate_logical_asap_memo_candidates │ the memo rules (memo/rules/) over the candidate memo Stage 1, Pass 2 ▼ @@ -70,7 +70,7 @@ same pipeline behind the `OptimizationPass` trait. | Concern | Where it lives | | --- | --- | -| Pass 1: which computations a query has (`ComputationTarget`), how each can be computed (`HowToComputeAggregateMeasure`: `Exact`, `ExactAccumulator`, `Summary`), fused computations (`FusedComputation`), pruning (`PruneReason`) | `asap-stage1-pass1-per-computation-candidates`, `computation_targets.rs` | +| Pass 1: which computations a query has (`ComputationTarget`), how each can be computed (`HowToComputeAggregateMeasure`: `Exact`, `ExactAccumulator`, `Summary`), fused computations (`FusedComputation`); the candidates that compute them | `asap-stage1-pass1-per-computation-candidates`, `computation_targets.rs`, `candidates/` | | Which summary families serve an intent (`summary_candidates`) | `asap-stage1-pass1-per-computation-candidates`, `summary_realization.rs` | | Pass 2 steps: rollup from the finest common group (shared producers across group keys), top-k reuse, readout requirements, dead-candidate elimination, chain groups (tumbling windows) and the logical edges | `asap-stage1-pass2-reuse-candidates`, `lib.rs` (the steps in order) and `rules/` (`rollup.rs`, `topk.rs`, `chains.rs`) | | Enumeration of the plans a memo stands for (reference pricer, DAG viewer) | none today (deleted in #1207 PR 0) | @@ -122,12 +122,12 @@ No stage caps the candidates it plans, and neither does `asap_planner`. asap-stage0-memo -p asap-stage1-pass1-per-computation-candidates -p asap-stage1-pass2-reuse-candidates -p asap-stage2-physical-optimization -p asap-stage3-plan-selection -E 'test()'`). -- `crates/stage1-pass1-per-computation-candidates/src/per_computation_candidates_tests.rs` covers +- `crates/stage1-pass1-per-computation-candidates/src/tests.rs` covers Pass 1. - `crates/integration-tests/tests/planner_layering_example{1,2,3,4}.rs` pin the design document's examples through every stage; `reuse_rules.rs`, `deployment_capabilities.rs`, `physical_properties_e2e.rs` - and `stage1_logical_asap_optimization.rs` cover single rules end to end. + 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 `--run-until` and the refused flags. diff --git a/docs/develop_docs/asap-aware-mapping-contracts.md b/docs/develop_docs/asap-aware-mapping-contracts.md index 8ee345045..8bbd9da5c 100644 --- a/docs/develop_docs/asap-aware-mapping-contracts.md +++ b/docs/develop_docs/asap-aware-mapping-contracts.md @@ -39,19 +39,17 @@ asap-stage1-pass2-reuse-candidates -p asap-stage2-physical-optimization -p asap- has a mergeable exact state, else `Exact`), then each `Summary(family)` from `summary_realization::summary_candidates`. Candidates are unranked: Pass 1 never compares cost. -- **Pruning.** A candidate that cannot meet the target is moved to the - inventory's `pruned_ways_to_compute` (with its target) with a `PruneReason` (`RequiresExact`, - `NullableAvgInput`, `UnsupportedByDeployment`, - `QuantileOutsideUnitInterval`); it is never silently - dropped. Pass 1 prunes only what it can prove; accuracy that depends on - data facts is left to Stage 3. -- **Fused computations.** `FusedComputation { absorbed_targets, ways_to_compute }` - replaces the targets beneath (the whole-expression top-k, the nested sum). - It absorbs the target directly beneath and, for a heap over the raw data samples - beneath a grouped sum of per-series sums or counts, the per-series target - too. A whole-workload choice keeps one digit per target; a fused pick with - a non-first digit on an absorbed target is skipped, so each plan is - enumerated once. +- **Ways not offered.** A way the measure or the deployment cannot compute + (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) is + not offered, and Pass 1 records none. Accuracy is Pass 2's. +- **Fused computations.** `FusedComputation { absorbed_groups, ways_to_compute }` + replaces the operators beneath (the whole-expression top-k, the nested + sum, min or max) in one appearance; its builds list `absorbed_groups` in + `fused_groups`. It absorbs the aggregate beneath and, for a heap over the + raw data samples beneath a grouped sum of per-series sums or counts, the + per-series aggregate too. - **Pass 2.** Each rule adds candidates; none removes a Pass 1 candidate, adds a summary family, or adds a readout. So a deployment that does not support a family never sees it again after Pass 1. diff --git a/docs/develop_docs/extend-asap-aware-mapping.md b/docs/develop_docs/extend-asap-aware-mapping.md index 9072b3536..2cb7da985 100644 --- a/docs/develop_docs/extend-asap-aware-mapping.md +++ b/docs/develop_docs/extend-asap-aware-mapping.md @@ -24,10 +24,10 @@ A new sketch that Pass 1 can offer for an intent. evaluates is its own declaration, `EVALUATED_READOUTS` (`crates/executor/src/capability.rs`); add the family's readouts there once the executor answers them. -3. **Offer and size.** Place it in `summary_realization::FAMILY_PREFERENCE` +3. **Offer and size.** Place it in `summary_realization::ALGORITHM_PREFERENCE` (`crates/stage1-pass1-per-computation-candidates`): `summary_candidates` offers it, in that order, for every intent whose statistic its capability row answers. - Size it in `asap_accuracy::sizing::default_size_params`. + To size it, add its list in `crates/types/src/summary_type/parameter_lists.rs` (`parameter_list`). 4. **Accuracy.** Add its error model under `crates/accuracy/src/guarantee/` and return it from `theoretical_guarantee`, evaluated at the required failure @@ -44,9 +44,9 @@ A new sketch that Pass 1 can offer for an intent. not with a local copy. 7. **Labels.** Name it in `asap_devtools::candidate_labels`. -Tests: a Pass 1 test in `crates/stage1-pass1-per-computation-candidates/src/per_computation_candidates_tests.rs` +Tests: a Pass 1 test in `crates/stage1-pass1-per-computation-candidates/src/tests.rs` that the intent gets the new candidate (and that a deployment without it -prunes it with `UnsupportedByDeployment`); an estimator test beside the +is not offered it); an estimator test beside the estimator; an execution test in `crates/integration-tests/tests/` such as `frequency_execution.rs` or `kll_tumbling_window_execution.rs`. diff --git a/docs/develop_docs/pre-asap-ir.md b/docs/develop_docs/pre-asap-ir.md index 1eecb5935..070c018ce 100644 --- a/docs/develop_docs/pre-asap-ir.md +++ b/docs/develop_docs/pre-asap-ir.md @@ -148,7 +148,7 @@ yet — and calls `asap_frontend_common::resolve_root`, which does three things The result is `Rc`. `lower_sql` / `lower_sql_dialect` and `lower_metricsql` return it; `lower_promql_query_workload` returns a `QueryRoot` per query. -Workload search then runs structural CSE (`share_common_sub_dags` (crate-private in `asap_stage0_memo`, `cse.rs`)) once +Workload search then runs structural CSE (Stage 0's `memo_of_queries` in `crates/stage0-memo/src/lib.rs`, hash-consing each operator into a `Memo` group through `Memo::find_or_add_group` and `crates/types/src/stages/logical/memo/hash_consing.rs`) once across every root: bottom-up hash-consing where the structural hash is only a filter and the typed `PartialEq` decides sharing, following scalar references like any other input, and gated by `NonASAPOp::is_shareable_when_equal` for non-ASAP producers. diff --git a/docs/develop_docs/target-candidate-api-migration.md b/docs/develop_docs/target-candidate-api-migration.md index 04d38d6c9..1f6564ca2 100644 --- a/docs/develop_docs/target-candidate-api-migration.md +++ b/docs/develop_docs/target-candidate-api-migration.md @@ -49,7 +49,7 @@ or `Operator::ASAP(ASAPOp)`. Old public names are not kept as aliases. | `SummaryFamilyType` | `FieldDataType` (its non-`Plain` variants) | | Timing stored on post-ASAP nodes | `OperatorNode::timing`, `None` until `ir::timing::apply_physical_properties` writes it from a `PhysicalPropertiesAssignment` (default: all query time) | | `UnresolvedQueryExpr` + `asap_types::pre_asap::resolve_root` | `UnresolvedOp` / `UnresolvedScalar` + `asap_frontend_common::resolve_root` | -| `pre_asap::canonicalize`, `pre_asap::cse::share_common_sub_dags` | `asap_frontend_common` `canonicalize` (crate-private), `share_common_sub_dags` (crate-private in `asap_stage0_memo`, `cse.rs`) | +| `pre_asap::canonicalize`, `pre_asap::cse::share_common_sub_dags` | `asap_frontend_common` `canonicalize` (crate-private), `memo_of_queries` (`asap_stage0_memo`, `crates/stage0-memo/src/lib.rs`), hash-consing through `Memo::find_or_add_group` (`crates/types/src/stages/logical/memo/hash_consing.rs`) | | `asap_types::post_asap::compile_post_asap_dag` (wire version 5, `Fallback`/`Binary`/`Value` payloads) | `asap_types::plan::physical_asap_dag::compile_physical_asap_dag` (`PhysicalASAPDAG`, carried in the plan file versioned by `asap_planner::INSTALLABLE_PLAN_WIRE_VERSION`: one node per operator, `Operator` payloads, `ScalarRef` edges); input must be timed | | Exported schema JSON `columns` | `fields` |