Apache DataFusion SQL Query Engine
fix(physical-plan): honor distinct soft limits in SingleHashAggregateStream (#25158)
Tiny_Murky38d58ed09db2
diff --git a/datafusion/core/tests/physical_optimizer/limited_distinct_aggregation.rs b/datafusion/core/tests/physical_optimizer/limited_distinct_aggregation.rsindex 323dfd6183..9a43ba01da 100644--- a/datafusion/core/tests/physical_optimizer/limited_distinct_aggregation.rs+++ b/datafusion/core/tests/physical_optimizer/limited_distinct_aggregation.rs@@ -104,8 +104,8 @@ async fn test_partial_final() -> Result<()> {Ok(())}-// Ensure operator respect the soft limit and stops early: `AggregateExec`'s-// `output_rows` metric should be smaller than then total distinct group count.+// Ensure operator respects the soft limit and stops early: `AggregateExec`'s+// `output_rows` metric should be smaller than the total distinct group count.#[tokio::test]async fn limited_distinct_aggregate_stream_respects_soft_limit() -> Result<()> {// Snapshot for an aggregate operator node from `EXPLAIN ANALYZE`.@@ -219,6 +219,125 @@ async fn limited_distinct_aggregate_stream_respects_soft_limit() -> Result<()> {Ok(())}+// Ensure operator respects the soft limit and stops early: `AggregateExec`'s+// `output_rows` metric should be smaller than the total distinct group count.+#[tokio::test]+async fn single_distinct_aggregate_stream_respects_soft_limit() -> Result<()> {+ // Snapshot for an aggregate operator node from `EXPLAIN ANALYZE`.+ //+ // Example: In an `EXPLAIN ANALYZE` output+ // ```txt+ // AggregateExec: mode=single, aggr=[], lim=[10], metrics=[output_rows=10, ...]+ // ProjectionExec: metrics=[output_rows=10, ...]+ // ```+ //+ // `output_rows` comes from the `AggregateExec` itself, while `input_rows`+ // is the `output_rows` metric of its direct input operator (such as a `ProjectionExec`).+ // Tracking both distinguishes early input termination from the downstream `LimitExec`+ // merely stopping after it receives enough output rows.+ //+ // we get:+ // ```txt+ // AggregateRuntimeMetric {+ // mode: Single,+ // limit: Some(10),+ // input_rows: 10,+ // output_rows: 10,+ // }+ // ```+ #[derive(Debug)]+ struct AggregateRuntimeMetric {+ mode: AggregateMode,+ limit: Option<usize>,+ input_rows: usize,+ output_rows: usize,+ }++ fn collect_aggregate_runtime_metrics(+ plan: &Arc<dyn ExecutionPlan>,+ metrics: &mut Vec<AggregateRuntimeMetric>,+ ) {+ if let Some(agg) = plan.downcast_ref::<AggregateExec>() {+ let input_rows = agg+ .input()+ .metrics()+ .and_then(|metrics| metrics.aggregate_by_name().output_rows())+ .expect("The input Exec should record output_rows after execution");++ let output_rows = agg+ .metrics()+ .and_then(|metrics| metrics.aggregate_by_name().output_rows())+ .expect("AggregateExec should record output_rows after execution");++ metrics.push(AggregateRuntimeMetric {+ mode: *agg.mode(),+ limit: agg.limit_options().map(|config| config.limit()),+ input_rows,+ output_rows,+ });+ }++ for child in plan.children() {+ collect_aggregate_runtime_metrics(child, metrics);+ }+ }++ fn aggregate_runtime_metrics(+ plan: &Arc<dyn ExecutionPlan>,+ ) -> Vec<AggregateRuntimeMetric> {+ let mut metrics = vec![];+ collect_aggregate_runtime_metrics(plan, &mut metrics);+ metrics+ }++ let cfg = SessionConfig::new()+ .with_target_partitions(1)+ .with_batch_size(10)+ .set_bool("datafusion.execution.enable_migration_aggregate", true);++ let ctx = SessionContext::new_with_config(cfg);++ let dataframe = ctx+ .sql(+ "SELECT DISTINCT value % 100000 AS v \+ FROM generate_series(1000000) \+ LIMIT 10",+ )+ .await?;+ let plan = dataframe.create_physical_plan().await?;+ let formatted_plan = displayable(plan.as_ref()).indent(false).to_string();+ assert!(+ formatted_plan.contains("AggregateExec: mode=Single"),+ "expected a single aggregate in plan:\n{formatted_plan}"+ );++ let batches = collect(Arc::clone(&plan), ctx.task_ctx()).await?;+ assert_eq!(+ batches.iter().map(|batch| batch.num_rows()).sum::<usize>(),+ 10+ );++ let metrics = aggregate_runtime_metrics(&plan);+ let single = metrics+ .iter()+ .find(|metric| metric.mode == AggregateMode::Single)+ .expect("expected single aggregate metrics");++ assert_eq!(single.limit, Some(10));++ assert!(+ single.input_rows <= 10,+ "single aggregate should stop reading input after reaching the soft limit: {metrics:?}"+ );++ assert!(+ single.output_rows <= 10,+ "single aggregate should stop before emitting all distinct groups: {metrics:?}"+ );++ Ok(())+}+#[tokio::test]async fn test_single_local() -> Result<()> {let source = mock_data()?;diff --git a/datafusion/physical-plan/src/aggregates/mod.rs b/datafusion/physical-plan/src/aggregates/mod.rsindex 3ed93e09ce..854fbf8484 100644--- a/datafusion/physical-plan/src/aggregates/mod.rs+++ b/datafusion/physical-plan/src/aggregates/mod.rs@@ -868,8 +868,8 @@ pub struct AggregateExec {/// Supported by:/// - [`StreamType::GroupedPriorityQueue`]: retains only the best `limit`/// groups per partition (this stream is selected only when a limit is set)- /// - [`StreamType::PartialHash`], [`StreamType::FinalHash`] and the legacy- /// [`StreamType::GroupedHash`]: stop reading input once `limit` groups+ /// - [`StreamType::SingleHash`], [`StreamType::PartialHash`], [`StreamType::FinalHash`]+ /// and the legacy [`StreamType::GroupedHash`]: stop reading input once `limit` groups/// have been accumulated////// The remaining streams consume all input.diff --git a/datafusion/physical-plan/src/aggregates/single_stream.rs b/datafusion/physical-plan/src/aggregates/single_stream.rsindex 6d46b90c26..cfa708c511 100644--- a/datafusion/physical-plan/src/aggregates/single_stream.rs+++ b/datafusion/physical-plan/src/aggregates/single_stream.rs@@ -88,6 +88,34 @@ use crate::{InputOrderMode, RecordBatchStream, SendableRecordBatchStream};/// into an ordered streaming aggregation, which ensures bounded memory usage and/// evaluates the final result./// - [`OrderedFinalAggregateStream`] is reused for the streaming aggregation.+///+/// # Optimization: DISTINCT LIMIT Soft Limit+///+/// When the input has only one partition or the input is already partitioned,+/// unordered distinct queries such as:+///+/// ```sql+/// SELECT DISTINCT x FROM t LIMIT 10;+/// ```+///+/// are optimized into a single-stage aggregate like:+///+/// ```txt+/// LimitExec, limit=10+/// --AggregateExec(Single), group_by=[x], aggr=[], soft_limit=10+/// ---- Scan(t)+/// ```+///+/// After each input batch, the stream checks whether the soft limit has been+/// reached. If so, it emits the accumulated groups and stops reading input.+///+/// This early termination is skipped after spilling has occurred to keep the+/// spill and replay path simple. In that case, the stream consumes the remaining+/// input and merges all spill runs before producing output.+///+/// This operator does not guarantee an exact limit because a single batch can+/// cross the threshold. The downstream limit operator enforces the exact result+/// size.pub(crate) struct SingleHashAggregateStream {/// Output schema: group columns followed by final aggregate value columns.schema: SchemaRef,@@ -104,6 +132,10 @@ pub(crate) struct SingleHashAggregateStream {/// Tracks the high-level stream lifecycle. The hash table owns the lower-level/// state for emitting output batches.state: Option<SingleHashAggregateState>,++ /// See the "Optimization: DISTINCT LIMIT Soft Limit" section in+ /// [`SingleHashAggregateStream`] for details.+ group_values_soft_limit: Option<usize>,}/// Spill configuration and accumulated runs for single hash aggregation.@@ -374,6 +406,7 @@ impl SingleHashAggregateStream {hash_table,spill_context,}),+ group_values_soft_limit: agg.limit_options().map(|config| config.limit()),})}@@ -449,6 +482,20 @@ impl SingleHashAggregateStream {return Self::break_with_err(e);}+ // Soft group limits are usually small and rarely coincide with+ // spilling. Once spilling has occurred, skip this optimization to+ // make the internal logic simpler.+ let spilled = spill_context+ .as_ref()+ .is_some_and(|context| context.has_spills());++ // See the "Optimization: DISTINCT LIMIT Soft Limit" section in+ // `SingleHashAggregateStream` for details.+ if self.hit_soft_group_limit(&hash_table) && !spilled {+ return self+ .close_input_and_prepare_output(hash_table, spill_context);+ }+// Check memory reservation, and potentially spill.let timer = elapsed_compute.timer();let resize_result =@@ -490,30 +537,53 @@ impl SingleHashAggregateStream {}Poll::Ready(Some(Err(e))) => Self::break_with_err(e),Poll::Ready(None) => {- self.close_input();- match spill_context {- Some(spill_context) if spill_context.has_spills() => {- ControlFlow::Continue(- SingleHashAggregateState::PreparingMergeInput {- hash_table,- spill_context,- },- )- }- _ => {- let elapsed_compute =- self.baseline_metrics.elapsed_compute().clone();- let timer = elapsed_compute.timer();- let result = hash_table.start_output();- timer.done();-- match result {- Ok(()) => ControlFlow::Continue(- SingleHashAggregateState::ProducingOutput { hash_table },- ),- Err(e) => Self::break_with_err(e),- }+ self.close_input_and_prepare_output(hash_table, spill_context)+ }+ }+ }++ /// See comments in [`Self::group_values_soft_limit`] for details.+ fn hit_soft_group_limit(+ &self,+ hash_table: &AggregateHashTable<SingleMarker>,+ ) -> bool {+ self.group_values_soft_limit+ .is_some_and(|limit| limit <= hash_table.building_group_count())+ }++ /// Stops consuming input and prepares the next execution phase.+ /// Called when the input is exhausted or the distinct soft limit is reached.+ ///+ /// If data has been spilled, transitions to `PreparingMergeInput` so the+ /// spilled and in-memory groups can be merged before output. Otherwise,+ /// starts output from the in-memory hash table and transitions to+ /// `ProducingOutput`.+ fn close_input_and_prepare_output(+ &mut self,+ mut hash_table: AggregateHashTable<SingleMarker>,+ spill_context: Option<Box<SingleSpillContext>>,+ ) -> SingleHashAggregateStateTransition {+ self.close_input();+ match spill_context {+ Some(spill_context) if spill_context.has_spills() => {+ ControlFlow::Continue(SingleHashAggregateState::PreparingMergeInput {+ hash_table,+ spill_context,+ })+ }+ _ => {+ let elapsed_compute = self.baseline_metrics.elapsed_compute().clone();+ let timer = elapsed_compute.timer();+ let result = hash_table.start_output();+ timer.done();++ match result {+ Ok(()) => {+ ControlFlow::Continue(SingleHashAggregateState::ProducingOutput {+ hash_table,+ })}+ Err(e) => Self::break_with_err(e),}}}@@ -728,7 +798,8 @@ impl Stream for SingleHashAggregateStream {/// The table cannot reserve enough memory. Move all current states into/// one fully group-key-sorted spill run./// -> ProducingOutput- /// Input was exhausted without spilling. Start outputting final values.+ /// Input was exhausted without spilling, or the distinct soft limit was+ /// reached before spilling. Start outputting final values./// -> PreparingMergeInput/// Input was exhausted after spilling. Spill the last in-memory run and/// construct the ordered input used to merge all spill files.