diff --git a/crates/accuracy/src/error_contract/mod.rs b/crates/accuracy/src/error_contract/mod.rs index 304dd7814..97b16bf63 100644 --- a/crates/accuracy/src/error_contract/mod.rs +++ b/crates/accuracy/src/error_contract/mod.rs @@ -2,7 +2,7 @@ //! output error from its inputs' errors (concepts doc, section 4). use asap_types::accuracy::AccuracyMetric; -use asap_types::ir::operator::arguments::BinaryOpKind; +use asap_types::ir::operator::arguments::{BinaryOpKind, PromQLVectorSetOpKind}; use asap_types::ir::operator::{AggIntent, Reduction}; use asap_types::ir::scalar::expr_ir::ArithmeticOpKind; use asap_types::ir::scalar::{resolve_column_ref, ColumnRef, ScalarValue}; @@ -20,12 +20,18 @@ use asap_types::summary_type::{ExactKind, SummaryInputExpr}; /// (concepts doc, section 4, "Local propagation"): /// - value-preserving (`Sort`, `TimeRange`, `TimeShift`, `Concat`, a /// readout, a finalize, a `SummaryMerge`): $\beta = 1$ in any metric; +/// - PromQL `and`, `unless` and `or`, which copy values and choose series +/// by labels only, and `label_replace` / `label_join` of labels +/// ([`set_operator_error_factors`], [`reads_an_estimate`]): $\beta = 1$ +/// on each input whose values are copied, 0 on `and`'s and `unless`'s +/// right input, in any metric; /// - a `Project` whose items reading an estimate ([`reads_an_estimate`]) /// each keep its error ([`keeps_error`]): $\beta = 1$, in any metric for /// a copied column, in absolute error for `abs`, `clamp`, `clamp_min`, /// `clamp_max` (also as the PromQL frontend's `promql_` functions) and a -/// negation, in relative error for a product with or quotient by a -/// nonzero literal (`q * 2`, `q / 1000`); +/// negation, in relative error for `abs` and a negation +/// ([`negation_or_abs`]) and a product with or quotient by a nonzero +/// literal (`q * 2`, `q / 1000`); /// - a `Filter` whose predicate reads only columns copied from a source /// (lineage `SourceColumn`, labels and keys): $\beta = 1$ in any metric; /// - an `Aggregate` (or exact accumulator build) of counts ($\beta = 0$), @@ -69,6 +75,13 @@ pub(crate) fn error_contract( .filter(|item| reads_an_estimate(memo, *child, &item.expr)) .all(|item| keeps_error(&item.expr, metric)) .then(|| uniform(1.0)), + // `label_replace(v, "x", "$1", "job", "(.*)")` writes label `x` + // from label `job` and copies every value: a value's error is + // unchanged in any metric, while the label it writes reads no + // estimate. + NonASAPOp::PromqlRelabel { value, child, .. } => { + (!reads_an_estimate(memo, *child, value)).then(|| uniform(1.0)) + } NonASAPOp::Filter { pred, child } => (pred.0.operator_refs().is_empty() && copied_from_a_source(memo, *child, pred.0.columns_referenced())) .then(|| uniform(1.0)), @@ -110,6 +123,17 @@ pub(crate) fn error_contract( } Some(uniform(factor)) } + NonASAPOp::BinaryOp { + operator: + BinaryOperator { + kind: BinaryOpKind::Set(kind), + .. + }, + .. + } => Some(ErrorContract { + error_factor_per_input: set_operator_error_factors(kind).to_vec(), + linear_bound_holds_up_to_per_input: vec![None; 2], + }), NonASAPOp::BinaryOp { operator: BinaryOperator { @@ -252,8 +276,9 @@ fn reads_an_estimate(memo: &Memo, child: MemoGroupId, expr: &ScalarExpr(expr: &ScalarExpr, metric: AccuracyMetric) -> bool { match expr { ScalarExpr::Column(_) | ScalarExpr::Literal(_) => true, @@ -261,7 +286,9 @@ fn keeps_error(expr: &ScalarExpr, metric: AccuracyMetric) -> bool { matches!(args[..], [ScalarExpr::Column(_)]) } _ if matches!(metric, AccuracyMetric::Absolute { .. }) => one_lipschitz(expr), - _ if metric == AccuracyMetric::Relative => scaled_by_a_constant(expr), + _ if metric == AccuracyMetric::Relative => { + negation_or_abs(expr) || scaled_by_a_constant(expr) + } _ => false, } } @@ -271,19 +298,67 @@ fn keeps_error(expr: &ScalarExpr, metric: AccuracyMetric) -> bool { /// `promql_abs`, …) of a column with literal bounds, or a column's /// negation (1-Lipschitz). fn one_lipschitz(expr: &ScalarExpr) -> bool { + negation_or_abs(expr) + || function_of_a_column_and_literals(expr, &["clamp", "clamp_min", "clamp_max"]) +} + +/// Whether `expr` is a column's negation or `abs` (`promql_abs`). Each +/// moves the value by at most the column's error and keeps its magnitude, +/// so it keeps the error both absolutely and as a share of the value: +/// $|(-\hat{x}) - (-x)| = |\hat{x} - x|$ and +/// $||\hat{x}| - |x|| \le |\hat{x} - x|$ (the reverse triangle +/// inequality), while $|-x| = ||x|| = |x|$. With x = 10 and x̂ = 10.5 (5% +/// off), −x̂ = −10.5 is 5% off −10; with x = −10 and x̂ = −10.5, |x̂| = +/// 10.5 is 5% off 10. +fn negation_or_abs(expr: &ScalarExpr) -> bool { match expr { ScalarExpr::Negative { expr, .. } => matches!(**expr, ScalarExpr::Column(_)), - ScalarExpr::FunctionCall { name, args } => { - let name = name.to_ascii_lowercase(); - matches!( - name.strip_prefix("promql_").unwrap_or(&name), - "abs" | "clamp" | "clamp_min" | "clamp_max" - ) && matches!(args.first(), Some(ScalarExpr::Column(_))) - && args[1..] - .iter() - .all(|arg| matches!(arg, ScalarExpr::Literal(_))) - } - _ => false, + _ => function_of_a_column_and_literals(expr, &["abs"]), + } +} + +/// Whether `expr` calls one of `functions` (or the PromQL frontend's +/// `promql_` function of that name), any case, on a column and then +/// literals only: `promql_clamp(value, 0, 100)`. +fn function_of_a_column_and_literals(expr: &ScalarExpr, functions: &[&str]) -> bool { + let ScalarExpr::FunctionCall { name, args } = expr else { + return false; + }; + const FRONTEND_PREFIX: &str = "promql_"; + let name = match name.split_at_checked(FRONTEND_PREFIX.len()) { + Some((prefix, rest)) if prefix.eq_ignore_ascii_case(FRONTEND_PREFIX) => rest, + _ => name.as_str(), + }; + functions + .iter() + .any(|function| function.eq_ignore_ascii_case(name)) + && matches!(args.first(), Some(ScalarExpr::Column(_))) + && args[1..] + .iter() + .all(|arg| matches!(arg, ScalarExpr::Literal(_))) +} + +/// $\beta$ of a PromQL set operator's left and right inputs. Each output +/// series is an input series, value copied, and which ones are kept +/// depends only on which labels the other side has: `lhs and rhs` and +/// `lhs unless rhs` keep left series, so the output's error is the left's +/// and the right's values are never read, $(1, 0)$; `lhs or rhs` copies +/// each value from one of them, $(1, 1)$. With q̂ = 10.5 for q = 10 on the +/// left, `q unless r` outputs 10.5 or nothing, whatever `r`'s values. +/// +/// This assumes that which series each side has is exact: a row's presence +/// never depends on an estimate, since no operator with a contract drops +/// rows by value (a `Filter` on a computed value, `HAVING`, a ranking, +/// `count_values` and `absent` have none) and a readout emits the series +/// the exact evaluation does. So `q unless r` drops the series of `q` that +/// `r` has whether `r` is read from a sketch or exactly; were +/// `r = quantile_over_time(0.9, m[5m]) > 100` allowed, an estimate of 99 +/// for 101 would drop the series from `r` and wrongly keep it in the +/// output. +fn set_operator_error_factors(kind: &PromQLVectorSetOpKind) -> [f64; 2] { + match kind { + PromQLVectorSetOpKind::And | PromQLVectorSetOpKind::Unless => [1.0, 0.0], + PromQLVectorSetOpKind::Or => [1.0, 1.0], } } diff --git a/crates/accuracy/src/error_contract/tests.rs b/crates/accuracy/src/error_contract/tests.rs index ead745d2b..4bbdca982 100644 --- a/crates/accuracy/src/error_contract/tests.rs +++ b/crates/accuracy/src/error_contract/tests.rs @@ -1,11 +1,13 @@ use super::*; -use asap_types::ir::operator::arguments::Reduction; +use asap_types::ir::operator::arguments::{PromQLVectorSetOpKind, Reduction}; use asap_types::ir::scalar::CompareOpKind; use asap_types::ir::schema::{DataType, PROMQL_SERIES_IDENTITY}; use asap_types::ir::{ExprSemantics, Predicate, ProjectItem}; use asap_types::stages::ValueSign; use asap_types::summary_type::{SketchAlgorithm, SketchStatistic, SummaryUpdate}; -use asap_types::test_support::memo_fixtures::{aggregate, arithmetic, compare, readout, scan}; +use asap_types::test_support::memo_fixtures::{ + aggregate, arithmetic, compare, readout, scan, set_operator, +}; use asap_types::workload::{DataWorkload, SourceFacts}; use std::collections::BTreeMap; @@ -15,8 +17,11 @@ use std::collections::BTreeMap; /// `latency` by `job`, `job = "api"` reads such a column; `value > 0.5` /// compares the computed estimate and has no contract. A `Project` of /// `abs`, `clamp` or a negation of the value changes it by at most its -/// error: β = 1 for absolute errors only; one scaling it by a nonzero -/// constant keeps its relative error: β = 1 for relative errors. Only +/// error: β = 1 for absolute errors. `abs` and a negation also keep its +/// magnitude, so they keep its relative error too (β = 1): q = 10, +/// q̂ = 10.5 gives −q̂ = −10.5, 5% off −10. A clamp does not: it is not +/// judged in relative error. One scaling it by a nonzero constant keeps +/// its relative error: β = 1 for relative errors. Only /// the items reading the estimate are judged, so the series identity /// `promql_drop_metric_name` computes does not count. #[test] @@ -136,7 +141,17 @@ fn key_filters_and_value_preserving_projects_have_unit_contracts() { Some(vec![1.0]), "{expr:?}" ); - assert_eq!(factor(&project, AccuracyMetric::Relative), None, "{expr:?}"); + let keeps_magnitude = match &expr { + ScalarExpr::Negative { .. } => true, + ScalarExpr::FunctionCall { name, .. } => name == "promql_abs", + _ => false, + }; + assert_eq!( + factor(&project, AccuracyMetric::Relative), + keeps_magnitude.then(|| vec![1.0]), + "{expr:?}" + ); + assert_eq!(factor(&project, AccuracyMetric::Rank), None, "{expr:?}"); } // Scaling by a nonzero constant keeps a relative error: `q / 2`, // `q * 2`, `2 * q`; scaling by 0 has no contract. @@ -371,3 +386,88 @@ fn sums_and_averages_carry_relative_error_over_values_of_one_sign() { ); } } + +/// PromQL operators that copy values and only choose which series to +/// keep, or rewrite a label, keep their input's error in every metric: +/// - `lhs and rhs` / `lhs unless rhs` keep or drop each left series by +/// whether a right series has its labels, and copy the kept value: the +/// output's error is the left's (β = 1), and the right's values are not +/// read (β = 0). With q̂ = 10.5 for q = 10 on the left, the output is +/// 10.5 or absent, whatever the right's values; +/// - `lhs or rhs` copies each value from one side: β = 1 on both; +/// - `label_replace(v, "x", "$1", "job", "(.*)")` writes label `x` from +/// label `job` and copies the value: β = 1. A rewrite reading the +/// estimate column itself has no contract. +#[test] +fn set_operators_and_relabels_copy_their_inputs_error() { + let mut memo = Memo::new(&DataWorkload::default()); + let g1 = memo + .find_or_add_group(scan("latency", &[("job", DataType::Utf8)], vec![])) + .unwrap(); + let state = memo + .find_or_add_group(Operator::ASAP(ASAPOp::SummaryAgg { + child: g1, + summary_type: FieldDataType::Sketch(SketchAlgorithm::DDSketch), + input: SummaryUpdate::column(ColumnRef::SampleValue), + reduction: Reduction::by(vec![2]), + filter: None, + })) + .unwrap(); + let readout = memo + .find_or_add_group(readout(SketchStatistic::Quantile { q: 0.9 }, state)) + .unwrap(); + let lineage = &memo.groups()[readout.0 as usize] + .group_properties + .column_lineage; + let column_where = |copied: bool| { + lineage + .iter() + .position(|l| matches!(l, ColumnLineage::SourceColumn(_)) == copied) + .expect("the readout has a label and an estimate") + }; + let (job, estimate) = (column_where(true), column_where(false)); + let relabel = |source_column| { + Operator::NonASAP(NonASAPOp::PromqlRelabel { + dst: "x".into(), + value: ScalarExpr::FunctionCall { + name: "label_replace".into(), + args: vec![ + ScalarExpr::Column(source_column), + ScalarExpr::Literal(ScalarValue::Utf8("(.*)".into())), + ScalarExpr::Literal(ScalarValue::Utf8("$1".into())), + ], + }, + child: readout, + }) + }; + let factors = |consumer: &Operator, metric| { + error_contract(&memo, consumer, metric).map(|contract| contract.error_factor_per_input) + }; + for metric in AccuracyMetric::ALL { + for kind in [PromQLVectorSetOpKind::And, PromQLVectorSetOpKind::Unless] { + assert_eq!( + factors(&set_operator(kind.clone(), readout, readout), metric), + Some(vec![1.0, 0.0]), + "{kind:?}, {metric:?}" + ); + } + assert_eq!( + factors( + &set_operator(PromQLVectorSetOpKind::Or, readout, readout), + metric + ), + Some(vec![1.0, 1.0]), + "or, {metric:?}" + ); + assert_eq!( + factors(&relabel(job), metric), + Some(vec![1.0]), + "relabel from job, {metric:?}" + ); + assert_eq!( + factors(&relabel(estimate), metric), + None, + "relabel from the estimate, {metric:?}" + ); + } +} diff --git a/crates/accuracy/src/metric_rule/tests.rs b/crates/accuracy/src/metric_rule/tests.rs index a4c186fec..1e32b6d10 100644 --- a/crates/accuracy/src/metric_rule/tests.rs +++ b/crates/accuracy/src/metric_rule/tests.rs @@ -292,6 +292,109 @@ fn avg_of_readouts_of_values_of_one_sign_keeps_the_ddsketch_edge() { } } +/// `sum(-quantile_over_time(0.99, m[5m]))` and +/// `sum(abs(quantile_over_time(0.99, m[5m])))` with a relative target, +/// `m` declared non-negative: the negation's values are non-positive and +/// `abs`'s non-negative, so the `sum` reads values of one sign and keeps +/// their relative error; the negation and `abs` keep each value's +/// relative error (q = 10, q̂ = 10.5: −q̂ = −10.5 is 5% off −10). The +/// DDSketch readout's edge into the `Project` holds, as does the +/// `Project`'s edge into the `sum`; the KLL readout's rank error is cut. +#[test] +fn a_sum_of_negated_or_absolute_readouts_keeps_the_ddsketch_edge() { + use asap_types::ir::scalar::{resolve_column_ref, ColumnRef, ProjectItem, ScalarExpr}; + let data = DataWorkload { + sources: BTreeMap::from([( + "m".to_string(), + SourceFacts { + column_signs: BTreeMap::from([("value".to_string(), ValueSign::NonNegative)]), + ..SourceFacts::default() + }, + )]), + ..DataWorkload::default() + }; + let negated = |column| ScalarExpr::Negative { + expr: Box::new(ScalarExpr::Column(column)), + semantics: ExprSemantics::Promql, + }; + let absolute = |column| ScalarExpr::FunctionCall { + name: "promql_abs".into(), + args: vec![ScalarExpr::Column(column)], + }; + for (function, sign) in [ + ( + &negated as &dyn Fn(usize) -> ScalarExpr, + ValueSign::NonPositive, + ), + (&absolute, ValueSign::NonNegative), + ] { + let mut memo = Memo::new(&data); + let p99 = quantile_readouts(&mut memo, 0.99); + let schema = memo.groups()[p99.result.0 as usize] + .group_properties + .schema + .clone(); + let value = resolve_column_ref(&ColumnRef::SampleValue, &schema).unwrap(); + let mapped = group( + &mut memo, + Operator::NonASAP(NonASAPOp::Project { + cols: schema + .fields + .iter() + .enumerate() + .map(|(column, field)| ProjectItem { + alias: Some(field.name.clone()), + expr: if column == value { + function(column) + } else { + ScalarExpr::Column(column) + }, + }) + .collect(), + child: p99.result, + }), + ); + assert_eq!( + memo.groups()[mapped.0 as usize] + .group_properties + .column_signs[value], + sign + ); + let sum = group( + &mut memo, + Operator::NonASAP(NonASAPOp::Aggregate { + child: mapped, + reduction: Reduction::by(vec![]), + measures: vec![AggIntent::Sum { col: None }], + output_names: vec!["sum".into()], + filters: vec![None], + having: None, + }), + ); + let target = AccuracyTarget::max_error(0.05).accuracy_metric(AccuracyMetric::Relative); + query(&mut memo, sum, Some(target)); + let into_sum = edge(&memo, own_candidate(mapped), own_candidate(sum), 0); + assert!(into_sum.is_ok(), "{sign:?}: {into_sum:?}"); + for readout in &p99.by_algorithm { + let result = readout_edge(&memo, readout, own_candidate(mapped), 0); + match readout.algorithm { + SketchAlgorithm::DDSketch => assert!(result.is_ok(), "{sign:?}: {result:?}"), + _ => assert!( + matches!( + result, + Err(RootPruneReason::MetricRule { + producer_metric: AccuracyMetric::Rank, + .. + }) + ), + "{sign:?}: {:?} {result:?}", + readout.algorithm + ), + } + } + } +} + /// A scalar root's operands are roots: `scalar(v)` returns the value /// it reads, so `scalar(quantile_over_time(0.99, m[5m]))` at a relative /// target allows relative error at the quantile group, and the DDSketch diff --git a/crates/accuracy/src/readout_caps/mod.rs b/crates/accuracy/src/readout_caps/mod.rs index be3925b49..d4bb4c854 100644 --- a/crates/accuracy/src/readout_caps/mod.rs +++ b/crates/accuracy/src/readout_caps/mod.rs @@ -6,7 +6,8 @@ use std::collections::{BTreeMap, BTreeSet, HashMap}; use asap_types::accuracy::{AccuracyMetric, AccuracyTarget}; -use asap_types::ir::Operator; +use asap_types::ir::operator::arguments::BinaryOpKind; +use asap_types::ir::{BinaryOperator, NonASAPOp, Operator}; use asap_types::stages::{CandidateForMemoGroupId, Memo, MemoGroupId, RequiredAccuracy}; use crate::metric_rule::{query_roots_with_target, ErrorContractPerMetric}; @@ -48,7 +49,7 @@ pub struct ReadoutRequiredAccuracy { pub levels: Vec, /// The queries, by index, whose target sets a failure probability /// without a per-value one at the readout (the values it covers or the - /// readout group's values per evaluation unknown). + /// values per evaluation of a readout group below it unknown). pub queries_without_per_value_failure_probability: Vec, } @@ -58,12 +59,15 @@ pub struct ReadoutRequiredAccuracy { /// memo's topological order (`Memo::topological_order`). /// - A query whose path reads one readout group gives one level: its target /// divided by the path's factor, the readout group's cap, at the target's -/// failure probability per readout value ([`query_levels`]). -/// - A composed query (several readout groups, such as a ratio) gives every -/// level of the grid [`MAX_ERROR_LEVELS`] × [`failure_probability_levels`] -/// not looser than the cap and the per-value failure probability (the cap -/// itself when no error level is), one δ level of 1 when the target sets -/// no failure probability. +/// failure probability per readout value ([`query_levels`]: split over +/// every readout value the query's output can depend on). +/// - A composed query (several readouts whose errors reach its output, +/// β > 0, such as a ratio; `q and r` and `q or r` combine none: +/// [`readouts_read_by_queries`]) gives every level of the grid +/// [`MAX_ERROR_LEVELS`] × [`failure_probability_levels`] not looser than +/// the cap and the per-value failure probability (the cap itself when no +/// error level is), one δ level of 1 when the target sets no failure +/// probability. /// - A readout group reached by several queries gets the union of their /// levels, in query order; one no query with a target reaches in the /// readout's metric gets none. Readouts of one group in one metric get @@ -100,7 +104,8 @@ pub fn readout_levels( } let readout_groups: BTreeSet = readouts.iter().map(|(readout, _)| readout.group).collect(); - let composed = composed_queries(memo, order, &readout_groups); + let readouts_read = + readouts_read_by_queries(memo, &error_metrics.error_contract, order, &readout_groups); let mut levels_of_group: HashMap<(MemoGroupId, AccuracyMetric), ReadoutRequiredAccuracy> = HashMap::new(); readouts @@ -109,7 +114,7 @@ pub fn readout_levels( let group = readout.group; let levels = levels_of_group .entry((group, metric)) - .or_insert_with(|| group_levels(memo, &caps, &composed, group, metric)) + .or_insert_with(|| group_levels(memo, &caps, &readouts_read, group, metric)) .clone(); (readout, levels) }) @@ -120,11 +125,10 @@ pub fn readout_levels( fn group_levels( memo: &Memo, caps: &Caps, - composed: &BTreeSet, + readouts_read: &ReadoutsReadByQueries, group: MemoGroupId, metric: AccuracyMetric, ) -> ReadoutRequiredAccuracy { - let readout_values = memo.max_values_per_evaluation(group); let mut levels: Vec = Vec::new(); let mut queries_without_per_value_failure_probability = Vec::new(); let group_caps = caps[group.0 as usize] @@ -139,10 +143,10 @@ fn group_levels( let Some(query_levels) = query_levels( target, memo.queries()[query].number_of_values_per_query_evaluation, - readout_values, + readouts_read.readout_values.get(&query).copied().flatten(), metric, cap, - composed.contains(&query), + readouts_read.composed.contains(&query), ) else { queries_without_per_value_failure_probability.push(query); continue; @@ -161,15 +165,23 @@ fn group_levels( /// The requirement levels one query gives a readout in `metric` whose cap /// for it is `cap`; `None` when its target's failure probability has no -/// per-value one. A whole-result δ splits over the values one evaluation -/// returns, $n_q$; a reduction (`max`, `min`, `avg`, `sum`) fails when any -/// readout it reads does, so δ also splits over the readout group's values -/// per evaluation, `readout_values` (`Memo::max_values_per_evaluation`): -/// the per-value failure probability is -/// $\delta / \max(n_q, \text{readout values})$ (`max(quantile_over_time(0.9, -/// m[5m]))` over 1000 series at δ = 0.01: 1e-5; `SELECT count(DISTINCT -/// dst)`, one readout value: 0.01), and needs both known when the target -/// sets a δ. +/// per-value one. The query's result fails when any readout value it can +/// depend on does, so by the union bound δ splits over all of them, +/// `readout_values` ([`ReadoutsReadByQueries::readout_values`], summed over +/// every readout group below the query), and over the values its scope +/// covers, $V$ (`AccuracyScope::max_values_covered`, $n_q$ for a whole +/// result): the per-value failure probability is +/// $\delta / \max(V, \text{readout values})$, and needs both known when the +/// target sets a δ. +/// - `max(quantile_over_time(0.9, m[5m]))` over 1000 series at δ = 0.01 +/// returns one value but reads 1000 readout values: 1e-5. +/// - `max by (job) (q{host="h0"} or q{host="h1"})` with 3 series per side +/// reads 6 readout values: δ / 6, not one side's δ / 3. +/// - A bare `q or r` copies each output value from one readout value, yet +/// a whole result fails when any of them does: δ over the readout values +/// of `q` and `r` together, at least $n_q$. A per-value scope ($V = 1$) +/// also splits over all readout values, which is conservative here. +/// - `SELECT count(DISTINCT dst)` reads one readout value: 0.01. fn query_levels( target: &AccuracyTarget, number_of_values_per_query_evaluation: Option, @@ -282,32 +294,83 @@ pub(crate) fn caps( caps } -/// The queries that combine several readouts: a candidate they reach has -/// two or more inputs below which a readout group lies (a ratio of two -/// quantiles). Readouts of one value by different summary types are -/// alternatives in one group's candidates, not a combination. -fn composed_queries( +/// What each query with a target reads from the readouts below it +/// ([`readouts_read_by_queries`]). +struct ReadoutsReadByQueries { + /// The queries that combine several readouts: a candidate they reach + /// has two or more inputs below which lies a readout whose error + /// reaches its output ($\beta > 0$ in a metric of its error contract, + /// [`caps`] — a readout reaches the input through β > 0 at every step + /// below): a ratio of two quantiles. `q and r` is not composed: its + /// output copies `q`'s values and reads only which series `r` has + /// ($\beta = 0$), so `q`'s readout keeps the single level of its cap. + /// Neither is `q / count(r)`: the count reads no value of `r`. Nor is + /// `q or r`: each output value is copied from `q` or from `r`, so its + /// error is the larger of their errors, not their sum + /// ([`takes_each_value_from_one_input`]), and each readout keeps the + /// single level of its cap. Readouts of one value by different summary + /// types are alternatives in one group's candidates, not a combination. + composed: BTreeSet, + /// Per query, by index: the readout values per evaluation its output + /// can depend on through β > 0, summed over the readout groups below it + /// (`Memo::max_values_per_evaluation` each) and, among alternative + /// candidates of a group, the largest; `None` when one of them is + /// unknown. `max by (job) (q{host="h0"} or q{host="h1"})` with 3 series + /// per side: 6, since `or` reads both sides; `q / count(r)`: `q`'s alone. + /// A readout group reached on two paths (`q or q`) counts twice, which + /// only tightens the split. + readout_values: BTreeMap>, +} + +/// The [`ReadoutsReadByQueries`] of `memo`, in one walk up `order` (the +/// memo's topological order) from the readout groups `readout_groups`. +fn readouts_read_by_queries( memo: &Memo, + error_contract: &[Vec], order: &[MemoGroupId], readout_groups: &BTreeSet, -) -> BTreeSet { - let mut reads_a_readout = vec![false; memo.groups().len()]; +) -> ReadoutsReadByQueries { + // Per group: the readout values its output can depend on (`Some(0)` + // when none, so it carries no readout error; `None` unknown). + let mut readout_values_per_group: Vec> = vec![Some(0); memo.groups().len()]; let mut composed = BTreeSet::new(); for &group in order { let candidates = &memo.groups()[group.0 as usize].candidates; - let inputs_reading = |operator: &Operator| { - operator - .children() - .into_iter() - .filter(|child| reads_a_readout[child.0 as usize]) - .count() - }; - let most_inputs_reading = candidates - .iter() - .map(|candidate| inputs_reading(&candidate.expression.operator)) - .max() - .unwrap_or(0); - if most_inputs_reading > 1 { + let mut most_inputs_reading_with_error = 0; + let mut most_readout_values = Some(0); + for (candidate, contract_per_metric) in + candidates.iter().zip(&error_contract[group.0 as usize]) + { + let operator = &candidate.expression.operator; + let children = operator.children(); + let reads_with_error = |input: &usize| { + readout_values_per_group[children[*input].0 as usize] != Some(0) + && contract_per_metric + .iter() + .flatten() + .any(|contract| contract.error_factor_per_input[*input] > 0.0) + }; + let inputs_reading_with_error = (0..children.len()).filter(reads_with_error).count(); + // Each output value comes from one input, so the output's error + // is one input's, never a sum of several; its values still + // depend on the readouts of every input. + let inputs_combined = if takes_each_value_from_one_input(operator) { + inputs_reading_with_error.min(1) + } else { + inputs_reading_with_error + }; + most_inputs_reading_with_error = most_inputs_reading_with_error.max(inputs_combined); + let readout_values = + (0..children.len()) + .filter(reads_with_error) + .try_fold(0u64, |total, input| { + total.checked_add(readout_values_per_group[children[input].0 as usize]?) + }); + most_readout_values = most_readout_values + .zip(readout_values) + .map(|(most, values)| most.max(values)); + } + if most_inputs_reading_with_error > 1 { composed.extend( memo.groups()[group.0 as usize] .reached_by_queries() @@ -315,10 +378,40 @@ fn composed_queries( .copied(), ); } - reads_a_readout[group.0 as usize] = - readout_groups.contains(&group) || most_inputs_reading > 0; + readout_values_per_group[group.0 as usize] = if readout_groups.contains(&group) { + memo.max_values_per_evaluation(group) + } else { + most_readout_values + }; + } + let mut readout_values: BTreeMap> = BTreeMap::new(); + for (query, root, _, _) in query_roots_with_target(memo) { + let total = readout_values.entry(query).or_insert(Some(0)); + *total = total + .zip(readout_values_per_group[root.0 as usize]) + .and_then(|(total, values)| total.checked_add(values)); + } + ReadoutsReadByQueries { + composed, + readout_values, } - composed +} + +/// Whether `operator` copies each output value from exactly one of its +/// inputs: a PromQL set operator (`q or r` takes a series' value from `q` +/// when `q` has the series, else from `r`; `and` and `unless` only from +/// the left). +fn takes_each_value_from_one_input(operator: &Operator) -> bool { + matches!( + operator, + Operator::NonASAP(NonASAPOp::BinaryOp { + operator: BinaryOperator { + kind: BinaryOpKind::Set(_), + .. + }, + .. + }) + ) } /// Keeps the larger of `cap` and the known cap of `query` in `metric`. diff --git a/crates/accuracy/src/readout_caps/tests.rs b/crates/accuracy/src/readout_caps/tests.rs index cf1acf089..cb19c80e4 100644 --- a/crates/accuracy/src/readout_caps/tests.rs +++ b/crates/accuracy/src/readout_caps/tests.rs @@ -1,5 +1,5 @@ use super::*; -use asap_types::ir::operator::arguments::Reduction; +use asap_types::ir::operator::arguments::{PromQLVectorSetOpKind, Reduction}; use asap_types::ir::operator::AggIntent; use asap_types::ir::scalar::expr_ir::ArithmeticOpKind; use asap_types::ir::QueryRoot; @@ -9,7 +9,7 @@ use asap_types::test_support::memo_builders::{ estimate, group, own_candidate, quantile_over_time, query, scan_group, sketch_state, with_series, }; -use asap_types::test_support::memo_fixtures::{aggregate, arithmetic}; +use asap_types::test_support::memo_fixtures::{aggregate, arithmetic, set_operator}; /// The levels [`readout_levels`] gives the readout candidate `readout`. fn levels_of(memo: &Memo, readout: MemoGroupId) -> Vec { @@ -154,3 +154,153 @@ fn a_readout_of_one_value_keeps_the_whole_failure_probability() { "{required:?}" ); } + +/// `quantile_over_time(0.9, m[5m]) and quantile_over_time(0.5, m[5m])` +/// copies the left values and reads only which series the right has +/// (β = 0), so it combines no errors: the left readout gets the single +/// level of its cap, 0.05 at δ = 0.01 over 100 series (1e-4), not the +/// composed grid, and the right one gets none. +#[test] +fn an_and_combines_no_readout_errors() { + let target = AccuracyTarget::max_error(0.05) + .failure_probability(0.01) + .accuracy_metric(AccuracyMetric::Relative); + let readouts_under = |kind| { + let mut memo = Memo::new(&with_series("m", 100)); + let (_, state, p90) = quantile_over_time(&mut memo, SketchAlgorithm::DDSketch, 0.9, 300); + let p50 = estimate(&mut memo, state, SketchStatistic::Quantile { q: 0.5 }); + let root = group(&mut memo, set_operator(kind, p90, p50)); + memo.add_query(MemoQuery { + root: QueryRoot::Operator(root), + accuracy_target: Some(target.clone()), + number_of_values_per_query_evaluation: Some(100), + }); + (levels_of(&memo, p90), levels_of(&memo, p50)) + }; + let (left, right) = readouts_under(PromQLVectorSetOpKind::And); + let [required] = left[..] else { + panic!("one level for the left readout: {left:?}"); + }; + assert!((required.max_error - 0.05).abs() < 1e-12, "{required:?}"); + assert!( + (required.failure_probability - 1e-4).abs() < 1e-12, + "{required:?}" + ); + assert_eq!(right, vec![]); +} + +/// `quantile_over_time(0.9, m[5m]) or quantile_over_time(0.5, m[5m])` +/// copies each output value from one side, so its error is the larger of +/// the two readouts' errors, not their sum: each readout gets the single +/// level of its cap, 0.05. Its whole result still fails when any of the +/// 200 readout values it can return does, so δ = 0.01 splits over all of +/// them: 5e-5 per value, not 1e-4 over its 100 output values. A ratio of +/// the same readouts combines both errors and keeps the composed grid. +#[test] +fn an_or_takes_each_value_from_one_readout() { + let target = AccuracyTarget::max_error(0.05) + .failure_probability(0.01) + .accuracy_metric(AccuracyMetric::Relative); + let readouts_under = |operator: fn(MemoGroupId, MemoGroupId) -> _| { + let mut memo = Memo::new(&with_series("m", 100)); + let (_, state, p90) = quantile_over_time(&mut memo, SketchAlgorithm::DDSketch, 0.9, 300); + let p50 = estimate(&mut memo, state, SketchStatistic::Quantile { q: 0.5 }); + let root = group(&mut memo, operator(p90, p50)); + memo.add_query(MemoQuery { + root: QueryRoot::Operator(root), + accuracy_target: Some(target.clone()), + number_of_values_per_query_evaluation: Some(100), + }); + [levels_of(&memo, p90), levels_of(&memo, p50)] + }; + for levels in readouts_under(|q, r| set_operator(PromQLVectorSetOpKind::Or, q, r)) { + let [required] = levels[..] else { + panic!("one level for each readout of `or`: {levels:?}"); + }; + assert!((required.max_error - 0.05).abs() < 1e-12, "{required:?}"); + assert!( + (required.failure_probability - 5e-5).abs() < 1e-12, + "{required:?}" + ); + } + for levels in readouts_under(|q, r| arithmetic(ArithmeticOpKind::Div, q, r)) { + assert!( + levels.len() > 1, + "the composed grid for a ratio: {levels:?}" + ); + } +} + +/// A reduction above an `or` reads every readout value of both sides: +/// `max by (job) (quantile_over_time(0.9, m[5m]) or +/// quantile_over_time(0.5, m[5m]))` over 3 series returns 3 values, but +/// fails when any of the 6 readout values below it does, so each readout +/// gets δ = 0.01 / 6, not 0.01 / 3 (one side's values), which would let +/// the union bound reach 2δ. +#[test] +fn a_reduction_above_an_or_splits_the_failure_probability_over_both_sides() { + let mut memo = Memo::new(&with_series("m", 3)); + let (_, state, p90) = quantile_over_time(&mut memo, SketchAlgorithm::DDSketch, 0.9, 300); + let p50 = estimate(&mut memo, state, SketchStatistic::Quantile { q: 0.5 }); + let either = group(&mut memo, set_operator(PromQLVectorSetOpKind::Or, p90, p50)); + let max = group( + &mut memo, + aggregate(Reduction::by(vec![0]), AggIntent::Max { col: None }, either), + ); + memo.add_query(MemoQuery { + root: QueryRoot::Operator(max), + accuracy_target: Some( + AccuracyTarget::max_error(0.05) + .failure_probability(0.01) + .accuracy_metric(AccuracyMetric::Relative), + ), + number_of_values_per_query_evaluation: Some(3), + }); + for readout in [p90, p50] { + let levels = levels_of(&memo, readout); + let [required] = levels[..] else { + panic!("one level for each readout: {levels:?}"); + }; + assert!( + (required.failure_probability - 0.01 / 6.0).abs() < 1e-12, + "{required:?}" + ); + } +} + +/// A count reads which readouts exist, not their values (β = 0), so an +/// operator above it combines no error of them: +/// `quantile_over_time(0.9, m[5m]) / count(quantile_over_time(0.5, m[5m]))` +/// over 100 series at relative error 0.05 and δ = 0.01 reads one +/// readout's error. The p90 readout gets the single level of its cap, +/// 0.05 · (1 − 0.1) = 0.045 (the division's factor 1 / (1 − 0.1)) at +/// 1e-4 per value, not the composed grid. +#[test] +fn an_operator_above_a_count_of_readouts_combines_one_readout_error() { + let mut memo = Memo::new(&with_series("m", 100)); + let (_, state, p90) = quantile_over_time(&mut memo, SketchAlgorithm::DDSketch, 0.9, 300); + let p50 = estimate(&mut memo, state, SketchStatistic::Quantile { q: 0.5 }); + let count = group( + &mut memo, + aggregate(Reduction::by(vec![]), AggIntent::Count, p50), + ); + let ratio = group(&mut memo, arithmetic(ArithmeticOpKind::Div, p90, count)); + memo.add_query(MemoQuery { + root: QueryRoot::Operator(ratio), + accuracy_target: Some( + AccuracyTarget::max_error(0.05) + .failure_probability(0.01) + .accuracy_metric(AccuracyMetric::Relative), + ), + number_of_values_per_query_evaluation: Some(100), + }); + let levels = levels_of(&memo, p90); + let [required] = levels[..] else { + panic!("one level for the p90 readout: {levels:?}"); + }; + assert!((required.max_error - 0.045).abs() < 1e-12, "{required:?}"); + assert!( + (required.failure_probability - 1e-4).abs() < 1e-12, + "{required:?}" + ); +} diff --git a/crates/executor/src/operators/current_series.rs b/crates/executor/src/operators/current_series.rs index d2bb586e0..0340bcca8 100644 --- a/crates/executor/src/operators/current_series.rs +++ b/crates/executor/src/operators/current_series.rs @@ -1,5 +1,6 @@ //! A bounded instant-vector snapshot: select latest before removing stale markers. use super::*; +use crate::values::is_stale_marker; impl Operator { pub fn current_series( @@ -95,7 +96,7 @@ pub(super) fn execute<'a>( .groups_in_key_order() .into_iter() .filter_map(|series| latest[series as usize]) - .filter(|&row| values.value(row as usize).to_bits() != STALE_MARKER) + .filter(|&row| !is_stale_marker(values.value(row as usize))) .collect::>(); let selected = batch.take(&arrow::array::UInt32Array::from(rows))?; let stamped = std::sync::Arc::new(arrow::array::TimestampMillisecondArray::from(vec![ diff --git a/crates/executor/src/operators/mod.rs b/crates/executor/src/operators/mod.rs index 989950635..ad2ef2adf 100644 --- a/crates/executor/src/operators/mod.rs +++ b/crates/executor/src/operators/mod.rs @@ -36,7 +36,6 @@ pub(crate) mod vector_binary; pub(crate) mod vector_window; pub use aggregate::Reduction; pub use series_window::SubquerySteps; -pub(crate) use series_window::STALE_MARKER; pub use sort::SortKey; pub use summary::{RowWeight, SummaryEvaluation}; #[derive(Clone, serde::Serialize, serde::Deserialize)] diff --git a/crates/executor/src/operators/series_window.rs b/crates/executor/src/operators/series_window.rs index b4452438d..b98974d78 100644 --- a/crates/executor/src/operators/series_window.rs +++ b/crates/executor/src/operators/series_window.rs @@ -1,5 +1,6 @@ //! PromQL per-series evaluation over the samples before an evaluation instant. use super::*; +use crate::values::is_stale_marker; use planner_types::ir::operator::{AggIntent, AtModifier}; /// A PromQL subquery grid: every multiple of `step_ms` in @@ -13,9 +14,6 @@ pub struct SubquerySteps { pub at_ms: Option, } -/// The bits of the Prometheus stale marker, a NaN that Remote Write -/// carries when a series ends. It is not a sample. -pub(crate) const STALE_MARKER: u64 = 0x7ff0_0000_0000_0002; const MAX_SUBQUERY_STEPS: i64 = 100_000; impl Operator { @@ -294,13 +292,13 @@ pub(super) fn execute<'a>( let result = match function { None => samples .last() - .filter(|p| p.1.to_bits() != STALE_MARKER) + .filter(|p| !is_stale_marker(p.1)) .map(|p| p.1), Some(intent) => { let fresh = samples .iter() .copied() - .filter(|p| p.1.to_bits() != STALE_MARKER) + .filter(|p| !is_stale_marker(p.1)) .collect::>(); if fresh.is_empty() { None diff --git a/crates/executor/src/operators/time_range.rs b/crates/executor/src/operators/time_range.rs index 68462c232..929cec29e 100644 --- a/crates/executor/src/operators/time_range.rs +++ b/crates/executor/src/operators/time_range.rs @@ -4,6 +4,7 @@ //! end-of-series NaN) are never rows; an ordinary NaN is. And a `TimeShift` //! with an `@` anchor, which evaluates its input at the anchor's time. use super::*; +use crate::values::is_stale_marker; use arrow::array::Array; use planner_types::ir::operator::AtModifier; @@ -207,7 +208,7 @@ pub(super) fn execute<'a>( start < t && t <= end }; let stale = values.is_some_and(|values| { - values.is_valid(row) && values.value(row).to_bits() == STALE_MARKER + values.is_valid(row) && is_stale_marker(values.value(row)) }); Some(in_window && !stale) }) diff --git a/crates/executor/src/physical_planner/mod.rs b/crates/executor/src/physical_planner/mod.rs index bcc74765e..bb319a3cc 100644 --- a/crates/executor/src/physical_planner/mod.rs +++ b/crates/executor/src/physical_planner/mod.rs @@ -480,7 +480,12 @@ fn compile_internal( .ok_or_else(|| invalid("a tumbling-window chain reads a time column"))?; let width_ms = i64::try_from(*tumbling_window_width_ms) .map_err(|_| invalid("tumbling-window width exceeds Int64"))?; - // A time series' stale markers are not samples. + // A time series' stale markers are not samples: the + // `TimeRange` drops them only when the chain reads the + // series' `Scan` (through shifts). Over a `Filter` or a + // `Project` it keeps them, and an exact accumulator then + // rejects a stale marker passed on unchanged by a `Filter` + // or a value-copying `Project` (`factory::not_a_stale_marker`). let below = node_below_shifts(first_input(id, &dependencies), &nodes, &dependencies); let sample_value = match below.map(|below| &nodes[&below].payload) { diff --git a/crates/executor/src/summary_kernels/factory/mod.rs b/crates/executor/src/summary_kernels/factory/mod.rs index 222935169..7ba28af8f 100644 --- a/crates/executor/src/summary_kernels/factory/mod.rs +++ b/crates/executor/src/summary_kernels/factory/mod.rs @@ -5,6 +5,7 @@ use crate::summary_kernels::{ CountMinSketchAccumulator, DDSketchAccumulator, DatasketchesKLLAccumulator, HydraCms, HydraKllSketchAccumulator, }; +use crate::values::is_stale_marker; use crate::AggregateCore; use planner_types::ir::schema::FieldDataType as SummaryFamilyType; use planner_types::summary_type::{SketchAlgorithm, SketchParams}; @@ -62,7 +63,7 @@ pub(crate) fn distinct_item(value: &crate::values::Value) -> Result DistinctItem::Skipped, - // A sample must be finite, as every numeric kernel requires. + // A sample must be finite, as every sketch kernel requires. Value::Float64(value) => { finite_input(*value)?; DistinctItem::Sample(*value) @@ -73,7 +74,8 @@ pub(crate) fn distinct_item(value: &crate::values::Value) -> Result Result<(), String> { if value.is_finite() { Ok(()) @@ -82,6 +84,45 @@ pub(crate) fn finite_input(value: f64) -> Result<(), String> { } } +/// The input rule of an exact accumulator of `kind`. A sum, count, min +/// or max takes any value with PromQL's semantics, since a division by +/// zero upstream gives one (`q / 0` is +Inf, `0 / 0` NaN): a sum that sees +/// NaN, or +Inf and -Inf, is NaN; a count counts the value; min and max +/// skip NaN unless every value is NaN. A stale marker is not a value +/// ([`not_a_stale_marker`]). A counter's rate or increase needs finite +/// samples ([`finite_input`]). +pub(crate) fn exact_accumulator_input( + kind: planner_types::summary_type::ExactKind, + value: f64, +) -> Result<(), String> { + use planner_types::summary_type::ExactKind; + match kind { + ExactKind::Sum | ExactKind::Count | ExactKind::Min | ExactKind::Max => { + not_a_stale_marker(value) + } + ExactKind::Increase | ExactKind::Rate | ExactKind::IRate => finite_input(value), + } +} + +/// An error when `value` is a Prometheus stale marker. A stale marker ends +/// a series and is not a sample: the `TimeRange` a chain builds over its +/// time series' `Scan` drops it before any accumulator sees it. One that +/// reaches an exact sum, count, min or max means the chain read the series +/// through another operator (a `Filter` or a `Project` that copies the +/// value), and it would turn `sum_over_time` into NaN or add one to +/// `count_over_time` silently. +fn not_a_stale_marker(value: f64) -> Result<(), String> { + if is_stale_marker(value) { + Err( + "a stale marker reached an exact accumulator: its chain must read the time \ + series' Scan, whose TimeRange drops stale markers" + .to_string(), + ) + } else { + Ok(()) + } +} + /// Shared update interface for query-time and precompute-time accumulation. /// /// This provides a uniform interface over all accumulator types so that the @@ -575,6 +616,12 @@ struct PlannerExactUpdater { acc: crate::summary_kernels::exact::ExactAccumulator, } impl AccumulatorUpdater for PlannerExactUpdater { + fn validate_single_input(&self, value: f64) -> Result<(), String> { + exact_accumulator_input( + crate::summary_kernels::exact::statistic_of(self.acc.family()), + value, + ) + } fn update_single(&mut self, value: f64, timestamp: i64) -> Result<(), String> { self.acc.update(None, value, timestamp); Ok(()) diff --git a/crates/executor/src/summary_kernels/factory/tests.rs b/crates/executor/src/summary_kernels/factory/tests.rs index 1bf70defd..0d0cbb809 100644 --- a/crates/executor/src/summary_kernels/factory/tests.rs +++ b/crates/executor/src/summary_kernels/factory/tests.rs @@ -106,3 +106,56 @@ fn an_hll_takes_int64_and_utf8_items() { .unwrap(); assert_eq!(estimate, 60.0); } + +/// An exact sum, count, min or max takes a non-finite value with PromQL's +/// semantics, as a division by zero upstream gives (`q / 0` is +Inf, +/// `0 / 0` NaN): a sum that sees +Inf is +Inf, then NaN once it also sees +/// -Inf or NaN; a count counts it; min and max skip NaN unless every +/// value is NaN. A counter's rate or increase still needs finite samples. +/// A stale marker is not a value: one that reaches the accumulator (its +/// `TimeRange` did not drop it) is an error, not a NaN summed or counted. +#[test] +fn exact_accumulators_take_non_finite_values_as_promql_does() { + use crate::values::Value; + use planner_types::summary_type::{ExactKind, SummaryUpdate}; + let update = SummaryUpdate::column(planner_types::ir::scalar::ColumnRef::SampleValue); + let finalized = |kind: ExactKind, values: &[f64]| -> Result, String> { + let family = SummaryFamilyType::exact(kind); + let mut updater = create_planner_accumulator(&family, None, &update)?; + for value in values { + updater.update_value(&Value::Float64(*value), 0)?; + } + let state = updater.take_accumulator(); + let exact = state + .as_any() + .downcast_ref::() + .expect("an exact state"); + exact + .evaluation(kind, None, None) + .map_err(|error| error.to_string()) + }; + let (inf, nan) = (f64::INFINITY, f64::NAN); + assert_eq!(finalized(ExactKind::Sum, &[1.0, inf]), Ok(Some(inf))); + for values in [[1.0, nan], [inf, -inf]] { + assert!(finalized(ExactKind::Sum, &values) + .unwrap() + .unwrap() + .is_nan()); + } + assert_eq!(finalized(ExactKind::Count, &[1.0, nan, inf]), Ok(Some(3.0))); + assert_eq!(finalized(ExactKind::Min, &[nan, 2.0, -inf]), Ok(Some(-inf))); + assert_eq!(finalized(ExactKind::Max, &[2.0, nan]), Ok(Some(2.0))); + assert!(finalized(ExactKind::Max, &[nan]).unwrap().unwrap().is_nan()); + for kind in [ExactKind::Rate, ExactKind::Increase] { + assert!(finalized(kind, &[1.0, nan]).is_err(), "{kind:?}"); + } + let stale = f64::from_bits(crate::values::STALE_MARKER); + for kind in [ + ExactKind::Sum, + ExactKind::Count, + ExactKind::Min, + ExactKind::Max, + ] { + assert!(finalized(kind, &[1.0, stale]).is_err(), "{kind:?}"); + } +} diff --git a/crates/executor/src/summary_kernels/state_column_updater/mod.rs b/crates/executor/src/summary_kernels/state_column_updater/mod.rs index 194b7eb44..a5b9cc5f4 100644 --- a/crates/executor/src/summary_kernels/state_column_updater/mod.rs +++ b/crates/executor/src/summary_kernels/state_column_updater/mod.rs @@ -283,9 +283,9 @@ impl StateColumnUpdater { /// Add one sample to `group`'s state: `value` observed at /// `timestamp_ms` (read only by counters). Bad input for a group never /// added; an operator error when the state cannot take the value (not - /// finite, outside a DDSketch's domain, a counter sample not after the - /// group's previous one) or the family is keyed. The state is then - /// unchanged. + /// finite for a sketch or a counter, outside a DDSketch's domain, a + /// counter sample not after the group's previous one) or the family is + /// keyed. The state is then unchanged. pub fn update(&mut self, group: u32, value: f64, timestamp_ms: i64) -> Result<(), Error> { self.update_value(group, &Value::Float64(value), timestamp_ms) } @@ -309,15 +309,19 @@ impl StateColumnUpdater { } match &mut self.states { GroupStates::Exact { states, .. } => { - // The exact kernel's input contract (`AccumulatorUpdater`); a - // count counts every non-NULL value of any type, NaN included - // (SQL `COUNT(col)`). + // The exact kernel's input rule + // (`factory::exact_accumulator_input`); a count also counts + // a non-NULL value of any other type (SQL `COUNT(col)`). + let FieldDataType::ExactAggregate(kind, _) = &self.family else { + unreachable!("exact states belong to an exact family") + }; match (&states[index], value) { - (ScalarState::Count(_), _) => states[index].update(0.0, timestamp_ms), (_, Value::Float64(value)) => { - super::factory::finite_input(*value).map_err(operator_error)?; + super::factory::exact_accumulator_input(*kind, *value) + .map_err(operator_error)?; states[index].update(*value, timestamp_ms); } + (ScalarState::Count(_), _) => states[index].update(0.0, timestamp_ms), _ => return Err(operator_error("summary update requires Float64")), } } diff --git a/crates/executor/src/summary_kernels/state_column_updater/tests.rs b/crates/executor/src/summary_kernels/state_column_updater/tests.rs index 74598e7cb..c44b03ea4 100644 --- a/crates/executor/src/summary_kernels/state_column_updater/tests.rs +++ b/crates/executor/src/summary_kernels/state_column_updater/tests.rs @@ -24,3 +24,39 @@ fn exact_memory_is_the_buffer_capacity() { ); } } + +// A state column of exact sums takes +Inf and NaN, as the exact kernel +// does (`AccumulatorUpdater`): PromQL's `sum` over `q / 0` is +Inf, over +// `0 / 0` NaN. A rate column still refuses a non-finite sample, and a +// sum or count column a stale marker, which is not a sample. +#[test] +fn an_exact_sum_column_takes_non_finite_values() { + let sum = FieldDataType::ExactAggregate(ExactKind::Sum, ExactParams::Sum); + let mut updater = StateColumnUpdater::new(&sum, None).unwrap(); + updater.ensure_groups(2).unwrap(); + updater.update(0, 1.0, 0).unwrap(); + updater.update(0, f64::INFINITY, 0).unwrap(); + updater.update(1, f64::NAN, 0).unwrap(); + let GroupStates::Exact { states, .. } = &updater.states else { + unreachable!() + }; + let read = |group: usize| { + states[group] + .evaluation(ExactKind::Sum, None) + .unwrap() + .unwrap() + }; + assert_eq!(read(0), f64::INFINITY); + assert!(read(1).is_nan()); + let rate = FieldDataType::ExactAggregate(ExactKind::Rate, ExactParams::Rate); + let mut updater = StateColumnUpdater::new(&rate, None).unwrap(); + updater.ensure_groups(1).unwrap(); + assert!(updater.update(0, f64::NAN, 0).is_err()); + let stale = f64::from_bits(crate::values::STALE_MARKER); + let count = FieldDataType::ExactAggregate(ExactKind::Count, ExactParams::Count); + for column in [sum, count] { + let mut updater = StateColumnUpdater::new(&column, None).unwrap(); + updater.ensure_groups(1).unwrap(); + assert!(updater.update(0, stale, 0).is_err(), "{column:?}"); + } +} diff --git a/crates/executor/src/values/mod.rs b/crates/executor/src/values/mod.rs index 8febfc053..4481de4a0 100644 --- a/crates/executor/src/values/mod.rs +++ b/crates/executor/src/values/mod.rs @@ -14,6 +14,17 @@ pub(crate) use state_column::StateStorage; /// Shared ownership of schema metadata; the field model is identical at planning /// and execution time. pub type SchemaRef = Arc; + +/// The bits of the Prometheus stale marker, a NaN that Remote Write +/// carries when a series ends. It is not a sample. +pub(crate) const STALE_MARKER: u64 = 0x7ff0_0000_0000_0002; + +/// Whether `value` is the Prometheus stale marker ([`STALE_MARKER`]), +/// not a sample: `f64::from_bits(0x7ff0_0000_0000_0002)` is one, while an +/// ordinary NaN such as `0.0 / 0.0` is a sample. +pub(crate) fn is_stale_marker(value: f64) -> bool { + value.to_bits() == STALE_MARKER +} #[derive(Clone, serde::Serialize, serde::Deserialize)] pub enum Value { Null, diff --git a/crates/types/src/ir/operator/asap.rs b/crates/types/src/ir/operator/asap.rs index e53e1eee2..44279f9de 100644 --- a/crates/types/src/ir/operator/asap.rs +++ b/crates/types/src/ir/operator/asap.rs @@ -823,48 +823,30 @@ fn finalized_schema( }, ) = build { - { - use crate::ir::operator::AggIntent; - use crate::summary_type::{ExactKind, SummaryInputExpr}; - let column = match &input.weight { - SummaryInputExpr::Column(col) => Some( - crate::ir::scalar::column_resolution::resolve_column_ref(col, source.schema()) - .map_err(|e| { - SchemaDerivationError::InvalidScalarSignature(e.to_string()) - })?, - ), - _ => None, - }; - let measure = match kind { - ExactKind::Sum => Some(AggIntent::Sum { col: column }), - ExactKind::Min => Some(AggIntent::Min { col: column }), - ExactKind::Max => Some(AggIntent::Max { col: column }), - ExactKind::Count => Some(AggIntent::Count), - ExactKind::Rate => Some(AggIntent::Rate), - ExactKind::IRate => Some(AggIntent::IRate), - ExactKind::Increase => Some(AggIntent::Increase), - }; - measure - .map(|measure| { - crate::ir::NonASAPOp::Aggregate { - child: source.clone(), - reduction: reduction.clone(), - measures: vec![measure], - output_names: vec![String::new()], - // A filtered SUM/MIN/MAX is NULL for a - // group without a matching row. - filters: vec![filter.clone()], - having: None, - } - .output_schema() - }) - .transpose()? - .and_then(|s| match reduction { - Reduction::PerEntity => { - s.column_id("value").and_then(|i| s.fields.get(i).cloned()) - } - Reduction::Reduce(_) => s.fields.last().cloned(), - }) + use crate::summary_type::SummaryInputExpr; + let column = match &input.weight { + SummaryInputExpr::Column(col) => Some( + crate::ir::scalar::column_resolution::resolve_column_ref(col, source.schema()) + .map_err(|e| SchemaDerivationError::InvalidScalarSignature(e.to_string()))?, + ), + _ => None, + }; + let aggregate_schema = crate::ir::NonASAPOp::Aggregate { + child: source.clone(), + reduction: reduction.clone(), + measures: vec![kind.measure(column)], + output_names: vec![String::new()], + // A filtered SUM/MIN/MAX is NULL for a + // group without a matching row. + filters: vec![filter.clone()], + having: None, + } + .output_schema()?; + match reduction { + Reduction::PerEntity => aggregate_schema + .column_id("value") + .and_then(|i| aggregate_schema.fields.get(i).cloned()), + Reduction::Reduce(_) => aggregate_schema.fields.last().cloned(), } } else { None diff --git a/crates/types/src/stages/logical/group/column_properties.rs b/crates/types/src/stages/logical/group/column_properties.rs index 82be7197e..29b437282 100644 --- a/crates/types/src/stages/logical/group/column_properties.rs +++ b/crates/types/src/stages/logical/group/column_properties.rs @@ -24,7 +24,7 @@ use crate::ir::schema::topk::{ranked_row_projection, topk_output_name}; use crate::ir::schema::{ColumnId, FieldDataType, Schema}; use crate::ir::{ASAPOp, NonASAPOp, Operator}; use crate::summary_type::{ - ExactKind, SketchStatistic, SummaryInputExpr, SummaryTypeCapability, SummaryUpdate, + SketchStatistic, SummaryInputExpr, SummaryTypeCapability, SummaryUpdate, }; use crate::workload::bounds::source_name; use crate::workload::{series_facts, PrometheusMetricType, SourceFacts}; @@ -463,18 +463,19 @@ fn asap_columns(op: &ASAPOp>, output: &Schema) -> Vec state, }), + // The finalized value has the sign of the aggregate the accumulator + // computes, over values of the state's recorded sign: a rate over + // non-positive samples (-5 then -3: +2; -3 then -5: a reset, -5) + // has none, a count is non-negative and a sum keeps its sign. FinalizeExactAccumulator { child } => { - let counts = child.schema().fields.iter().any(|field| { - matches!( - field.dtype, - FieldDataType::ExactAggregate(ExactKind::Count, _) - ) - }); - readout_columns( - child, - output, - |state, _| if counts { NonNegative } else { state }, - ) + readout_columns(child, output, |state, summary_type| match summary_type { + FieldDataType::ExactAggregate(kind, _) => measure_sign(&kind.measure(None), state), + FieldDataType::Plain(_) + | FieldDataType::Sketch(_) + | FieldDataType::SummarySample(..) + | FieldDataType::Wavelet(..) + | FieldDataType::StatModel(..) => Unknown, + }) } MaintainPopulation { child, .. } => columns_of(child), EvaluatePopulation { child, .. } if output == child.schema() => columns_of(child), diff --git a/crates/types/src/summary_type/parameters.rs b/crates/types/src/summary_type/parameters.rs index 004855cc3..339fa9b83 100644 --- a/crates/types/src/summary_type/parameters.rs +++ b/crates/types/src/summary_type/parameters.rs @@ -32,6 +32,28 @@ pub enum ExactKind { IRate, } +impl ExactKind { + /// The aggregate an exact accumulator of this kind computes, of input + /// column `column` (`None`: the sample value): `ExactKind::Rate` + /// finalizes to what `AggIntent::Rate` computes, and + /// `ExactKind::Sum.measure(Some(2))` to `AggIntent::Sum { col: Some(2) }`. + pub(crate) fn measure( + self, + column: Option, + ) -> crate::ir::operator::AggIntent { + use crate::ir::operator::AggIntent; + match self { + ExactKind::Sum => AggIntent::Sum { col: column }, + ExactKind::Min => AggIntent::Min { col: column }, + ExactKind::Max => AggIntent::Max { col: column }, + ExactKind::Count => AggIntent::Count, + ExactKind::Rate => AggIntent::Rate, + ExactKind::IRate => AggIntent::IRate, + ExactKind::Increase => AggIntent::Increase, + } + } +} + /// Parameters for an [`ExactKind`] accumulator. All exact accumulators have /// fixed semantics — no tuning parameters — so each variant carries none; /// kept as a per-kind enum (mirroring [`SketchParams`]) so a mismatched diff --git a/crates/types/src/test_support/memo_fixtures.rs b/crates/types/src/test_support/memo_fixtures.rs index 9a23b9a4e..db6fcb344 100644 --- a/crates/types/src/test_support/memo_fixtures.rs +++ b/crates/types/src/test_support/memo_fixtures.rs @@ -6,7 +6,7 @@ use std::time::Duration; use crate::ir::operator::arguments::{ - AtModifier, BinaryOpKind, Reduction, Source, SourceColumn, TimeShift, + AtModifier, BinaryOpKind, PromQLVectorSetOpKind, Reduction, Source, SourceColumn, TimeShift, }; use crate::ir::operator::AggIntent; use crate::ir::scalar::expr_ir::{ArithmeticOpKind, CompareOpKind}; @@ -173,11 +173,25 @@ pub fn arithmetic( lhs: MemoGroupId, rhs: MemoGroupId, ) -> Operator { + binary_op(BinaryOpKind::Arithmetic(kind), lhs, rhs) +} + +/// `lhs and rhs`, `lhs or rhs` or `lhs unless rhs`, series by series, +/// without vector matching. +pub fn set_operator( + kind: PromQLVectorSetOpKind, + lhs: MemoGroupId, + rhs: MemoGroupId, +) -> Operator { + binary_op(BinaryOpKind::Set(kind), lhs, rhs) +} + +fn binary_op(kind: BinaryOpKind, lhs: MemoGroupId, rhs: MemoGroupId) -> Operator { Operator::NonASAP(NonASAPOp::BinaryOp { operator: BinaryOperator { checked_relative_division: false, checked_finite_division: false, - kind: BinaryOpKind::Arithmetic(kind), + kind, vector_match: None, }, return_bool: false, diff --git a/crates/types/tests/memo_group_properties.rs b/crates/types/tests/memo_group_properties.rs index 4024f5ba1..bf3e14c3d 100644 --- a/crates/types/tests/memo_group_properties.rs +++ b/crates/types/tests/memo_group_properties.rs @@ -854,3 +854,71 @@ fn scalar_arithmetic_follows_its_operands_signs() { assert_eq!(signs(&memo, group), [Unknown, value, Unknown], "{group:?}"); } } + +/// Finalizing an exact accumulator gives its value the sign the logical +/// aggregate it computes has (`measure_sign`), per accumulator kind: a sum, +/// min or max keeps the sign of the values it was updated with, a count is +/// non-negative, and a counter's increase, rate or irate is non-negative +/// only over non-negative values. Over `neg` (declared non-positive) a +/// counter-reset-aware delta can have either sign: samples -5 then -3 are +/// an increase of 2, samples -3 then -5 a reset and an increase of -5. +/// +/// | Group | Expression | value sign | +/// |---|---|---| +/// | G4 | `Finalize(SummaryAgg[Rate](neg[1m]))` | `Unknown` (was the weight's `NonPositive`) | +/// | G4 | `Finalize(SummaryAgg[Increase](neg[1m]))` | `Unknown` | +/// | G4 | `Finalize(SummaryAgg[IRate](neg[1m]))` | `Unknown` | +/// | G4 | `Finalize(SummaryAgg[Sum](neg[1m]))` | `NonPositive` | +/// | G4 | `Finalize(SummaryAgg[Min](neg[1m]))` | `NonPositive` | +/// | G4 | `Finalize(SummaryAgg[Count](neg[1m]))` | `NonNegative` | +/// | G4 | `Finalize(SummaryAgg[Rate](latency[1m]))` | `NonNegative` | +#[test] +fn a_finalized_exact_accumulator_has_its_aggregates_sign() { + use asap_types::summary_type::ExactKind; + let mut memo = Memo::new(&DataWorkload { + sources: BTreeMap::from([ + ( + "latency".to_string(), + SourceFacts { + column_signs: BTreeMap::from([("value".to_string(), NonNegative)]), + ..SourceFacts::default() + }, + ), + ( + "neg".to_string(), + SourceFacts { + column_signs: BTreeMap::from([("value".to_string(), NonPositive)]), + ..SourceFacts::default() + }, + ), + ]), + ..DataWorkload::default() + }); + let mut finalized_value_sign = |metric: &str, kind: ExactKind| { + let g1 = add(&mut memo, series(metric)); + let g2 = add(&mut memo, range(MINUTE_MS, g1)); + let g3 = add(&mut memo, state(FieldDataType::exact(kind), g2)); + let g4 = add( + &mut memo, + Operator::ASAP(ASAPOp::FinalizeExactAccumulator { child: g3 }), + ); + signs(&memo, g4)[VALUE] + }; + for (metric, kind, expected) in [ + ("neg", ExactKind::Rate, Unknown), + ("neg", ExactKind::Increase, Unknown), + ("neg", ExactKind::IRate, Unknown), + ("neg", ExactKind::Sum, NonPositive), + ("neg", ExactKind::Min, NonPositive), + ("neg", ExactKind::Max, NonPositive), + ("neg", ExactKind::Count, NonNegative), + ("latency", ExactKind::Rate, NonNegative), + ("latency", ExactKind::Sum, NonNegative), + ] { + assert_eq!( + finalized_value_sign(metric, kind), + expected, + "{kind:?} over {metric}" + ); + } +} diff --git a/docs/design_docs/concepts/accuracy-models.md b/docs/design_docs/concepts/accuracy-models.md index 633812520..079a5581e 100644 --- a/docs/design_docs/concepts/accuracy-models.md +++ b/docs/design_docs/concepts/accuracy-models.md @@ -78,10 +78,11 @@ unknown (generic HLL) serves no query with an accuracy target heap size and its value guarantee alone (the contracts table). Pass 2 gives each sketch readout the error and per-value failure probability -`δ / max(V, R)` it must meet, with `R` the readout group's values per -evaluation (the series its scans read): a `max` over 1000 readouts returns +`δ / max(V, R)` it must meet, with `R` the readout values the query's output +can depend on (the values per evaluation of every readout group below it, +summed: the series their scans read): a `max` over 1000 readouts returns one value yet fails when any readout does, so the union bound gives δ over -every readout read; +every readout read, and `max by (job) (q or r)` reads those of both sides; Pass 1's candidate takes the first requirement level and Pass 2 adds a copy per further level. A readout several queries reach gets the union of their levels. Pass 2 sizes nothing: a state has one build per listed θ, and each @@ -227,7 +228,8 @@ within its validity cap `b_i` (`ErrorContract::error_factor_per_input` and |---|---| | Sort, TimeRange, TimeShift, Concat, a readout, a finalize, a summary merge | `β = 1` in any metric | | Filter on columns copied from a source (labels and keys) | `β = 1` in any metric; a filter comparing a computed value has none | -| Project | Judged on the items reading a computed value (labels, the time and the series identity are copied): `β = 1` in any metric for a copied column; absolute error, `β = 1`, for `abs`, `clamp`, `clamp_min`, `clamp_max` (also PromQL's `promql_` functions) and a negation; relative error, `β = 1`, for a product with or quotient by a nonzero constant | +| PromQL `and`, `unless`, `or`; `label_replace`, `label_join` of labels | `β = 1` in any metric on each input whose values are copied; `β = 0` on the right input of `and` and `unless`, whose values are not read. This needs each side's series to be exact: no operator with a contract drops a row by its value, and a readout emits the series the exact evaluation does. A relabel reading a computed value has none | +| Project | Judged on the items reading a computed value (labels, the time and the series identity are copied): `β = 1` in any metric for a copied column; absolute error, `β = 1`, for `abs`, `clamp`, `clamp_min`, `clamp_max` (also PromQL's `promql_` functions) and a negation; relative error, `β = 1`, for `abs` and a negation (`\|−x̂ − (−x)\| = \|x̂ − x\|`, `\|\|x̂\| − \|x\|\| ≤ \|x̂ − x\|`, and `\|−x\| = \|\|x\|\| = \|x\|`) and for a product with or quotient by a nonzero constant | | Aggregate or exact-accumulator build of counts, min, max, avg, sum | Counts `β = 0`; min and max absolute or relative with `β = 1`; avg absolute with `β = 1`; sum and avg relative with `β = 1` when the values they aggregate are of one sign (the input column's `column_signs` is non-negative or non-positive): `\|Σ (x̂_i − x_i)\| ≤ ε Σ \|x_i\| = ε \|Σ x_i\|`; only when every group-by key is copied from a source (a `by` key as listed; for `without`, every column but the time, the sample value and the excluded ones); none with measure filters or `HAVING`, or with a key reading an estimate | | `+`, `-` | Absolute error, `β = 1` | | `/` | Relative error, `β = 1/(1 − b)` on both operands, the denominator capped at `b` | @@ -240,9 +242,11 @@ algorithm's list, so it never excludes a listed θ. For relative errors `x` and `y` with `y ≤ b`, `(1 + x)(1 + y) − 1 ≤ (1 + b)·x + y`, and a ratio of relative errors `a` over `b` is within `(a + b)/(1 − b)`. A relative bound below 1 keeps zero at zero and keeps the sign, so a zero denominator gives the -same non-finite answer exactly and approximately. The ratio rule relies on -each operand's own relative guarantee (for DDSketch, its estimator contract: -one-signed values within the mapping's range). A sum or difference of +same non-finite answer exactly and approximately, except the sign of a zero: +an exact −0.0 may be read as +0.0, which flips the infinity's sign. The ratio +rule relies on each operand's own relative guarantee (for DDSketch, its +estimator contract: one-signed values within the mapping's range). A sum or +difference of relative errors has no relative bound (cancellation), and a rank error (KLL) has no value bound, so neither passes through division. Likewise, an exact sum above approximate values retains their uncertainty: exact arithmetic does @@ -269,23 +273,33 @@ largest error the readout's output may have for that query. - A query whose path reads one readout gives one requirement level: the target divided by the path's factor, at the target's failure probability per - value: a whole-result δ split over the larger of `n_q` and the readout's - own values per evaluation (`Memo::max_values_per_evaluation`: at most the - series scanned below it, the declared distinct values of its state's keys, - one without keys), since a reduction such as `max` fails when any readout - it reads does. `SELECT count(DISTINCT dst) FROM flows` at δ = 0.01 reads - one distinct count, so its readout keeps 0.01. -- A composed query (several readouts, such as a ratio) gives every level of - the error grid (10%, 5%, 2%, 1%, 0.5%, 0.2%, 0.1%) and the failure-probability - grid (powers of ten from 1e-2 down to 1e-5, continued down to the first - one at or below a tenth of the query's per-value failure probability) not - looser than the cap. The logical-edge check then - keeps the levels a producer's θ meets. + value: a whole-result δ split over the larger of `n_q` and the readout + values the query's output can depend on, summed over every readout group + below it (`Memo::max_values_per_evaluation` each: at most the series + scanned below it, the declared distinct values of its state's keys, one + without keys), since a reduction such as `max` fails when any readout it + reads does. `SELECT count(DISTINCT dst) FROM flows` at δ = 0.01 reads + one distinct count, so its readout keeps 0.01. `max by (job) (q or r)` + with 3 series per side reads 6 readout values, so each gets δ / 6; a + bare `q or r` copies each output value from one readout value, but its + whole result still fails when any of them does, so it too splits δ over + the readout values of both sides. +- A composed query (several readouts whose errors reach its output, `β > 0`, + such as a ratio; `q and r` reads one, since `r`'s values are not read, and + `q or r` combines none, since each output value is copied from one side + and its error is that side's) gives every level of the error grid (10%, + 5%, 2%, 1%, 0.5%, 0.2%, 0.1%) and the failure-probability grid (powers of + ten from 1e-2 down to 1e-5, continued down to the first one at or below a + tenth of the query's per-value failure probability) not looser than the + cap. The logical-edge check then keeps the levels a producer's θ meets. - A readout reached by several queries gets the union of their levels. -- A count reads no value (`β = 0`): the readouts below it get no level - through it. +- A count reads no value (`β = 0`), and neither does the right input of + `and` and `unless`: the readouts below it get no level through it, and + an operator above it combines no error of them (`q / count(r)` reads + one readout's error). - A query whose target sets a failure probability with no per-value one - (`n_q` or the readout's values per evaluation unknown) gives no level. A + (`n_q` or the values per evaluation of a readout below it unknown) gives + no level. A readout no query gives a level is pruned (`RootPruneReason::ValuesPerEvaluationUnknown`); one another query gives a level stays, and the query reads its group only exactly. diff --git a/docs/develop_docs/end-to-end-accuracy-guarantees.md b/docs/develop_docs/end-to-end-accuracy-guarantees.md index c4676323f..cc068e8aa 100644 --- a/docs/develop_docs/end-to-end-accuracy-guarantees.md +++ b/docs/develop_docs/end-to-end-accuracy-guarantees.md @@ -113,9 +113,12 @@ keeps the metric: an input's error and the output's are in the same one. | --- | --- | --- | --- | | `Sort`, `TimeRange`, `TimeShift`, `Concat`, a readout, a finalize, `SummaryMerge` | any | 1 | none | | `Filter` whose predicate reads only columns copied from a source (labels, keys) | any | 1 | none | +| PromQL `and`, `unless` (the right side's series are exact: no operator with a contract drops a row by its value) | any | 1 on the left, 0 on the right | none | +| PromQL `or` (each side's series are exact, as for `and`: `or` keeps the right side's series the left side lacks) | any | 1 on both | none | +| `PromqlRelabel` (`label_replace`, `label_join`) whose new label reads no computed value | any | 1 | none | | `Project` whose items reading a computed value (not a copied label, the time or the series identity) are copies | any | 1 | none | | the same, with items computing `abs`, `clamp`, `clamp_min`, `clamp_max` (or PromQL's `promql_abs`, …) or a negation of a column | absolute | 1 | none | -| the same, with items multiplying or dividing a column by a nonzero literal | relative | 1 | none | +| the same, with items computing `abs` or a negation of a column, or multiplying or dividing a column by a nonzero literal | relative | 1 | none | | `Aggregate` (or exact accumulator build) by keys copied from a source, without measure filters or `HAVING`: `count` | any | 0 | none | | the same: `min`, `max` | absolute, relative | 1 | none | | the same: `avg` | absolute | 1 | none | @@ -153,14 +156,19 @@ The contracts are used in three places: and metric. A query that reads one readout gives it one level, its cap at the target's failure probability per value (a whole-result δ split over the larger of the values one evaluation returns and the readout - group's values per evaluation, `Memo::max_values_per_evaluation`, since a - `max` over many readouts fails - when any of them does); a count passes no cap down; a query that combines several - readouts (a ratio of two quantiles) gives every level of the grid + values the query's output can depend on, summed over every readout group + below it, `Memo::max_values_per_evaluation` each, since a `max` over many + readouts fails when any of them does, and `max by (job) (q or r)` reads + the readouts of both sides); a count, and the right input of `and` and + `unless`, read no value and pass no cap down; a query that combines + several readouts whose errors reach its output (β > 0: a ratio of two + quantiles; `q and r` reads one, since `r`'s values are not read, and so + does `q / count(r)`; `q or r` combines none, since each output value is + copied from one side) gives every level of the grid `MAX_ERROR_LEVELS` × a failure-probability grid (powers of ten from 1e-2 down to 1e-5, continued to the first at or below a tenth of the per-value - δ) that is not looser than the cap and the per-value δ. Pass 2 writes each level on a readout - candidate of its own. + δ) that is not looser than the cap and the per-value δ. Pass 2 writes + each level on a readout candidate of its own. - **$\alpha^{\log}$** (`ErrorMetricsOfMemo::edge_meets_logical_requirements`, `accuracy/src/logical_edge/mod.rs`): an edge into a readout holds when the producer's θ has a guarantee (measured, else `theoretical_guarantee`)