Apache DataFusion SQL Query Engine
Refine and document AggregateExec metrics (#24757)
kosiew8a9228164fdd
diff --git a/datafusion/core/tests/sql/explain_analyze.rs b/datafusion/core/tests/sql/explain_analyze.rsindex f8498cbedf..2ca04ad6b3 100644--- a/datafusion/core/tests/sql/explain_analyze.rs+++ b/datafusion/core/tests/sql/explain_analyze.rs@@ -1064,6 +1064,47 @@ async fn csv_explain_analyze_verbose() {assert_contains!(formatted, verbose_needle);}+#[tokio::test]+#[cfg_attr(coverage, ignore)]+async fn explain_analyze_aggregate_metrics_map_indices_to_expressions() {+ let ctx =+ SessionContext::new_with_config(SessionConfig::new().with_target_partitions(1));+ register_aggregate_csv_by_sql(&ctx).await;++ let query =+ "SELECT c1, SUM(c5), SUM(c6), COUNT(c7) FROM aggregate_test_100 GROUP BY c1";+ let normal = execute_to_batches(&ctx, &format!("EXPLAIN ANALYZE {query}")).await;+ let normal = arrow::util::pretty::pretty_format_batches(&normal)+ .unwrap()+ .to_string();+ assert_contains!(+ normal.as_str(),+ "aggr=[sum(aggregate_test_100.c5), sum(aggregate_test_100.c6), count(aggregate_test_100.c7)]"+ );+ assert_contains!(normal.as_str(), "agg_expr_0_arguments_time");+ assert_contains!(normal.as_str(), "agg_expr_1_arguments_time");+ assert_contains!(normal.as_str(), "agg_expr_2_arguments_time");+ assert!(!normal.contains("aggregate="));++ let verbose =+ execute_to_batches(&ctx, &format!("EXPLAIN ANALYZE VERBOSE {query}")).await;+ let verbose = arrow::util::pretty::pretty_format_batches(&verbose)+ .unwrap()+ .to_string();+ assert_contains!(+ verbose.as_str(),+ "agg_expr_0_arguments_time{partition=0, aggregate=sum(aggregate_test_100.c5)}"+ );+ assert_contains!(+ verbose.as_str(),+ "agg_expr_1_arguments_time{partition=0, aggregate=sum(aggregate_test_100.c6)}"+ );+ assert_contains!(+ verbose.as_str(),+ "agg_expr_2_arguments_time{partition=0, aggregate=count(aggregate_test_100.c7)}"+ );+}+#[tokio::test]async fn explain_logical_plan_only() {let mut config = ConfigOptions::new();diff --git a/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common.rs b/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common.rsindex 0c481a6b3b..75468198f5 100644--- a/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common.rs+++ b/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common.rs@@ -173,24 +173,23 @@ impl<AggrMode> AggregateHashTable<AggrMode> {batch: &RecordBatch,) -> Result<EvaluatedAggregateBatch> {let state = self.state.building();- let timer = self.group_by_metrics.time_calculating_group_ids.timer();- // outer vec: one per each grouping set- // inner vec: all group by exprs for the current grouping set- let grouping_set_args = evaluate_group_by(&state.group_by, batch)?;- drop(timer);-- let timer = self.group_by_metrics.aggregate_arguments_time.timer();- // The evaluated args for each accumulator- let accumulator_args = state- .accumulators- .iter()- .enumerate()- .map(|(idx, acc)| {- self.aggregate_argument_metrics- .time(idx, || acc.evaluate_acc_args(batch))- })- .collect::<Result<Vec<_>>>()?;- drop(timer);+ // Outer vec: one per grouping set; inner vec: group-by expressions.+ let grouping_set_args = self+ .group_by_metrics+ .time_group_key_preparation(|| evaluate_group_by(&state.group_by, batch))?;++ // The evaluated args for each accumulator.+ let accumulator_args = self.group_by_metrics.time_aggregate_arguments(|| {+ state+ .accumulators+ .iter()+ .enumerate()+ .map(|(idx, acc)| {+ self.aggregate_argument_metrics+ .time(idx, || acc.evaluate_acc_args(batch))+ })+ .collect::<Result<Vec<_>>>()+ })?;Ok(EvaluatedAggregateBatch {grouping_set_args,@@ -212,26 +211,31 @@ impl<AggrMode> AggregateHashTable<AggrMode> {) -> Result<()> {let evaluated_batch = self.evaluate_batch(batch)?;let accumulator_metrics = Arc::clone(&self.aggregate_accumulator_metrics);+ let group_by_metrics = self.group_by_metrics.clone();let state = self.state.building_mut();- let _timer = self.group_by_metrics.aggregation_time.timer();for group_values in &evaluated_batch.grouping_set_args {- state- .group_values- .intern(group_values, &mut state.batch_group_indices)?;+ group_by_metrics.time_group_key_preparation(|| {+ state+ .group_values+ .intern(group_values, &mut state.batch_group_indices)+ })?;+let group_indices = &state.batch_group_indices;let total_num_groups = state.group_values.len();-- for (idx, (acc, values)) in state- .accumulators- .iter_mut()- .zip(evaluated_batch.accumulator_args.iter())- .enumerate()- {- accumulator_metrics.time(idx, accumulator_phase, || {- aggregate_fn(acc, values, group_indices, total_num_groups)- })?;- }+ group_by_metrics.time_aggregation(|| {+ for (idx, (acc, values)) in state+ .accumulators+ .iter_mut()+ .zip(evaluated_batch.accumulator_args.iter())+ .enumerate()+ {+ accumulator_metrics.time(idx, accumulator_phase, || {+ aggregate_fn(acc, values, group_indices, total_num_groups)+ })?;+ }+ Ok::<(), datafusion_common::DataFusionError>(())+ })?;}Ok(())@@ -265,16 +269,17 @@ impl<AggrMode> AggregateHashTable<AggrMode> {// Accumulator output consumes internal state. Materialize all// groups once, then slice the materialized batch on later polls.let emit_to = EmitTo::All;- let timer = self.group_by_metrics.emitting_time.timer();- let mut columns = state.group_values.emit(emit_to)?;- for (idx, acc) in state.accumulators.iter_mut().enumerate() {- columns.extend(accumulator_metrics.time(- idx,- accumulator_phase,- || materialize_accumulator_fn(acc, emit_to),- )?);- }- drop(timer);+ let columns = self.group_by_metrics.time_emitting(|| {+ let mut columns = state.group_values.emit(emit_to)?;+ for (idx, acc) in state.accumulators.iter_mut().enumerate() {+ columns.extend(accumulator_metrics.time(+ idx,+ accumulator_phase,+ || materialize_accumulator_fn(acc, emit_to),+ )?);+ }+ Ok::<_, datafusion_common::DataFusionError>(columns)+ })?;let batch = RecordBatch::try_new(output_schema, columns)?;debug_assert!(batch.num_rows() > 0);@@ -334,19 +339,23 @@ impl<AggrMode> AggregateHashTable<AggrMode> {) -> Result<Option<RecordBatch>> {let state_schema = Arc::clone(&self.state_schema);let accumulator_metrics = Arc::clone(&self.aggregate_accumulator_metrics);+ let group_by_metrics = self.group_by_metrics.clone();let state = self.state.building_mut();if state.group_values.is_empty() {return Ok(None);}- let mut output = state.group_values.emit(EmitTo::All)?;- for (idx, acc) in state.accumulators.iter_mut().enumerate() {- output.extend(accumulator_metrics.time(- idx,- AccumulatorPhase::State,- || acc.state(EmitTo::All),- )?);- }+ let output = group_by_metrics.time_emitting(|| {+ let mut output = state.group_values.emit(EmitTo::All)?;+ for (idx, acc) in state.accumulators.iter_mut().enumerate() {+ output.extend(accumulator_metrics.time(+ idx,+ AccumulatorPhase::State,+ || acc.state(EmitTo::All),+ )?);+ }+ Ok::<_, datafusion_common::DataFusionError>(output)+ })?;let batch = RecordBatch::try_new(state_schema, output)?;debug_assert!(batch.num_rows() > 0);@@ -401,57 +410,71 @@ impl<AggrMode> AggregateHashTable<AggrMode> {/// already expanded keys as plain group columns (see/// [`PhysicalGroupBy::as_final`]) and never own a grouping set.pub(super) fn init_empty_grouping_sets(&mut self) -> Result<()> {+ let group_by_metrics = self.group_by_metrics.clone();let state = self.state.building_mut();if !state.group_by.has_grouping_set() || !state.group_values.is_empty() {return Ok(());}let accumulator_metrics = Arc::clone(&self.aggregate_accumulator_metrics);- let max_ordinal = max_duplicate_ordinal(state.group_by.groups());- let mut ordinals: HashMap<&[bool], usize> = HashMap::new();- let group_schema = state.group_by.group_schema(&self.input_schema)?;- let n_expr = state.group_by.expr().len();- let mut any_interned = false;-- for group in state.group_by.groups() {- let ordinal = {- let entry = ordinals.entry(group.as_slice()).or_insert(0);- let ordinal = *entry;- *entry += 1;- ordinal- };-- if !group.iter().all(|&is_null| is_null) {- continue;- }+ let any_interned = group_by_metrics.time_group_key_preparation(|| {+ let max_ordinal = max_duplicate_ordinal(state.group_by.groups());+ let mut ordinals: HashMap<&[bool], usize> = HashMap::new();+ let group_schema = state.group_by.group_schema(&self.input_schema)?;+ let n_expr = state.group_by.expr().len();+ let mut any_interned = false;++ for group in state.group_by.groups() {+ let ordinal = {+ let entry = ordinals.entry(group.as_slice()).or_insert(0);+ let ordinal = *entry;+ *entry += 1;+ ordinal+ };- let mut cols: Vec<ArrayRef> = group_schema- .fields()- .iter()- .take(n_expr)- .map(|field| new_null_array(field.data_type(), 1))- .collect();- cols.push(group_id_array(group, ordinal, max_ordinal, 1)?);+ if !group.iter().all(|&is_null| is_null) {+ continue;+ }- state- .group_values- .intern(&cols, &mut state.batch_group_indices)?;- any_interned = true;- }+ let mut cols: Vec<ArrayRef> = group_schema+ .fields()+ .iter()+ .take(n_expr)+ .map(|field| new_null_array(field.data_type(), 1))+ .collect();+ cols.push(group_id_array(group, ordinal, max_ordinal, 1)?);++ state+ .group_values+ .intern(&cols, &mut state.batch_group_indices)?;+ any_interned = true;+ }+ Ok::<_, datafusion_common::DataFusionError>(any_interned)+ })?;if any_interned {let total_groups = state.group_values.len();let false_filter = BooleanArray::from(vec![false]);- for (idx, acc) in state.accumulators.iter_mut().enumerate() {- let null_args = acc.null_arguments(&self.input_schema)?;- let values = EvaluatedAccumulatorArgs {- arguments: null_args,- filter: Some(Arc::new(false_filter.clone())),- };- accumulator_metrics.time(idx, AccumulatorPhase::Update, || {- acc.update_batch(&values, &[0], total_groups)- })?;- }+ let values = state+ .accumulators+ .iter()+ .map(|acc| {+ Ok(EvaluatedAccumulatorArgs {+ arguments: acc.null_arguments(&self.input_schema)?,+ filter: Some(Arc::new(false_filter.clone())),+ })+ })+ .collect::<Result<Vec<_>>>()?;+ group_by_metrics.time_aggregation(|| {+ for (idx, (acc, values)) in+ state.accumulators.iter_mut().zip(values.iter()).enumerate()+ {+ accumulator_metrics.time(idx, AccumulatorPhase::Update, || {+ acc.update_batch(values, &[0], total_groups)+ })?;+ }+ Ok::<(), datafusion_common::DataFusionError>(())+ })?;}Ok(())diff --git a/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common_ordered.rs b/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common_ordered.rsindex 4ced967a09..418f3f376b 100644--- a/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common_ordered.rs+++ b/datafusion/physical-plan/src/aggregates/aggregate_hash_table/common_ordered.rs@@ -244,22 +244,22 @@ impl<AggrMode> OrderedAggregateTable<AggrMode> {&self,batch: &RecordBatch,) -> Result<EvaluatedAggregateBatch> {- let timer = self.group_by_metrics.time_calculating_group_ids.timer();- let grouping_set_args = evaluate_group_by(&self.buffer.group_by, batch)?;- drop(timer);+ let grouping_set_args =+ self.group_by_metrics.time_group_key_preparation(|| {+ evaluate_group_by(&self.buffer.group_by, batch)+ })?;- let timer = self.group_by_metrics.aggregate_arguments_time.timer();- let accumulator_args = self- .buffer- .accumulators- .iter()- .enumerate()- .map(|(idx, acc)| {- self.aggregate_argument_metrics- .time(idx, || acc.evaluate_acc_args(batch))- })- .collect::<Result<Vec<_>>>()?;- drop(timer);+ let accumulator_args = self.group_by_metrics.time_aggregate_arguments(|| {+ self.buffer+ .accumulators+ .iter()+ .enumerate()+ .map(|(idx, acc)| {+ self.aggregate_argument_metrics+ .time(idx, || acc.evaluate_acc_args(batch))+ })+ .collect::<Result<Vec<_>>>()+ })?;Ok(EvaluatedAggregateBatch {grouping_set_args,@@ -326,14 +326,17 @@ impl<AggrMode> OrderedAggregateTable<AggrMode> {}let accumulator_metrics = Arc::clone(&self.aggregate_accumulator_metrics);- let mut output = self.buffer.group_values.emit(EmitTo::All)?;- for (idx, acc) in self.buffer.accumulators.iter_mut().enumerate() {- output.extend(accumulator_metrics.time(- idx,- AccumulatorPhase::State,- || acc.state(EmitTo::All),- )?);- }+ let output = self.group_by_metrics.time_emitting(|| {+ let mut output = self.buffer.group_values.emit(EmitTo::All)?;+ for (idx, acc) in self.buffer.accumulators.iter_mut().enumerate() {+ output.extend(accumulator_metrics.time(+ idx,+ AccumulatorPhase::State,+ || acc.state(EmitTo::All),+ )?);+ }+ Ok::<_, datafusion_common::DataFusionError>(output)+ })?;let batch = RecordBatch::try_new(Arc::clone(&self.state_schema), output)?;debug_assert!(batch.num_rows() > 0);@@ -381,38 +384,43 @@ impl<AggrMode> OrderedAggregateTable<AggrMode> {accumulator_phase: AccumulatorPhase,) -> Result<()> {let accumulator_metrics = Arc::clone(&self.aggregate_accumulator_metrics);+ let group_by_metrics = self.group_by_metrics.clone();for group_values in &evaluated_batch.grouping_set_args {- let starting_num_groups = self.buffer.group_values.len();- self.buffer- .group_values- .intern(group_values, &mut self.buffer.group_indices)?;- let total_num_groups = self.buffer.group_values.len();- if total_num_groups > starting_num_groups {- self.buffer.group_ordering.new_groups(- group_values,- &self.buffer.group_indices,- total_num_groups,- )?;- }-- let timer = self.group_by_metrics.aggregation_time.timer();- for (idx, (acc, values)) in self- .buffer- .accumulators- .iter_mut()- .zip(evaluated_batch.accumulator_args.iter())- .enumerate()- {- accumulator_metrics.time(idx, accumulator_phase, || {- aggregate_fn(- acc,- values,+ let total_num_groups = group_by_metrics.time_group_key_preparation(|| {+ let starting_num_groups = self.buffer.group_values.len();+ self.buffer+ .group_values+ .intern(group_values, &mut self.buffer.group_indices)?;+ let total_num_groups = self.buffer.group_values.len();+ if total_num_groups > starting_num_groups {+ self.buffer.group_ordering.new_groups(+ group_values,&self.buffer.group_indices,total_num_groups,- )- })?;- }- drop(timer);+ )?;+ }+ Ok::<_, datafusion_common::DataFusionError>(total_num_groups)+ })?;++ group_by_metrics.time_aggregation(|| {+ for (idx, (acc, values)) in self+ .buffer+ .accumulators+ .iter_mut()+ .zip(evaluated_batch.accumulator_args.iter())+ .enumerate()+ {+ accumulator_metrics.time(idx, accumulator_phase, || {+ aggregate_fn(+ acc,+ values,+ &self.buffer.group_indices,+ total_num_groups,+ )+ })?;+ }+ Ok::<(), datafusion_common::DataFusionError>(())+ })?;}Ok(())@@ -441,24 +449,27 @@ impl<AggrMode> OrderedAggregateTable<AggrMode> {self.clamp_emit_to(self.buffer.group_values.len(), emit_to);let accumulator_metrics = Arc::clone(&self.aggregate_accumulator_metrics);- let timer = self.group_by_metrics.emitting_time.timer();- let mut output = self.buffer.group_values.emit(emit_to)?;- if should_remove_groups {- match emit_to {- EmitTo::First(n) => self.buffer.group_ordering.remove_groups(n),- // `EmitTo::All` is only used after `input_done`, when all- // buffered groups are known complete and the ordering state is- // no longer needed.- EmitTo::All => {}+ let output = self.group_by_metrics.time_emitting(|| {+ let mut output = self.buffer.group_values.emit(emit_to)?;+ if should_remove_groups {+ match emit_to {+ EmitTo::First(n) => self.buffer.group_ordering.remove_groups(n),+ // `EmitTo::All` is only used after `input_done`, when all+ // buffered groups are known complete and the ordering state is+ // no longer needed.+ EmitTo::All => {}+ }}- }- for (idx, acc) in self.buffer.accumulators.iter_mut().enumerate() {- output.extend(accumulator_metrics.time(idx, accumulator_phase, || {- materialize_accumulator_fn(acc, emit_to)- })?);- }- drop(timer);+ for (idx, acc) in self.buffer.accumulators.iter_mut().enumerate() {+ output.extend(accumulator_metrics.time(+ idx,+ accumulator_phase,+ || materialize_accumulator_fn(acc, emit_to),+ )?);+ }+ Ok::<_, datafusion_common::DataFusionError>(output)+ })?;let batch = RecordBatch::try_new(Arc::clone(&self.output_schema), output)?;debug_assert!(batch.num_rows() > 0);diff --git a/datafusion/physical-plan/src/aggregates/aggregate_stream.rs b/datafusion/physical-plan/src/aggregates/aggregate_stream.rsindex a3fc731cb8..23f74e6352 100644--- a/datafusion/physical-plan/src/aggregates/aggregate_stream.rs+++ b/datafusion/physical-plan/src/aggregates/aggregate_stream.rs@@ -701,6 +701,7 @@ mod tests {}assert!(aggregate_metrics(&metrics, "merge").is_empty());assert!(aggregate_metrics(&metrics, "state").is_empty());+ assert!(metrics.sum_by_name("emitting_time").is_none());Ok(())}diff --git a/datafusion/physical-plan/src/aggregates/group_values/metrics.rs b/datafusion/physical-plan/src/aggregates/group_values/metrics.rsindex 4b5bfd1725..d6405bb403 100644--- a/datafusion/physical-plan/src/aggregates/group_values/metrics.rs+++ b/datafusion/physical-plan/src/aggregates/group_values/metrics.rs@@ -143,38 +143,87 @@ impl AggregateAccumulatorMetrics {#[derive(Clone)]pub(crate) struct GroupByMetrics {- /// Time spent calculating the group IDs from the evaluated grouping columns.- pub(crate) time_calculating_group_ids: Time,- /// Time spent evaluating the inputs to the aggregate functions.- pub(crate) aggregate_arguments_time: Time,- /// Time spent evaluating the aggregate expressions themselves- /// (e.g. summing all elements and counting number of elements for `avg` aggregate).- pub(crate) aggregation_time: Time,- /// Time spent emitting the final results and constructing the record batch- /// which includes finalizing the grouping expressions- /// (e.g. emit from the hash table in case of hash aggregation) and the accumulators- pub(crate) emitting_time: Time,+ /// Group-key preparation: grouping-expression evaluation, interning, and ordering updates.+ time_calculating_group_ids: Time,+ /// Aggregate-input evaluation, including collectively evaluated filters.+ aggregate_arguments_time: Time,+ /// Input-processing accumulator operations (`update` and `merge`).+ aggregation_time: Option<Time>,+ /// Output emission: group values and accumulator states or final values.+ emitting_time: Time,+ /// Grouped TopK priority-map batch setup, insertion, comparison, and NULL handling.+ topk_maintenance_time: Option<Time>,}impl GroupByMetrics {pub(crate) fn new(metrics: &ExecutionPlanMetricsSet, partition: usize) -> Self {+ Self::new_with_options(metrics, partition, true, false)+ }++ /// Creates metrics for Grouped TopK, which does not invoke accumulators.+ pub(crate) fn new_topk(metrics: &ExecutionPlanMetricsSet, partition: usize) -> Self {+ Self::new_with_options(metrics, partition, false, true)+ }++ fn new_with_options(+ metrics: &ExecutionPlanMetricsSet,+ partition: usize,+ include_aggregation_time: bool,+ include_topk_maintenance_time: bool,+ ) -> Self {Self {time_calculating_group_ids: MetricBuilder::new(metrics).subset_time("time_calculating_group_ids", partition),aggregate_arguments_time: MetricBuilder::new(metrics).subset_time("aggregate_arguments_time", partition),- aggregation_time: MetricBuilder::new(metrics)- .subset_time("aggregation_time", partition),+ aggregation_time: include_aggregation_time.then(|| {+ MetricBuilder::new(metrics).subset_time("aggregation_time", partition)+ }),emitting_time: MetricBuilder::new(metrics).subset_time("emitting_time", partition),+ topk_maintenance_time: include_topk_maintenance_time.then(|| {+ MetricBuilder::new(metrics)+ .subset_time("topk_maintenance_time", partition)+ }),}}++ /// Times grouping-expression evaluation, group interning, and ordering updates.+ pub(crate) fn time_group_key_preparation<R>(&self, f: impl FnOnce() -> R) -> R {+ let _timer = self.time_calculating_group_ids.timer();+ f()+ }++ /// Times aggregate argument and collectively evaluated filter expressions.+ pub(crate) fn time_aggregate_arguments<R>(&self, f: impl FnOnce() -> R) -> R {+ let _timer = self.aggregate_arguments_time.timer();+ f()+ }++ /// Times one interval containing all input-processing accumulator operations.+ pub(crate) fn time_aggregation<R>(&self, f: impl FnOnce() -> R) -> R {+ let _timer = self.aggregation_time.as_ref().map(Time::timer);+ f()+ }++ /// Times group-value and accumulator-state/final-value output emission.+ pub(crate) fn time_emitting<R>(&self, f: impl FnOnce() -> R) -> R {+ let _timer = self.emitting_time.timer();+ f()+ }++ /// Times Grouped TopK priority-map maintenance after group keys are prepared.+ pub(crate) fn time_topk_maintenance<R>(&self, f: impl FnOnce() -> R) -> R {+ let _timer = self.topk_maintenance_time.as_ref().map(Time::timer);+ f()+ }}#[cfg(test)]mod tests {+ use super::GroupByMetrics;use crate::aggregates::{AggregateExec, AggregateMode, PhysicalGroupBy};- use crate::metrics::{MetricValue, MetricsSet};+ use crate::metrics::{ExecutionPlanMetricsSet, MetricValue, MetricsSet};use crate::test::TestMemoryExec;use crate::{ExecutionPlan, collect};use arrow::array::{Float64Array, UInt32Array};@@ -207,6 +256,23 @@ mod tests {assert!(emitting_time.unwrap().as_usize() > 0);}+ #[test]+ fn groupby_metrics_without_accumulators_do_not_register_aggregation_time() {+ let metrics = ExecutionPlanMetricsSet::new();+ let groupby_metrics = GroupByMetrics::new_topk(&metrics, 0);+ let mut called = false;++ groupby_metrics.time_aggregation(|| called = true);++ assert!(called);+ assert!(+ metrics+ .clone_inner()+ .sum_by_name("aggregation_time")+ .is_none()+ );+ }+fn aggregate_metric_names_and_labels(metrics: &MetricsSet,suffix: &str,diff --git a/datafusion/physical-plan/src/aggregates/grouped_hash_stream.rs b/datafusion/physical-plan/src/aggregates/grouped_hash_stream.rsindex 3f6f3f8ce8..24bb4c16d8 100644--- a/datafusion/physical-plan/src/aggregates/grouped_hash_stream.rs+++ b/datafusion/physical-plan/src/aggregates/grouped_hash_stream.rs@@ -59,7 +59,6 @@ use datafusion_physical_expr_common::sort_expr::LexOrdering;use datafusion_physical_expr_common::utils::evaluate_expressions_to_arrays;use crate::sorts::IncrementalSortIterator;-use datafusion_common::instant::Instant;use datafusion_common::utils::memory::get_record_batch_memory_size;use futures::ready;use futures::stream::{Stream, StreamExt};@@ -869,120 +868,109 @@ impl RecordBatchStream for GroupedHashAggregateStream {impl GroupedHashAggregateStream {/// Perform group-by aggregation for the given [`RecordBatch`].fn group_aggregate_batch(&mut self, batch: &RecordBatch) -> Result<()> {- // Evaluate the grouping expressions- let group_by_values = if self.spill_state.is_stream_merging {- evaluate_group_by(&self.spill_state.merging_group_by, batch)?- } else {- evaluate_group_by(&self.group_by, batch)?- };+ let is_stream_merging = self.spill_state.is_stream_merging;- // Only create the timer if there are actual aggregate arguments to evaluate- let timer = match (- self.spill_state.is_stream_merging,- self.spill_state.merging_aggregate_arguments.is_empty(),- self.aggregate_arguments.is_empty(),- ) {- (true, false, _) | (false, _, false) => {- Some(self.group_by_metrics.aggregate_arguments_time.timer())+ // Evaluate the grouping expressions; interning happens below in the+ // same group-key-preparation phase.+ let group_by_values = self.group_by_metrics.time_group_key_preparation(|| {+ if is_stream_merging {+ evaluate_group_by(&self.spill_state.merging_group_by, batch)+ } else {+ evaluate_group_by(&self.group_by, batch)}- _ => None,- };+ })?;- // Evaluate the aggregation expressions.- let aggregate_arguments = if self.spill_state.is_stream_merging {+ // Evaluate aggregate arguments and filters together. Per-aggregate+ // argument timers remain limited to their argument expressions because+ // filters are evaluated collectively here.+ let aggregate_arguments = if is_stream_merging {&self.spill_state.merging_aggregate_arguments} else {&self.aggregate_arguments};- let input_values = aggregate_arguments- .iter()- .enumerate()- .map(|(idx, expr)| {- self.aggregate_argument_metrics- .time(idx, || evaluate_expressions_to_arrays(expr, batch))- })- .collect::<Result<Vec<_>>>()?;- drop(timer);-- // Evaluate the filter expressions, if any, against the inputs- let filter_values = if self.spill_state.is_stream_merging {- let filter_expressions = vec![None; self.accumulators.len()];- evaluate_optional(&filter_expressions, batch)?- } else {- evaluate_optional(&self.filter_expressions, batch)?- };+ let (input_values, filter_values) =+ self.group_by_metrics.time_aggregate_arguments(|| {+ let input_values = aggregate_arguments+ .iter()+ .enumerate()+ .map(|(idx, expr)| {+ self.aggregate_argument_metrics+ .time(idx, || evaluate_expressions_to_arrays(expr, batch))+ })+ .collect::<Result<Vec<_>>>()?;+ let filter_values = if is_stream_merging {+ let filter_expressions = vec![None; self.accumulators.len()];+ evaluate_optional(&filter_expressions, batch)?+ } else {+ evaluate_optional(&self.filter_expressions, batch)?+ };+ Ok::<_, DataFusionError>((input_values, filter_values))+ })?;for group_values in &group_by_values {- let groups_start_time = Instant::now();-- // calculate the group indices for each input row- let starting_num_groups = self.group_values.len();- self.group_values- .intern(group_values, &mut self.current_group_indices)?;- let group_indices = &self.current_group_indices;-- // Update ordering information if necessary- let total_num_groups = self.group_values.len();- if total_num_groups > starting_num_groups {- self.group_ordering.new_groups(- group_values,- group_indices,- total_num_groups,- )?;- }-- // Use this instant for both measurements to save a syscall- let agg_start_time = Instant::now();- self.group_by_metrics- .time_calculating_group_ids- .add_duration(agg_start_time - groups_start_time);-- // Gather the inputs to call the actual accumulator- let t = self- .accumulators- .iter_mut()- .zip(input_values.iter())- .zip(filter_values.iter());-- for (idx, ((acc, values), opt_filter)) in t.enumerate() {- let opt_filter = opt_filter.as_ref().map(|filter| filter.as_boolean());-- // Call the appropriate method on each aggregator with- // the entire input row and the relevant group indexes- if self.mode.input_mode() == AggregateInputMode::Raw- && !self.spill_state.is_stream_merging- {- self.aggregate_accumulator_metrics.time(- idx,- AccumulatorPhase::Update,- || {- acc.update_batch(- values,- group_indices,- opt_filter,- total_num_groups,- )- },- )?;- } else {- assert_or_internal_err!(- opt_filter.is_none(),- "aggregate filter should be applied in partial stage, there should be no filter in final stage"- );+ // Calculate group indices and update ordering information.+ let total_num_groups =+ self.group_by_metrics.time_group_key_preparation(|| {+ let starting_num_groups = self.group_values.len();+ self.group_values+ .intern(group_values, &mut self.current_group_indices)?;+ let group_indices = &self.current_group_indices;+ let total_num_groups = self.group_values.len();+ if total_num_groups > starting_num_groups {+ self.group_ordering.new_groups(+ group_values,+ group_indices,+ total_num_groups,+ )?;+ }+ Ok::<_, DataFusionError>(total_num_groups)+ })?;- // if aggregation is over intermediate states,- // use merge- self.aggregate_accumulator_metrics.time(- idx,- AccumulatorPhase::Merge,- || acc.merge_batch(values, group_indices, total_num_groups),- )?;+ // Convert filters before timing accumulator calls. The timer covers+ // one interval across all accumulator operations, rather than a+ // prefix sum charged once per aggregate expression.+ let filters = filter_values+ .iter()+ .map(|filter| filter.as_ref().map(|filter| filter.as_boolean()))+ .collect::<Vec<_>>();+ self.group_by_metrics.time_aggregation(|| {+ let group_indices = &self.current_group_indices;+ let t = self+ .accumulators+ .iter_mut()+ .zip(input_values.iter())+ .zip(filters.iter());++ for (idx, ((acc, values), opt_filter)) in t.enumerate() {+ if self.mode.input_mode() == AggregateInputMode::Raw && !is_stream_merging+ {+ self.aggregate_accumulator_metrics.time(+ idx,+ AccumulatorPhase::Update,+ || {+ acc.update_batch(+ values,+ group_indices,+ *opt_filter,+ total_num_groups,+ )+ },+ )?;+ } else {+ assert_or_internal_err!(+ opt_filter.is_none(),+ "aggregate filter should be applied in partial stage, there should be no filter in final stage"+ );++ self.aggregate_accumulator_metrics.time(+ idx,+ AccumulatorPhase::Merge,+ || acc.merge_batch(values, group_indices, total_num_groups),+ )?;+ }}- }- // Recorded once per grouping set, after all its accumulators ran- self.group_by_metrics- .aggregation_time- .add_elapsed(agg_start_time);+ Ok::<(), DataFusionError>(())+ })?;}Ok(())@@ -1077,31 +1065,31 @@ impl GroupedHashAggregateStream {return Ok(None);}- let timer = self.group_by_metrics.emitting_time.timer();- let mut output = self.group_values.emit(emit_to)?;- if let EmitTo::First(n) = emit_to {- self.group_ordering.remove_groups(n);- }+ let group_by_metrics = self.group_by_metrics.clone();+ let output = group_by_metrics.time_emitting(|| {+ let mut output = self.group_values.emit(emit_to)?;+ if let EmitTo::First(n) = emit_to {+ self.group_ordering.remove_groups(n);+ }- // Next output each aggregate value- for (idx, acc) in self.accumulators.iter_mut().enumerate() {- if self.mode.output_mode() == AggregateOutputMode::Final && !spilling {- output.push(self.aggregate_accumulator_metrics.time(- idx,- AccumulatorPhase::Evaluate,- || acc.evaluate(emit_to),- )?)- } else {- // Output partial state: either because we're in a non-final mode,- // or because we're spilling and will merge/re-evaluate later.- output.extend(self.aggregate_accumulator_metrics.time(- idx,- AccumulatorPhase::State,- || acc.state(emit_to),- )?)+ // Next output each aggregate value.+ for (idx, acc) in self.accumulators.iter_mut().enumerate() {+ if self.mode.output_mode() == AggregateOutputMode::Final && !spilling {+ output.push(self.aggregate_accumulator_metrics.time(+ idx,+ AccumulatorPhase::Evaluate,+ || acc.evaluate(emit_to),+ )?)+ } else {+ output.extend(self.aggregate_accumulator_metrics.time(+ idx,+ AccumulatorPhase::State,+ || acc.state(emit_to),+ )?)+ }}- }- drop(timer);+ Ok::<_, DataFusionError>(output)+ })?;// emit reduces the memory usage. Ignore Err from update_memory_reservation. Even if it is// over the target memory size after emission, we can emit again rather than returning Err.@@ -1127,47 +1115,50 @@ impl GroupedHashAggregateStream {return Ok(());}- let max_ordinal = max_duplicate_ordinal(self.group_by.groups());- let mut ordinals: std::collections::HashMap<&[bool], usize> =- std::collections::HashMap::new();- let group_schema = self.group_by.group_schema(&self.input_schema)?;- let n_expr = self.group_by.expr().len();- let mut any_interned = false;-- for group in self.group_by.groups() {- let ordinal = {- let entry = ordinals.entry(group.as_slice()).or_insert(0);- let o = *entry;- *entry += 1;- o- };+ let group_by_metrics = self.group_by_metrics.clone();+ let any_interned = group_by_metrics.time_group_key_preparation(|| {+ let max_ordinal = max_duplicate_ordinal(self.group_by.groups());+ let mut ordinals: std::collections::HashMap<&[bool], usize> =+ std::collections::HashMap::new();+ let group_schema = self.group_by.group_schema(&self.input_schema)?;+ let n_expr = self.group_by.expr().len();+ let mut any_interned = false;++ for group in self.group_by.groups() {+ let ordinal = {+ let entry = ordinals.entry(group.as_slice()).or_insert(0);+ let o = *entry;+ *entry += 1;+ o+ };- if !group.iter().all(|&is_null| is_null) {- continue;- }+ if !group.iter().all(|&is_null| is_null) {+ continue;+ }- // Build the group key: one NULL per group-by expression, then the grouping_id.- let mut cols: Vec<ArrayRef> = group_schema- .fields()- .iter()- .take(n_expr)- .map(|f| new_null_array(f.data_type(), 1))- .collect();- cols.push(group_id_array(group, ordinal, max_ordinal, 1)?);-- let starting_groups = self.group_values.len();- self.group_values- .intern(&cols, &mut self.current_group_indices)?;- let total_groups = self.group_values.len();- if total_groups > starting_groups {- self.group_ordering.new_groups(- &cols,- &self.current_group_indices,- total_groups,- )?;+ let mut cols: Vec<ArrayRef> = group_schema+ .fields()+ .iter()+ .take(n_expr)+ .map(|f| new_null_array(f.data_type(), 1))+ .collect();+ cols.push(group_id_array(group, ordinal, max_ordinal, 1)?);++ let starting_groups = self.group_values.len();+ self.group_values+ .intern(&cols, &mut self.current_group_indices)?;+ let total_groups = self.group_values.len();+ if total_groups > starting_groups {+ self.group_ordering.new_groups(+ &cols,+ &self.current_group_indices,+ total_groups,+ )?;+ }+ any_interned = true;}- any_interned = true;- }+ Ok::<_, DataFusionError>(any_interned)+ })?;if any_interned {// Prime each accumulator for the registered group count with no data.@@ -1212,18 +1203,28 @@ impl GroupedHashAggregateStream {}).collect::<Result<Vec<_>>>()?;let false_filter = BooleanArray::from(vec![false]);- for (idx, (acc, args)) in self- .accumulators- .iter_mut()- .zip(null_args.iter())- .enumerate()- {- self.aggregate_accumulator_metrics.time(- idx,- AccumulatorPhase::Update,- || acc.update_batch(args, &[0], Some(&false_filter), total_groups),- )?;- }+ group_by_metrics.time_aggregation(|| {+ for (idx, (acc, args)) in self+ .accumulators+ .iter_mut()+ .zip(null_args.iter())+ .enumerate()+ {+ self.aggregate_accumulator_metrics.time(+ idx,+ AccumulatorPhase::Update,+ || {+ acc.update_batch(+ args,+ &[0],+ Some(&false_filter),+ total_groups,+ )+ },+ )?;+ }+ Ok::<(), DataFusionError>(())+ })?;}Ok(())@@ -1435,19 +1436,24 @@ impl GroupedHashAggregateStream {/// Transforms input batch to intermediate aggregate state, without grouping itfn transform_to_states(&self, batch: &RecordBatch) -> Result<RecordBatch> {- let mut group_values = evaluate_group_by(&self.group_by, batch)?;- let timer = self.group_by_metrics.aggregate_arguments_time.timer();- let input_values = self- .aggregate_arguments- .iter()- .enumerate()- .map(|(idx, expr)| {- self.aggregate_argument_metrics- .time(idx, || evaluate_expressions_to_arrays(expr, batch))- })- .collect::<Result<Vec<_>>>()?;- drop(timer);- let filter_values = evaluate_optional(&self.filter_expressions, batch)?;+ let mut group_values = self+ .group_by_metrics+ .time_group_key_preparation(|| evaluate_group_by(&self.group_by, batch))?;++ let (input_values, filter_values) =+ self.group_by_metrics.time_aggregate_arguments(|| {+ let input_values = self+ .aggregate_arguments+ .iter()+ .enumerate()+ .map(|(idx, expr)| {+ self.aggregate_argument_metrics+ .time(idx, || evaluate_expressions_to_arrays(expr, batch))+ })+ .collect::<Result<Vec<_>>>()?;+ let filter_values = evaluate_optional(&self.filter_expressions, batch)?;+ Ok::<_, DataFusionError>((input_values, filter_values))+ })?;assert_eq_or_internal_err!(group_values.len(),diff --git a/datafusion/physical-plan/src/aggregates/grouped_topk_stream.rs b/datafusion/physical-plan/src/aggregates/grouped_topk_stream.rsindex a5b274cffe..13ead73930 100644--- a/datafusion/physical-plan/src/aggregates/grouped_topk_stream.rs+++ b/datafusion/physical-plan/src/aggregates/grouped_topk_stream.rs@@ -74,7 +74,7 @@ impl GroupedTopKAggregateStream {let group_by = Arc::clone(&aggr.group_by);let input = aggr.input.execute(partition, Arc::clone(context))?;let baseline_metrics = BaselineMetrics::new(&aggr.metrics, partition);- let group_by_metrics = GroupByMetrics::new(&aggr.metrics, partition);+ let group_by_metrics = GroupByMetrics::new_topk(&aggr.metrics, partition);let aggregate_argument_metrics = AggregateArgumentMetrics::new(&aggr.metrics,partition,@@ -151,38 +151,40 @@ impl GroupedTopKAggregateStream {}fn intern(&mut self, ids: &ArrayRef, vals: &ArrayRef) -> Result<()> {- let _timer = self.group_by_metrics.time_calculating_group_ids.timer();+ let group_by_metrics = self.group_by_metrics.clone();+ group_by_metrics.time_topk_maintenance(|| {+ let len = ids.len();+ self.priority_map+ .set_batch(Arc::clone(ids), Arc::clone(vals));- let len = ids.len();- self.priority_map- .set_batch(Arc::clone(ids), Arc::clone(vals));-- let has_nulls = vals.null_count() > 0;- if has_nulls && self.is_group_by_only() {- self.null_group_seen = true;- }- // Keep the common no-NULL path free of NULL bookkeeping. Once a NULL- // group exists, use the NULL-aware path until it has been resolved.- let track_null_groups = !self.is_group_by_only()- && (has_nulls || self.priority_map.has_null_groups());- for row_idx in 0..len {- if has_nulls && vals.is_null(row_idx) {- // MIN/MAX ignore NULL inputs, but a group whose values are all- // NULL must still be emitted with a NULL aggregate value, so- // track it. (GROUP BY-only aggregations handle NULL group keys- // via `null_group_seen` instead.)- if !self.is_group_by_only() {- self.priority_map.insert_null(row_idx);- }- continue;+ let has_nulls = vals.null_count() > 0;+ let is_group_by_only = self.is_group_by_only();+ if has_nulls && is_group_by_only {+ self.null_group_seen = true;}- if track_null_groups {- self.priority_map.insert_with_null_groups(row_idx)?;- } else {- self.priority_map.insert(row_idx)?;+ // Keep the common no-NULL path free of NULL bookkeeping. Once a NULL+ // group exists, use the NULL-aware path until it has been resolved.+ let track_null_groups =+ !is_group_by_only && (has_nulls || self.priority_map.has_null_groups());+ for row_idx in 0..len {+ if has_nulls && vals.is_null(row_idx) {+ // MIN/MAX ignore NULL inputs, but a group whose values are all+ // NULL must still be emitted with a NULL aggregate value, so+ // track it. (GROUP BY-only aggregations handle NULL group keys+ // via `null_group_seen` instead.)+ if !is_group_by_only {+ self.priority_map.insert_null(row_idx);+ }+ continue;+ }+ if track_null_groups {+ self.priority_map.insert_with_null_groups(row_idx)?;+ } else {+ self.priority_map.insert(row_idx)?;+ }}- }- Ok(())+ Ok(())+ })}fn emit_columns(&mut self) -> Result<Vec<ArrayRef>> {@@ -230,7 +232,6 @@ impl Stream for GroupedTopKAggregateStream {return Poll::Ready(None);}let elapsed_compute = self.baseline_metrics.elapsed_compute().clone();- let emitting_time = self.group_by_metrics.emitting_time.clone();while let Poll::Ready(res) = self.input.poll_next_unpin(cx) {let _timer = elapsed_compute.timer();match res {@@ -247,7 +248,10 @@ impl Stream for GroupedTopKAggregateStream {print_batches(std::slice::from_ref(&batch))?;}self.row_count += batch.num_rows();- let group_by_values = evaluate_group_by(&self.group_by, &batch)?;+ let group_by_values =+ self.group_by_metrics.time_group_key_preparation(|| {+ evaluate_group_by(&self.group_by, &batch)+ })?;assert_eq!(group_by_values.len(),1,@@ -264,18 +268,18 @@ impl Stream for GroupedTopKAggregateStream {Arc::clone(&group_by_values)} else {// MIN/MAX case: evaluate aggregate expressions- let _timer =- self.group_by_metrics.aggregate_arguments_time.timer();- let input_values = self- .aggregate_arguments- .iter()- .enumerate()- .map(|(idx, expr)| {- self.aggregate_argument_metrics.time(idx, || {- evaluate_expressions_to_arrays(expr, &batch)- })- })- .collect::<Result<Vec<_>>>()?;+ let input_values =+ self.group_by_metrics.time_aggregate_arguments(|| {+ self.aggregate_arguments+ .iter()+ .enumerate()+ .map(|(idx, expr)| {+ self.aggregate_argument_metrics.time(idx, || {+ evaluate_expressions_to_arrays(expr, &batch)+ })+ })+ .collect::<Result<Vec<_>>>()+ })?;assert_eq!(input_values.len(), 1, "Exactly 1 input required");assert_eq!(input_values[0].len(), 1, "Exactly 1 input required");Arc::clone(&input_values[0][0])@@ -294,11 +298,11 @@ impl Stream for GroupedTopKAggregateStream {self.done = true;return Poll::Ready(None);}- let batch = {- let _timer = emitting_time.timer();+ let group_by_metrics = self.group_by_metrics.clone();+ let batch = group_by_metrics.time_emitting(|| {let cols = self.emit_columns()?;- RecordBatch::try_new(Arc::clone(&self.schema), cols)?- };+ RecordBatch::try_new(Arc::clone(&self.schema), cols)+ })?;let batch = batch.record_output(&self.baseline_metrics);trace!("partition {} emit batch with {} rows",@@ -398,6 +402,15 @@ mod tests {assert!(argument_metric.is_some());assert!(argument_metric.unwrap().value().as_usize() > 0);+ let topk_maintenance_time = metrics.sum_by_name("topk_maintenance_time");+ assert!(topk_maintenance_time.is_some());+ assert!(topk_maintenance_time.unwrap().as_usize() > 0);++ let group_id_time = metrics.sum_by_name("time_calculating_group_ids");+ assert!(group_id_time.is_some());+ assert!(group_id_time.unwrap().as_usize() > 0);+ assert!(metrics.sum_by_name("aggregation_time").is_none());+Ok(())}}diff --git a/datafusion/physical-plan/src/aggregates/mod.rs b/datafusion/physical-plan/src/aggregates/mod.rsindex ba08c4b003..774c08535c 100644--- a/datafusion/physical-plan/src/aggregates/mod.rs+++ b/datafusion/physical-plan/src/aggregates/mod.rs@@ -4407,6 +4407,13 @@ mod tests {| 2 |+---+");+ assert!(+ partial_aggregate+ .metrics()+ .unwrap()+ .sum_by_name("topk_maintenance_time")+ .is_none()+ );let final_input =TestMemoryExec::try_new_exec(&[input_batches], Arc::clone(&schema), None)?;@@ -4441,6 +4448,13 @@ mod tests {| 2 |+---+");+ assert!(+ final_aggregate+ .metrics()+ .unwrap()+ .sum_by_name("topk_maintenance_time")+ .is_none()+ );Ok(())}diff --git a/docs/source/user-guide/metrics.md b/docs/source/user-guide/metrics.mdindex 306094c438..5bb4895a3d 100644--- a/docs/source/user-guide/metrics.md+++ b/docs/source/user-guide/metrics.md@@ -61,6 +61,127 @@ subsequent join processing time.| avg_fanout | Average number of build-side join-key matches per matched probe-side row before applying any join filter. || array_map_created_count | Number of times `HashJoinExec` created an `ArrayMap` for perfect hash join lookup execution. |+### AggregateExec++`AggregateExec` exposes the common `BaselineMetrics`, the operator-level+metrics below, and a timer per aggregate expression and execution phase.++| Metric | Description |+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |+| time_calculating_group_ids | Time spent preparing group keys; see the note below for path-specific coverage. |+| aggregate_arguments_time | Total time spent evaluating the inputs to the aggregate functions. `agg_expr_{index}_arguments_time` breaks this down per expression. |+| aggregation_time | Time spent invoking accumulator `update` and `merge` operations. |+| emitting_time | Time spent materializing group values and accumulator `state` or `evaluate` results. |+| topk_maintenance_time | Time spent maintaining Grouped TopK's priority map, including batch setup, insertion, comparison, and NULL handling. |+| skipped_aggregation_rows | Number of input rows passed through without aggregating them, when partial aggregation is skipped. |+| reduction_factor | Rows emitted per row consumed by a partial aggregation, displayed as `66.67% (2/3)`. |+| spill_count | Number of spill files written when the aggregation exceeds its memory budget. |+| spilled_bytes | Total number of bytes written to spill files. |+| spilled_rows | Total number of rows written to spill files. |+| peak_mem_used | Peak tracked memory held by the grouped aggregation, in bytes; recorded by the fallback grouped hash path only. |++These operator-level metrics are recorded by the grouped aggregation paths+only: an `AggregateExec` without a `GROUP BY` reports just `BaselineMetrics`+and the per-aggregate timers. `reduction_factor` and `skipped_aggregation_rows`+are recorded in partial mode only. `skipped_aggregation_rows` is recorded only+when partial-aggregation skipping is enabled for a single, non-grouping-sets+`GROUP BY` whose input is not ordered by its grouping expressions; a+`datafusion.execution.skip_partial_aggregation_probe_ratio_threshold` of `>= 1.0`+disables the feature.++`time_calculating_group_ids` covers both grouping-expression evaluation and+resolving the resulting rows to group IDs, including interning and ordering+setup. `aggregation_time` covers only accumulator `update` and `merge` calls.+On accumulator-backed grouped aggregation paths, `state` and `evaluate` are+included in `emitting_time`, including when partial aggregation materializes+state under memory pressure. For an `AggregateExec` without a `GROUP BY`, the+per-aggregate `state` and `evaluate` timers are recorded during+`elapsed_compute`; it does not report grouped operator metrics such as+`emitting_time`. Partial aggregation that skips aggregation reports+`convert_to_state` instead of `aggregation_time` for those rows.++When the specialized Grouped TopK path is selected for a limited grouped+aggregate, it has no accumulators. Its group-key expression evaluation is+included in `time_calculating_group_ids`, and its priority-map work is reported+by `topk_maintenance_time`; it does not report accumulator phases. Planner+selection is query-shape dependent: a limited `DISTINCT` query without+ordering requirements uses the regular aggregate path instead.++The per-aggregate timers are named `agg_expr_{index}_{phase}_time`, where+`index` is the zero-based position of an aggregate expression in the operator+and `phase` is one of the following:++| Phase | Description |+| ------------------ | --------------------------------------------------------------------------------------------- |+| `arguments` | Evaluating the aggregate's argument expressions into input arrays. |+| `update` | Updating an accumulator from raw input values. |+| `merge` | Merging partial accumulator states. |+| `state` | Obtaining an accumulator's intermediate state for partial output or aggregate spilling. |+| `convert_to_state` | Converting raw aggregate inputs directly to partial state without normal accumulator updates. |+| `evaluate` | Evaluating an accumulator to its final result. |++For example, when a partial stage is planned, the partial `AggregateExec` for+`SELECT SUM(a), SUM(b) FROM t` reports `agg_expr_0_arguments_time` and+`agg_expr_0_update_time` for `SUM(a)`,+and `agg_expr_1_arguments_time` and `agg_expr_1_update_time` for `SUM(b)`. The+index is positional and refers to the same position in the `aggr=[...]` list+printed on the operator's plan line, which is how an indexed timer is mapped+back to an aggregate expression. Because the index is part of the metric name,+otherwise identical functions over different columns stay distinct when+per-partition metrics are combined.++Each per-aggregate timer additionally carries an `aggregate` label holding the+rendered aggregate expression (for example, `sum(t.a)`). Combining metrics+across partitions drops labels, so this label is only shown in the "Plan with+Full Metrics" section of `EXPLAIN ANALYZE VERBOSE`, which reports metrics per+partition.++`arguments` is recorded in every mode. The accumulator phases that are present+depend on the aggregate mode and implementation. For non-grouped aggregation,+partial mode records `update` and `state`, partial reduce mode records `merge`+and `state`, final mode records `merge` and `evaluate`, and single mode records+`update` and `evaluate`. Hash aggregation uses `update`, `state`, and+`convert_to_state` in partial mode; `merge` and `state` in partial-reduce mode;+`merge`, `state`, and `evaluate` in final mode; and `update`, `state`, `merge`,+and `evaluate` in single mode. Its `state` timers measure intermediate-state+emission, including during spilling. The grouped TopK aggregate path records+only the per-aggregate `arguments` timer, because it maintains values directly+rather than using accumulators.++Where an aggregate has a `FILTER` clause, its evaluation is included in+`aggregate_arguments_time`. Per-aggregate `arguments` timers include the filter+when it is evaluated per aggregate. The legacy grouped hash path evaluates+filters collectively, so its per-aggregate `arguments` timers cover argument+expressions only; their sum need not equal `aggregate_arguments_time`.++Except for the `Summary` metric `reduction_factor`, these operator-level and+per-aggregate metrics are `Dev` metrics. They appear in `EXPLAIN ANALYZE` when+`datafusion.explain.analyze_level` includes `Dev` (the default), but are omitted+at the `Summary` level. The normal display combines partitions; use `EXPLAIN ANALYZE VERBOSE` to additionally show the per-partition values together with+each per-aggregate timer's `aggregate` label. For a query+such as the following, the per-expression metrics stay readable, and the+operator's `aggr=[...]` list names the aggregate behind each timer index:++```sql+EXPLAIN ANALYZE+SELECT k, SUM(a), SUM(b), COUNT(c)+FROM t+GROUP BY k;+```++The abbreviated partial-aggregate plan line below shows that mapping (timings+and unrelated metrics are omitted):++```text+AggregateExec: mode=Partial, gby=[k@0 as k], aggr=[sum(t.a), sum(t.b), count(t.c)],+ metrics=[..., agg_expr_0_arguments_time=..., agg_expr_1_arguments_time=...,+ agg_expr_2_arguments_time=...]+```++Thus `agg_expr_0_*` is `sum(t.a)`, `agg_expr_1_*` is `sum(t.b)`, and+`agg_expr_2_*` is `count(t.c)`. In verbose output, the corresponding+`aggregate` labels provide the same mapping per partition.+## TODOAdd metrics for the remaining operators