@@ -134,14 +134,11 @@ struct SkipAggregationProbe {
134134 /// (from `SessionConfig`). If the ratio exceeds this value, aggregation
135135 /// is skipped and input rows are directly converted to output
136136 probe_ratio_threshold : f64 ,
137- /// (experimental) Cost-aware skip rule: skip when measured per-row wall
138- /// time is high even at ratios below `probe_ratio_threshold` . Disabled
139- /// by default; preserves the current bare-ratio behaviour.
137+ /// (experimental) When true, apply a secondary skip rule using
138+ /// `cost_min_ratio` as a lower effective ratio threshold . Disabled
139+ /// by default to preserve the bare-ratio behaviour.
140140 use_cost_model : bool ,
141- /// Per-row wall-time threshold (ns) for cost-aware skip rule.
142- cost_ns_per_row_threshold : u64 ,
143- /// Minimum ratio for cost-aware skip rule to fire. Below this ratio
144- /// partial aggregation is kept regardless of per-row cost.
141+ /// Effective ratio threshold for the cost-aware skip rule.
145142 cost_min_ratio : f64 ,
146143
147144 // ========================================================================
@@ -174,25 +171,39 @@ struct SkipAggregationProbe {
174171 /// Operator-wide `elapsed_compute` metric. Cloned from
175172 /// `BaselineMetrics` so the probe can read the accumulated nanoseconds
176173 /// at decision time and infer the wall time spent on partial
177- /// aggregation so far (used by the cost-aware rule) .
174+ /// aggregation so far.
178175 elapsed_compute : metrics:: Time ,
179176 /// `elapsed_compute.value()` snapshot at probe construction. Diff
180177 /// against the live value gives wall time elapsed since the stream
181178 /// started — a close approximation of partial aggregation cost,
182179 /// since `elapsed_compute` covers exactly the timed work blocks in
183180 /// the partial-mode loop.
184181 elapsed_compute_at_probe_start : usize ,
182+ /// Diagnostic gauge: measured wall-time per input row (ns) at the
183+ /// most recent probe evaluation. `set` once per `update_state` call
184+ /// after `probe_rows_threshold` is met, so EXPLAIN ANALYZE reflects
185+ /// the last evaluation's reading regardless of whether a skip rule
186+ /// fired. Provides the empirical signal used to tune
187+ /// `cost_min_ratio` / future cost-based rules.
188+ probe_ns_per_row : metrics:: Gauge ,
189+ /// Diagnostic gauge: aggregation ratio (`num_groups / input_rows`)
190+ /// at the most recent probe evaluation, scaled by 1000 (so 0.565
191+ /// → 565). `usize` gauges store integers, so the scale lets us
192+ /// preserve three decimal digits without floating point.
193+ probe_ratio_per_mille : metrics:: Gauge ,
185194}
186195
187196impl SkipAggregationProbe {
197+ #[ expect( clippy:: too_many_arguments) ]
188198 fn new (
189199 probe_rows_threshold : usize ,
190200 probe_ratio_threshold : f64 ,
191201 use_cost_model : bool ,
192- cost_ns_per_row_threshold : u64 ,
193202 cost_min_ratio : f64 ,
194203 skipped_aggregation_rows : metrics:: Count ,
195204 elapsed_compute : metrics:: Time ,
205+ probe_ns_per_row : metrics:: Gauge ,
206+ probe_ratio_per_mille : metrics:: Gauge ,
196207 ) -> Self {
197208 let elapsed_compute_at_probe_start = elapsed_compute. value ( ) ;
198209 Self {
@@ -201,34 +212,34 @@ impl SkipAggregationProbe {
201212 probe_rows_threshold,
202213 probe_ratio_threshold,
203214 use_cost_model,
204- cost_ns_per_row_threshold,
205215 cost_min_ratio,
206216 should_skip : false ,
207217 is_locked : false ,
208218 skipped_aggregation_rows,
209219 elapsed_compute,
210220 elapsed_compute_at_probe_start,
221+ probe_ns_per_row,
222+ probe_ratio_per_mille,
211223 }
212224 }
213225
214226 /// Updates `SkipAggregationProbe` state:
215227 /// - increments the number of input rows
216228 /// - replaces the number of groups with the new value
217229 /// - on `probe_rows_threshold` exceeded applies the skip-decision rules
218- /// (fixed ratio threshold, plus the optional cost-aware rule)
219- /// - if `should_skip` is set, locks further state updates
230+ /// - records the diagnostic gauges
220231 ///
221232 /// Two skip rules are evaluated, in order:
222233 ///
223234 /// 1. **Fixed ratio**: `num_groups / input_rows >= probe_ratio_threshold`
224235 /// — the original behaviour, preserved for backwards compatibility.
225- /// 2. **Cost-aware ** (opt-in via `use_cost_model`): when the ratio is
226- /// above `cost_min_ratio` *and* the measured per-row wall time of
227- /// the operator exceeds `cost_ns_per_row_threshold`, skip even if
228- /// the ratio is below `probe_ratio_threshold`. This catches the
229- /// case where partial aggregation is net-negative due to high
230- /// per-row cost (heavy variable-length keys, expensive aggregates)
231- /// rather than poor reduction alone .
236+ /// 2. **Lower-ratio ** (opt-in via `use_cost_model`): skip when the ratio
237+ /// is at least `cost_min_ratio` (default 0.5). Targets the medium
238+ /// band (0.5–0.8) where partial aggregation is often net-negative
239+ /// despite the ratio being below the fixed threshold. The per-row
240+ /// cost gauge is reported alongside via `probe_ns_per_row` for
241+ /// diagnosing whether a cost-based replacement of this static
242+ /// threshold is feasible .
232243 fn update_state ( & mut self , input_rows : usize , num_groups : usize ) {
233244 if self . is_locked {
234245 return ;
@@ -238,29 +249,30 @@ impl SkipAggregationProbe {
238249 if self . input_rows >= self . probe_rows_threshold {
239250 let ratio = self . num_groups as f64 / self . input_rows as f64 ;
240251
252+ // Diagnostic gauges: always recorded at probe evaluation,
253+ // independent of which (if any) skip rule fires.
254+ let elapsed_ns = self
255+ . elapsed_compute
256+ . value ( )
257+ . saturating_sub ( self . elapsed_compute_at_probe_start ) ;
258+ let ns_per_row = ( elapsed_ns as u64 )
259+ . checked_div ( self . input_rows as u64 )
260+ . unwrap_or ( 0 ) ;
261+ self . probe_ns_per_row . set ( ns_per_row as usize ) ;
262+ self . probe_ratio_per_mille . set ( ( ratio * 1000.0 ) as usize ) ;
263+
241264 // Rule 1: fixed-ratio skip (existing behaviour).
242265 if ratio >= self . probe_ratio_threshold {
243266 self . should_skip = true ;
244267 self . is_locked = true ;
245268 return ;
246269 }
247270
248- // Rule 2 (opt-in): cost-aware skip for the medium-ratio,
249- // high-per-row-cost band.
271+ // Rule 2 (opt-in): lower-ratio skip.
250272 if self . use_cost_model && ratio >= self . cost_min_ratio {
251- let elapsed_ns = self
252- . elapsed_compute
253- . value ( )
254- . saturating_sub ( self . elapsed_compute_at_probe_start ) ;
255- let ns_per_row = ( elapsed_ns as u64 )
256- . checked_div ( self . input_rows as u64 )
257- . unwrap_or ( 0 ) ;
258- if ns_per_row > self . cost_ns_per_row_threshold {
259- self . should_skip = true ;
260- self . is_locked = true ;
261- }
273+ self . should_skip = true ;
274+ self . is_locked = true ;
262275 }
263-
264276 // No rule fired — leave `is_locked` false so the next batch
265277 // can re-evaluate.
266278 }
@@ -709,20 +721,25 @@ impl GroupedHashAggregateStream {
709721 let probe_ratio_threshold =
710722 options. skip_partial_aggregation_probe_ratio_threshold ;
711723 let use_cost_model = options. skip_partial_aggregation_use_cost_model ;
712- let cost_ns_per_row_threshold =
713- options. skip_partial_aggregation_cost_ns_per_row ;
714724 let cost_min_ratio = options. skip_partial_aggregation_cost_min_ratio ;
715725 let skipped_aggregation_rows = MetricBuilder :: new ( & agg. metrics )
716726 . with_category ( MetricCategory :: Rows )
717727 . counter ( "skipped_aggregation_rows" , partition) ;
728+ let probe_ns_per_row = MetricBuilder :: new ( & agg. metrics )
729+ . with_category ( MetricCategory :: Timing )
730+ . gauge ( "partial_agg_probe_ns_per_row" , partition) ;
731+ let probe_ratio_per_mille = MetricBuilder :: new ( & agg. metrics )
732+ . with_category ( MetricCategory :: Rows )
733+ . gauge ( "partial_agg_probe_ratio_per_mille" , partition) ;
718734 Some ( SkipAggregationProbe :: new (
719735 probe_rows_threshold,
720736 probe_ratio_threshold,
721737 use_cost_model,
722- cost_ns_per_row_threshold,
723738 cost_min_ratio,
724739 skipped_aggregation_rows,
725740 baseline_metrics. elapsed_compute ( ) . clone ( ) ,
741+ probe_ns_per_row,
742+ probe_ratio_per_mille,
726743 ) )
727744 } else {
728745 None
@@ -1893,25 +1910,26 @@ mod tests {
18931910
18941911 // ---------------- SkipAggregationProbe unit tests ----------------
18951912
1896- /// Build a probe with the given configuration. Skip-count metric is
1897- /// disconnected (a fresh `Count`) and `elapsed_compute` is a fresh
1898- /// `Time` that the test can drive with `add_duration`.
1913+ /// Build a probe with the given configuration. Skip-count metric and
1914+ /// diagnostic gauges are disconnected; `elapsed_compute` is exposed
1915+ /// so a test can drive it with `add_duration` to verify the
1916+ /// diagnostic gauge picks the value up.
18991917 fn make_probe (
19001918 probe_rows_threshold : usize ,
19011919 probe_ratio_threshold : f64 ,
19021920 use_cost_model : bool ,
1903- cost_ns_per_row_threshold : u64 ,
19041921 cost_min_ratio : f64 ,
19051922 ) -> ( SkipAggregationProbe , metrics:: Time ) {
19061923 let elapsed_compute = metrics:: Time :: new ( ) ;
19071924 let probe = SkipAggregationProbe :: new (
19081925 probe_rows_threshold,
19091926 probe_ratio_threshold,
19101927 use_cost_model,
1911- cost_ns_per_row_threshold,
19121928 cost_min_ratio,
19131929 metrics:: Count :: new ( ) ,
19141930 elapsed_compute. clone ( ) ,
1931+ metrics:: Gauge :: new ( ) ,
1932+ metrics:: Gauge :: new ( ) ,
19151933 ) ;
19161934 ( probe, elapsed_compute)
19171935 }
@@ -1920,7 +1938,7 @@ mod tests {
19201938 /// ratio check.
19211939 #[ test]
19221940 fn skip_probe_cost_model_off_matches_legacy_ratio_check ( ) {
1923- let ( mut probe, _t) = make_probe ( 100 , 0.8 , false , 1000 , 0.3 ) ;
1941+ let ( mut probe, _t) = make_probe ( 100 , 0.8 , false , 0.5 ) ;
19241942
19251943 // 100 rows / 50 groups → ratio 0.5, below 0.8 → don't skip
19261944 probe. update_state ( 100 , 50 ) ;
@@ -1934,62 +1952,72 @@ mod tests {
19341952 assert ! ( probe. is_locked) ;
19351953 }
19361954
1937- /// With the cost model on, a high-cost slow query in the medium- ratio
1938- /// band (0.3 ≤ ratio < 0.8) gets skipped — the ClickBench Q18 case .
1955+ /// With the cost model on, a medium-ratio query (Q18-shape: ratio
1956+ /// 0.56, below 0.8 but at or above `cost_min_ratio`) is skipped .
19391957 #[ test]
1940- fn skip_probe_cost_model_fires_in_medium_ratio_high_cost_band ( ) {
1941- let ( mut probe, elapsed ) = make_probe ( 100 , 0.8 , true , 1000 , 0.3 ) ;
1958+ fn skip_probe_cost_model_fires_in_medium_ratio_band ( ) {
1959+ let ( mut probe, _t ) = make_probe ( 100 , 0.8 , true , 0.5 ) ;
19421960
1943- // 200_000 ns over 100 rows → 2_000 ns/row → above the 1_000
1944- // threshold. Ratio 0.5 sits in the medium band.
1945- elapsed. add_duration ( Duration :: from_nanos ( 200_000 ) ) ;
1946- probe. update_state ( 100 , 50 ) ;
1961+ // Ratio 0.56 — Q18's measured value. Above the 0.5 threshold.
1962+ probe. update_state ( 100 , 56 ) ;
19471963
19481964 assert ! ( probe. should_skip( ) ) ;
19491965 assert ! ( probe. is_locked) ;
19501966 }
19511967
1952- /// Cost model on, ratio below `cost_min_ratio`: the partial agg is
1953- /// genuinely reducing a lot (small / cheap output), so we keep it
1954- /// regardless of per-row cost.
1968+ /// Cost model on, ratio below `cost_min_ratio`: keep partial agg —
1969+ /// it's reducing too much to be worth skipping.
19551970 #[ test]
19561971 fn skip_probe_cost_model_does_not_fire_below_min_ratio ( ) {
1957- let ( mut probe, elapsed ) = make_probe ( 100 , 0.8 , true , 1000 , 0.3 ) ;
1972+ let ( mut probe, _t ) = make_probe ( 100 , 0.8 , true , 0.5 ) ;
19581973
1959- // Very expensive — 5_000 ns/row — but ratio is 0.2 (huge
1960- // reduction), so partial agg is still net-positive.
1961- elapsed. add_duration ( Duration :: from_nanos ( 500_000 ) ) ;
1962- probe. update_state ( 100 , 20 ) ;
1963-
1964- assert ! ( !probe. should_skip( ) ) ;
1965- assert ! ( !probe. is_locked) ;
1966- }
1967-
1968- /// Cost model on but per-row cost is below threshold: ratio alone
1969- /// doesn't justify skipping → keep aggregating.
1970- #[ test]
1971- fn skip_probe_cost_model_does_not_fire_when_cheap_per_row ( ) {
1972- let ( mut probe, elapsed) = make_probe ( 100 , 0.8 , true , 1000 , 0.3 ) ;
1973-
1974- // 50_000 ns over 100 rows → 500 ns/row → below the 1_000 ns
1975- // threshold. Ratio 0.5 alone is below the fixed 0.8 cut-off.
1976- elapsed. add_duration ( Duration :: from_nanos ( 50_000 ) ) ;
1977- probe. update_state ( 100 , 50 ) ;
1974+ // Ratio 0.3 — well below the 0.5 threshold.
1975+ probe. update_state ( 100 , 30 ) ;
19781976
19791977 assert ! ( !probe. should_skip( ) ) ;
19801978 assert ! ( !probe. is_locked) ;
19811979 }
19821980
19831981 /// Cost model on still honours the original high-ratio rule: ratio
1984- /// >= `probe_ratio_threshold` skips regardless of cost.
1982+ /// at or above `probe_ratio_threshold` skips, even though the
1983+ /// lower-ratio rule would also fire.
19851984 #[ test]
19861985 fn skip_probe_cost_model_still_honours_high_ratio_rule ( ) {
1987- let ( mut probe, _t) = make_probe ( 100 , 0.8 , true , 1000 , 0.3 ) ;
1986+ let ( mut probe, _t) = make_probe ( 100 , 0.8 , true , 0.5 ) ;
19881987
1989- // Ratio 0.9, no measured cost → skip via the fixed rule.
1988+ // Ratio 0.9 → skip via the fixed rule (Rule 1) .
19901989 probe. update_state ( 100 , 90 ) ;
19911990
19921991 assert ! ( probe. should_skip( ) ) ;
19931992 assert ! ( probe. is_locked) ;
19941993 }
1994+
1995+ /// The diagnostic gauges record the measured per-row wall time and
1996+ /// the ratio (× 1000) on every probe evaluation, regardless of which
1997+ /// — if any — skip rule fires.
1998+ #[ test]
1999+ fn skip_probe_records_diagnostic_gauges ( ) {
2000+ let elapsed_compute = metrics:: Time :: new ( ) ;
2001+ let probe_ns_per_row = metrics:: Gauge :: new ( ) ;
2002+ let probe_ratio_per_mille = metrics:: Gauge :: new ( ) ;
2003+ let mut probe = SkipAggregationProbe :: new (
2004+ 100 ,
2005+ 0.8 ,
2006+ false ,
2007+ 0.5 ,
2008+ metrics:: Count :: new ( ) ,
2009+ elapsed_compute. clone ( ) ,
2010+ probe_ns_per_row. clone ( ) ,
2011+ probe_ratio_per_mille. clone ( ) ,
2012+ ) ;
2013+
2014+ // 200_000 ns over 100 rows → 2_000 ns/row. Ratio 50/100 = 0.5 →
2015+ // 500 per-mille. No skip fires (legacy ratio check is off, no
2016+ // 0.8 reached), but the gauges still update.
2017+ elapsed_compute. add_duration ( Duration :: from_nanos ( 200_000 ) ) ;
2018+ probe. update_state ( 100 , 50 ) ;
2019+
2020+ assert_eq ! ( probe_ns_per_row. value( ) , 2_000 ) ;
2021+ assert_eq ! ( probe_ratio_per_mille. value( ) , 500 ) ;
2022+ }
19952023}
0 commit comments