Skip to content

Commit e6a98fe

Browse files
committed
pivot to lower-ratio Rule 2 + diagnostic gauges
Round 1 (cost_ns_per_row > 1000) didn't fire on Q18 because partial agg per-row cost at probe close (first 100k rows, hash table still small) is ~100-200 ns on the ARM bot, not 1000+. Lowering to 100 didn't help either — the measured cost at probe time underestimates the eventual asymptotic cost, so a single-shot probe-time threshold is fundamentally fragile. Pivot: - Drop `skip_partial_aggregation_cost_ns_per_row` entirely from the decision. Rule 2 is now a pure ratio check: skip when `ratio >= cost_min_ratio` (default 0.5). - This matches the empirical finding in the issue body: ratio_threshold = 0.6 makes Q18 1.73× faster on M-series. 0.5 is conservative around that — the 0.3 cost_min_ratio guard from before is gone. - Add two diagnostic gauges (always recorded, regardless of which rule fires): * `partial_agg_probe_ns_per_row` — measured per-row wall time * `partial_agg_probe_ratio_per_mille` — ratio × 1000 EXPLAIN ANALYZE shows these so we can revisit a real cost-aware rule later with actual numbers instead of guessing thresholds. Why keep `use_cost_model` as the flag name even though it isn't cost-aware anymore: the gauges (the basis for a future cost-aware rule) ride alongside, and we want a single opt-in surface that graduates from "lower ratio threshold" to "cost-aware" without churning configs. Unit tests rewritten to match: 5 tests covering off/on, fires/doesn't fire, fixed-rule precedence, and gauge recording.
1 parent 5c10375 commit e6a98fe

4 files changed

Lines changed: 135 additions & 105 deletions

File tree

‎datafusion/common/src/config.rs‎

Lines changed: 26 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -648,29 +648,34 @@ config_namespace! {
648648
/// aggregation ratio check and trying to switch to skipping aggregation mode
649649
pub skip_partial_aggregation_probe_rows_threshold: usize, default = 100_000
650650

651-
/// (experimental) When true, augment the fixed
652-
/// `skip_partial_aggregation_probe_ratio_threshold` check with a
653-
/// cost-aware rule: skip partial aggregation when the measured
654-
/// per-row wall time exceeds
655-
/// `skip_partial_aggregation_cost_ns_per_row` even at ratios below
656-
/// the fixed threshold (provided the ratio is at least
657-
/// `skip_partial_aggregation_cost_min_ratio`). Targets ClickBench
658-
/// Q18-shape queries where the ratio (~0.56) is below 0.8 but
659-
/// partial aggregation is net-negative due to heavy keys / aggs.
651+
/// (experimental) When true, apply a *secondary* skip rule on top
652+
/// of `skip_partial_aggregation_probe_ratio_threshold`: skip
653+
/// partial aggregation when the measured ratio is at least
654+
/// `skip_partial_aggregation_cost_min_ratio` (default 0.5).
655+
/// Targets ClickBench Q18-shape queries where the ratio (~0.56)
656+
/// sits just below the fixed 0.8 threshold so partial agg keeps
657+
/// running, but the absolute work (heavy variable-length keys,
658+
/// complex aggregates) makes it net-negative.
659+
///
660+
/// Empirical motivation: lowering the global ratio threshold to
661+
/// 0.6 fixes Q18 (1.73× faster) but risks regressing low-cost
662+
/// queries at similar ratios. This flag exposes the lower
663+
/// threshold as a separate, opt-in knob. Whether the cost-aware
664+
/// signal (`partial_agg_probe_ns_per_row` metric) can replace
665+
/// this static threshold is an open question — for now the
666+
/// metric is reported alongside so callers can evaluate.
660667
pub skip_partial_aggregation_use_cost_model: bool, default = true
661668

662-
/// Minimum measured per-row wall time (nanoseconds) of partial
663-
/// aggregation for the cost-aware skip rule to fire. Only
664-
/// consulted when `skip_partial_aggregation_use_cost_model` is
665-
/// true.
666-
pub skip_partial_aggregation_cost_ns_per_row: u64, default = 100
667-
668-
/// Lower bound on aggregation ratio (num_groups / input_rows) for
669-
/// the cost-aware skip rule to fire. Below this ratio partial
670-
/// aggregation is considered valuable enough to keep regardless
671-
/// of per-row cost. Only consulted when
672-
/// `skip_partial_aggregation_use_cost_model` is true.
673-
pub skip_partial_aggregation_cost_min_ratio: f64, default = 0.3
669+
/// Effective ratio threshold used by the cost-aware skip rule.
670+
/// Skip partial aggregation when ratio at probe close is at
671+
/// least this value (provided
672+
/// `skip_partial_aggregation_use_cost_model` is true).
673+
///
674+
/// Default 0.5 is the empirical sweet spot from ClickBench: 0.4
675+
/// would skip too aggressively (regresses low-cost queries
676+
/// that benefit from partial), 0.7 fails to catch Q18-shape
677+
/// queries.
678+
pub skip_partial_aggregation_cost_min_ratio: f64, default = 0.5
674679

675680
/// Should DataFusion use row number estimates at the input to decide
676681
/// whether increasing parallelism is beneficial or not. By default,

‎datafusion/physical-plan/src/aggregates/row_hash.rs‎

Lines changed: 104 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -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

187196
impl 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

Comments
 (0)