Skip to content

Commit 31ddcdf

Browse files
kosiewOmega359
authored andcommitted
Add aggregate-internal submetrics (apache#25051)
## Which issue does this PR close? * Closes apache#23570 This is the last of a series of PRs to close the issue ## Rationale for this change Existing per-aggregate operation metrics attribute complete `update`, `merge`, `state`, and `evaluate` calls to each aggregate expression, but they cannot show how much time an aggregate spends in meaningful internal subphases. This PR adds a separate contract for optional aggregate-owned submetrics so implementations can expose internal timing while retaining a clear owning aggregate expression and stable metric identity across repeated aggregates and partitions. The existing aggregate operation timers remain separate from these internal submetrics. `array_agg(DISTINCT ...)` is used as the representative implementation, exposing time spent in its distinct-value handling. ## What changes are included in this PR? * Adds `AggregateMetric` and `AggregateMetrics` interfaces for aggregate-owned internal metrics, plus `AggregateMetricRecorder` for recording one or more timed intervals into a submetric. * Adds optional metric injection to `Accumulator` and `GroupsAccumulator` while preserving default behavior for implementations that do not expose submetrics. * Adds grouped update/merge hooks so `GroupsAccumulatorAdapter` can time aggregate-owned work once across grouped dispatch rather than recording a timer for every group. * Registers aggregate submetrics lazily using stable names of the form `agg_expr_{index}_internal_{subphase}_time` and retains the aggregate label and partition identity. * Propagates submetric factories through hash, ordered, and streaming aggregate execution paths, including newly created/empty accumulators. * Instruments `DistinctArrayAggAccumulator` with a `distinct` submetric covering its distinct-value handling during updates and merges. * Keeps adapter-owned work such as slicing/filtering, size accounting, and state materialization outside the aggregate-owned submetric. * Updates grouped adapter allocation accounting so retained group-index scratch capacity is charged when the underlying vectors grow. * Adds a high-cardinality `array_agg(DISTINCT)` SQL benchmark with 1M groups and two rows per group. * Adds focused `GroupsAccumulatorAdapter`, `nth_value`, and `approx_percentile_cont` benchmarks to measure the grouped adapter path. * Adds `Time::add_duration_exact` so aggregate submetrics can accumulate durations without rounding every individual recording up to one nanosecond. ## Are these changes tested? Yes. The patch adds tests covering: * metric propagation to grouped accumulators; * grouped update and `convert_to_state` metric recording; * exclusion of adapter-owned size accounting and state materialization from internal timing; * metric recording on update errors; * allocation accounting and cleanup after grouped updates and errors; * `array_agg(DISTINCT)` update and merge metric recording; * metric identity reuse and support for multiple subphases; * zero-duration metric handling; * aggregate submetric naming and labels for repeated aggregate expressions; * aggregation and partition identity across multiple partitions; * aggregate execution with `array_agg(DISTINCT)` submetrics; * preservation of existing update/evaluate aggregate metrics; * compatibility with aggregates that do not expose internal submetrics. The patch also adds benchmarks for the uninstrumented grouped accumulator adapter path, ordered `nth_value`, `approx_percentile_cont`, and a 1M-group `array_agg(DISTINCT)` SQL workload. ## Are there any user-facing changes? `EXPLAIN ANALYZE`/aggregate execution metrics can now include optional aggregate-owned internal timing metrics for aggregates that expose them. In this PR, `array_agg(DISTINCT ...)` exposes an `internal_distinct` timing metric. Aggregates that do not expose internal submetrics retain their existing behavior and metrics. This PR also extends the public accumulator interfaces with optional metric-related methods that have default implementations. ## LLM-generated code disclosure This PR includes LLM-generated code and comments. All LLM-generated content has been manually reviewed.
1 parent 1503bfa commit 31ddcdf

24 files changed

Lines changed: 1871 additions & 157 deletions

File tree

‎benchmarks/bench.sh‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,7 @@ nlj: Benchmark for simple nested loop joins, testing various
165165
hj: Benchmark for simple hash joins, testing various join scenarios
166166
smj: Benchmark for simple sort merge joins, testing various join scenarios
167167
dict: Benchmark for dictionary-encoded group-by scenarios
168+
array_agg_distinct: 1000K-group, two-row-per-group array_agg(DISTINCT) benchmark
168169
compile_profile: Compile and execute TPC-H across selected Cargo profiles, reporting timing and binary size
169170
170171
@@ -660,6 +661,9 @@ main() {
660661
dict)
661662
run_dict
662663
;;
664+
array_agg_distinct)
665+
run_array_agg_distinct
666+
;;
663667
compile_profile)
664668
run_compile_profile "${PROFILE_ARGS[@]}"
665669
;;
@@ -1719,6 +1723,14 @@ run_dict() {
17191723
debug_run $CARGO_COMMAND --bin dfbench -- dict --iterations 5 -o "${RESULTS_FILE}" ${QUERY_ARG} ${LATENCY_ARG}
17201724
}
17211725

1726+
# Runs the data-free high-cardinality array_agg(DISTINCT) SQL benchmark.
1727+
run_array_agg_distinct() {
1728+
echo "Running array_agg_distinct benchmark..."
1729+
debug_run env BENCH_NAME=array_agg_distinct \
1730+
${QUERY:+BENCH_QUERY="${QUERY}"} \
1731+
bash -c "$SQL_CARGO_COMMAND"
1732+
}
1733+
17221734

17231735
compare_benchmarks() {
17241736
BASE_RESULTS_DIR="${SCRIPT_DIR}/results"
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
description = "High-cardinality array_agg(DISTINCT) SQL benchmarks"
2+
3+
query_pattern = "q{QUERY_ID_PADDED}.benchmark"
4+
5+
[[examples]]
6+
command = "cargo run --release --bin benchmark_runner -- array_agg_distinct"
7+
description = "Run the high-cardinality array_agg(DISTINCT) benchmark."
8+
9+
[[examples]]
10+
command = "cargo run --release --bin benchmark_runner -- array_agg_distinct --query 1 --iterations 5 --output /tmp/array_agg_distinct.json"
11+
description = "Run five iterations and write comparable JSON results."
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name Q01
2+
group array_agg_distinct
3+
4+
expect_plan AggregateExec
5+
6+
run
7+
-- 1M groups, 2 rows/group, and 2 distinct values/group. `range` is end-exclusive.
8+
-- This is data-free so comparisons isolate grouped array_agg(DISTINCT) execution.
9+
SELECT value / 2 AS k, array_agg(DISTINCT value % 2) AS distinct_values
10+
FROM range(2000000)
11+
GROUP BY value / 2;

‎datafusion/expr-common/src/accumulator.rs‎

Lines changed: 108 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,79 @@
1818
//! Accumulator module contains the trait definition for aggregation function's accumulators.
1919
2020
use arrow::array::ArrayRef;
21-
use datafusion_common::{Result, ScalarValue, internal_err};
21+
use datafusion_common::{Result, ScalarValue, instant::Instant, internal_err};
2222
use std::fmt::Debug;
23+
use std::sync::Arc;
24+
use std::time::Duration;
25+
26+
/// A metric owned by one aggregate implementation.
27+
///
28+
/// Aggregate implementations use this interface for optional internal
29+
/// subphases. The execution engine owns metric registration and aggregation.
30+
pub trait AggregateMetric: Debug + Send + Sync + std::panic::RefUnwindSafe {
31+
/// Adds elapsed time to this metric.
32+
fn add_duration(&self, duration: Duration);
33+
}
34+
35+
/// Factory for optional metrics owned by one aggregate expression.
36+
///
37+
/// `subphase` must be a stable static identifier. Repeated requests for the
38+
/// same subphase must return handles that update the same metric identity. An
39+
/// implementation may request no metrics. The execution engine assigns the
40+
/// aggregate expression identity.
41+
pub trait AggregateMetrics: Debug + Send + Sync {
42+
/// Returns the metric for an aggregate-owned internal subphase.
43+
fn metric(&self, subphase: &'static str) -> Arc<dyn AggregateMetric>;
44+
}
45+
46+
/// Publishes aggregate-owned timing when dropped.
47+
///
48+
/// Create this before the operation that may return an error, and scope each
49+
/// [`Self::timer`] to only the aggregate-owned work. All timed intervals are
50+
/// combined into one metric update when the recorder is dropped.
51+
pub struct AggregateMetricRecorder {
52+
metric: Option<Arc<dyn AggregateMetric>>,
53+
duration: Duration,
54+
}
55+
56+
impl AggregateMetricRecorder {
57+
/// Creates a recorder for an optional aggregate-owned metric.
58+
pub fn new(metric: Option<Arc<dyn AggregateMetric>>) -> Self {
59+
Self {
60+
metric,
61+
duration: Duration::ZERO,
62+
}
63+
}
64+
65+
/// Starts timing one aggregate-owned interval.
66+
pub fn timer(&mut self) -> Option<AggregateMetricTimer<'_>> {
67+
self.metric.as_ref()?;
68+
Some(AggregateMetricTimer {
69+
duration: &mut self.duration,
70+
start: Instant::now(),
71+
})
72+
}
73+
}
74+
75+
impl Drop for AggregateMetricRecorder {
76+
fn drop(&mut self) {
77+
if let Some(metric) = &self.metric {
78+
metric.add_duration(self.duration);
79+
}
80+
}
81+
}
82+
83+
/// One aggregate-owned interval recorded by [`AggregateMetricRecorder`].
84+
pub struct AggregateMetricTimer<'a> {
85+
duration: &'a mut Duration,
86+
start: Instant,
87+
}
88+
89+
impl Drop for AggregateMetricTimer<'_> {
90+
fn drop(&mut self) {
91+
*self.duration += self.start.elapsed();
92+
}
93+
}
2394

2495
/// Tracks an aggregate function's state.
2596
///
@@ -49,6 +120,15 @@ use std::fmt::Debug;
49120
/// [`merge_batch`]: Self::merge_batch
50121
/// [window function]: https://en.wikipedia.org/wiki/Window_function_(SQL)
51122
pub trait Accumulator: Send + Sync + Debug + std::any::Any {
123+
/// Supplies optional metrics owned by this aggregate expression.
124+
///
125+
/// The grouped accumulator adapter supplies these metrics to every
126+
/// accumulator it creates. Call this immediately after construction and
127+
/// before the accumulator is used; replacing metrics after use is
128+
/// unsupported. The default preserves compatibility for accumulators
129+
/// without internal submetrics.
130+
fn set_metrics(&mut self, _metrics: Arc<dyn AggregateMetrics>) {}
131+
52132
/// Updates the accumulator's state from its input.
53133
///
54134
/// `values` contains the arguments to this aggregate function.
@@ -58,6 +138,33 @@ pub trait Accumulator: Send + Sync + Debug + std::any::Any {
58138
/// running sum.
59139
fn update_batch(&mut self, values: &[ArrayRef]) -> Result<()>;
60140

141+
/// Returns an optional metric timed once per grouped adapter input batch.
142+
///
143+
/// A grouped accumulator adapter uses this for aggregate-owned work it
144+
/// dispatches to one accumulator per group. The default preserves the
145+
/// usual per-accumulator update path.
146+
fn grouped_update_batch_metric(&self) -> Option<Arc<dyn AggregateMetric>> {
147+
None
148+
}
149+
150+
/// Updates state when called by a grouped accumulator adapter.
151+
///
152+
/// The default delegates to [`Self::update_batch`]. Implementations that
153+
/// return a [`Self::grouped_update_batch_metric`] can avoid timing every
154+
/// per-group call; the adapter records one interval for the full batch.
155+
fn update_batch_grouped(&mut self, values: &[ArrayRef]) -> Result<()> {
156+
self.update_batch(values)
157+
}
158+
159+
/// Merges state when called by a grouped accumulator adapter.
160+
///
161+
/// The default delegates to [`Self::merge_batch`]. Implementations that
162+
/// return a [`Self::grouped_update_batch_metric`] can avoid timing every
163+
/// per-group merge; the adapter records one interval for the full batch.
164+
fn merge_batch_grouped(&mut self, states: &[ArrayRef]) -> Result<()> {
165+
self.merge_batch(states)
166+
}
167+
61168
/// Returns the final aggregate value.
62169
///
63170
/// For example, the `SUM` accumulator maintains a running sum,

‎datafusion/expr-common/src/groups_accumulator.rs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@
1919
2020
use arrow::array::{ArrayRef, BooleanArray};
2121
use datafusion_common::{Result, exec_err, not_impl_err, utils::split_vec_min_alloc};
22+
use std::sync::Arc;
23+
24+
use crate::accumulator::AggregateMetrics;
2225

2326
/// Describes how many rows should be emitted during grouping.
2427
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -188,6 +191,13 @@ impl<'a> GroupSelection<'a> {
188191
/// [`Accumulator`]: crate::accumulator::Accumulator
189192
/// [Aggregating Millions of Groups Fast blog]: https://arrow.apache.org/blog/2023/08/05/datafusion_fast_grouping/
190193
pub trait GroupsAccumulator: Send + std::any::Any {
194+
/// Supplies optional metrics owned by this aggregate expression.
195+
///
196+
/// Call this immediately after construction and before the accumulator is
197+
/// used; replacing metrics after use is unsupported. The default preserves
198+
/// compatibility for accumulators without internal submetrics.
199+
fn set_metrics(&mut self, _metrics: Arc<dyn AggregateMetrics>) {}
200+
191201
/// Updates the accumulator's state from its arguments, encoded as
192202
/// a vector of [`ArrayRef`]s.
193203
///

‎datafusion/expr/src/lib.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,9 @@ pub use datafusion_doc::{
101101
DocSection, Documentation, DocumentationBuilder, aggregate_doc_sections,
102102
scalar_doc_sections, window_doc_sections,
103103
};
104-
pub use datafusion_expr_common::accumulator::Accumulator;
104+
pub use datafusion_expr_common::accumulator::{
105+
Accumulator, AggregateMetric, AggregateMetricRecorder, AggregateMetrics,
106+
};
105107
pub use datafusion_expr_common::columnar_value::ColumnarValue;
106108
pub use datafusion_expr_common::groups_accumulator::{
107109
EmitTo, GroupSelection, GroupsAccumulator,

‎datafusion/functions-aggregate-common/Cargo.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,7 @@ rand = { workspace = true }
5757
[[bench]]
5858
harness = false
5959
name = "accumulate"
60+
61+
[[bench]]
62+
harness = false
63+
name = "groups_accumulator_adapter"
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one
2+
// or more contributor license agreements. See the NOTICE file
3+
// distributed with this work for additional information
4+
// regarding copyright ownership. The ASF licenses this file
5+
// to you under the Apache License, Version 2.0 (the
6+
// "License"); you may not use this file except in compliance
7+
// with the License. You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
18+
//! Benchmarks the uninstrumented `GroupsAccumulatorAdapter` update path.
19+
20+
use std::hint::black_box;
21+
use std::sync::Arc;
22+
23+
use arrow::array::{ArrayRef, Int64Array};
24+
use arrow::datatypes::DataType;
25+
use criterion::{BatchSize, Criterion, criterion_group, criterion_main};
26+
use datafusion_expr_common::accumulator::Accumulator;
27+
use datafusion_expr_common::groups_accumulator::GroupsAccumulator;
28+
use datafusion_functions_aggregate_common::aggregate::groups_accumulator::GroupsAccumulatorAdapter;
29+
use datafusion_functions_aggregate_common::min_max::MaxAccumulator;
30+
31+
const NUM_GROUPS: usize = 8_192;
32+
33+
fn groups_accumulator_adapter(c: &mut Criterion) {
34+
let values: ArrayRef = Arc::new(Int64Array::from_iter_values(0..NUM_GROUPS as i64));
35+
let group_indices: Vec<_> = (0..NUM_GROUPS).collect();
36+
37+
c.bench_function("groups_accumulator_adapter/update_batch/8192_groups", |b| {
38+
b.iter_batched(
39+
|| {
40+
GroupsAccumulatorAdapter::new(|| {
41+
Ok(Box::new(MaxAccumulator::try_new(&DataType::Int64)?)
42+
as Box<dyn Accumulator>)
43+
})
44+
},
45+
|mut accumulator| {
46+
accumulator
47+
.update_batch(
48+
&[Arc::clone(&values)],
49+
&group_indices,
50+
None,
51+
NUM_GROUPS,
52+
)
53+
.unwrap();
54+
black_box(accumulator);
55+
},
56+
BatchSize::SmallInput,
57+
);
58+
});
59+
}
60+
61+
criterion_group!(benches, groups_accumulator_adapter);
62+
criterion_main!(benches);

0 commit comments

Comments
 (0)