Skip to content

Commit 8b4b772

Browse files
committed
fix(physical-plan): honor distinct soft limits in SingleHashAggregateStream
## Which issue does this PR close? - Closes [apache#24980](apache#24980) ## Rationale for this change `SingleHashAggregateStream` ignores the distinct soft limit pushed into `AggregateExec`. As a result, single-stage `SELECT DISTINCT ... LIMIT n` queries consume all input even after enough distinct groups have been collected. This change stops input consumption once the in-memory hash table contains at least the requested number of distinct groups. Any existing spills are merged before producing output, and the downstream limit operator enforces the exact output row count. ## What changes are included in this PR? * Add a distinct soft-limit check to `SingleHashAggregateStream` after processing each input batch. * Reuse the input-exhausted transition when the soft limit is reached, preserving spill merging and output preparation. * Add unit tests covering early termination with and without spilling. - Update the `AggregateExec::limit_options` documentation to list `SingleHash` as supporting distinct soft limits. ## Are these changes tested? Added unit tests covering: * Reaching the soft limit without spilling. * Reaching the soft limit after spilling, preserving spilled groups and deduplicating overlapping groups. * Rejecting further input consumption after the soft limit is reached in the spill case. Following test commands have been executed and passed - `cargo test --profile=ci --test sqllogictests` - `cargo test -p datafusion` - `cargo test -p datafusion-cli` ## Are there any user-facing changes? Single-stage `DISTINCT` queries with a limit can stop consuming input earlier, reducing unnecessary work. Query semantics are unchanged.
1 parent f8cc678 commit 8b4b772

2 files changed

Lines changed: 267 additions & 25 deletions

File tree

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

Lines changed: 195 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -868,8 +868,8 @@ pub struct AggregateExec {
868868
/// Supported by:
869869
/// - [`StreamType::GroupedPriorityQueue`]: retains only the best `limit`
870870
/// groups per partition (this stream is selected only when a limit is set)
871-
/// - [`StreamType::PartialHash`], [`StreamType::FinalHash`] and the legacy
872-
/// [`StreamType::GroupedHash`]: stop reading input once `limit` groups
871+
/// - [`StreamType::SingleHash`], [`StreamType::PartialHash`], [`StreamType::FinalHash`]
872+
/// and the legacy [`StreamType::GroupedHash`]: stop reading input once `limit` groups
873873
/// have been accumulated
874874
///
875875
/// The remaining streams consume all input.
@@ -4424,6 +4424,199 @@ mod tests {
44244424
Ok(())
44254425
}
44264426

4427+
#[tokio::test]
4428+
async fn single_hash_distinct_aggregation_soft_limit_no_spill() -> Result<()> {
4429+
// Verify that single hash aggregation stops reading
4430+
// input once it has collected enough distinct groups to
4431+
// satisfy the soft limit.
4432+
4433+
let soft_limit: usize = 2;
4434+
4435+
let schema =
4436+
Arc::new(Schema::new(vec![Field::new("a", DataType::UInt32, false)]));
4437+
4438+
let input_batches = vec![
4439+
RecordBatch::try_new(
4440+
Arc::clone(&schema),
4441+
// The accumulated groups should be [1]
4442+
vec![Arc::new(UInt32Array::from(vec![1, 1]))],
4443+
)?,
4444+
RecordBatch::try_new(
4445+
Arc::clone(&schema),
4446+
// The accumulated groups should be [1, 2]
4447+
vec![Arc::new(UInt32Array::from(vec![2, 2]))],
4448+
)?,
4449+
RecordBatch::try_new(
4450+
Arc::clone(&schema),
4451+
// This batch must not be read.
4452+
vec![Arc::new(UInt32Array::from(vec![3, 4, 5]))],
4453+
)?,
4454+
];
4455+
4456+
let group_by =
4457+
PhysicalGroupBy::new_single(vec![(col("a", &schema)?, "a".to_string())]);
4458+
4459+
let input = TestMemoryExec::try_new_exec(
4460+
std::slice::from_ref(&input_batches),
4461+
Arc::clone(&schema),
4462+
None,
4463+
)?;
4464+
4465+
let single_aggregate = Arc::new(
4466+
AggregateExec::try_new(
4467+
AggregateMode::Single,
4468+
group_by.clone(),
4469+
vec![],
4470+
vec![],
4471+
input,
4472+
Arc::clone(&schema),
4473+
)?
4474+
.with_limit_options(Some(LimitOptions::new(soft_limit))),
4475+
);
4476+
4477+
let task_ctx = Arc::new(
4478+
TaskContext::default().with_session_config(
4479+
SessionConfig::new()
4480+
.set_bool("datafusion.execution.enable_migration_aggregate", true),
4481+
),
4482+
);
4483+
4484+
let single_stream = single_aggregate.execute_typed(0, &task_ctx)?;
4485+
assert!(matches!(single_stream, StreamType::SingleHash(_)));
4486+
let stream: SendableRecordBatchStream = single_stream.into();
4487+
let single_output = collect(stream).await?;
4488+
assert_eq!(
4489+
single_output
4490+
.iter()
4491+
.map(RecordBatch::num_rows)
4492+
.sum::<usize>(),
4493+
soft_limit
4494+
);
4495+
assert_snapshot!(batches_to_sort_string(&single_output), @r"
4496+
+---+
4497+
| a |
4498+
+---+
4499+
| 1 |
4500+
| 2 |
4501+
+---+
4502+
");
4503+
4504+
Ok(())
4505+
}
4506+
4507+
#[tokio::test]
4508+
async fn single_hash_distinct_aggregation_soft_limit_with_spill() -> Result<()> {
4509+
// Verify that reaching the soft limit after spilling stops input consumption
4510+
// and merges the spilled and in-memory groups before producing output.
4511+
4512+
use crate::test::exec::MockExec;
4513+
4514+
// Force the first batch to spill while leaving room for spill replay.
4515+
let pool_size = 8 * 1024; // 8 KiB
4516+
let batch_size = 2;
4517+
let memory_pool = Arc::new(FairSpillPool::new(pool_size));
4518+
let task_ctx = Arc::new(
4519+
TaskContext::default()
4520+
.with_session_config(
4521+
SessionConfig::new().with_batch_size(batch_size).set_bool(
4522+
"datafusion.execution.enable_migration_aggregate",
4523+
true,
4524+
),
4525+
)
4526+
.with_runtime(Arc::new(
4527+
RuntimeEnvBuilder::new()
4528+
.with_memory_pool(memory_pool)
4529+
.build()?,
4530+
)),
4531+
);
4532+
4533+
let soft_limit = 1024;
4534+
4535+
let schema =
4536+
Arc::new(Schema::new(vec![Field::new("a", DataType::UInt32, false)]));
4537+
4538+
let input_batches = vec![
4539+
RecordBatch::try_new(
4540+
Arc::clone(&schema),
4541+
// Fewer groups than the soft limit, but enough to force a spill.
4542+
vec![Arc::new(UInt32Array::from_iter_values(0..512))],
4543+
)
4544+
.map_err(DataFusionError::from),
4545+
RecordBatch::try_new(
4546+
Arc::clone(&schema),
4547+
// Reach the soft limit after spilling, with overlapping groups.
4548+
vec![Arc::new(UInt32Array::from_iter_values(256..1280))],
4549+
)
4550+
.map_err(DataFusionError::from),
4551+
// Reading past the soft limit must fail the test, even if those
4552+
// additional rows would not change the aggregate's output.
4553+
Err(DataFusionError::Execution(
4554+
"input must not be polled after reaching the soft limit".to_string(),
4555+
)),
4556+
];
4557+
4558+
let group_by =
4559+
PhysicalGroupBy::new_single(vec![(col("a", &schema)?, "a".to_string())]);
4560+
4561+
let input = Arc::new(
4562+
MockExec::new(input_batches, Arc::clone(&schema))
4563+
.with_use_task(false)
4564+
// Avoid inspecting the intentional input error (in `vec!`) while
4565+
// computing statistics before execution.
4566+
.with_unknown_statistics(),
4567+
);
4568+
4569+
let single_aggregate = Arc::new(
4570+
AggregateExec::try_new(
4571+
AggregateMode::Single,
4572+
group_by,
4573+
vec![],
4574+
vec![],
4575+
input,
4576+
Arc::clone(&schema),
4577+
)?
4578+
.with_limit_options(Some(LimitOptions::new(soft_limit))),
4579+
);
4580+
4581+
let stream = single_aggregate.execute_typed(0, &task_ctx)?;
4582+
assert!(matches!(stream, StreamType::SingleHash(_)));
4583+
let stream: SendableRecordBatchStream = stream.into();
4584+
let output = collect(stream).await?;
4585+
4586+
let mut values: Vec<u32> = output
4587+
.iter()
4588+
.flat_map(|batch| {
4589+
batch
4590+
.column(0)
4591+
.as_any()
4592+
.downcast_ref::<UInt32Array>()
4593+
.unwrap()
4594+
.values()
4595+
.iter()
4596+
.copied()
4597+
})
4598+
.collect();
4599+
values.sort_unstable();
4600+
4601+
//The merged output must contain each value in 0..1280
4602+
// exactly once.
4603+
assert_eq!(values, (0..1280).collect::<Vec<u32>>());
4604+
4605+
let metrics = single_aggregate.metrics().expect("metrics must exist");
4606+
4607+
assert!(
4608+
metrics.spill_count().unwrap_or(0) > 0,
4609+
"test must actually spill"
4610+
);
4611+
4612+
assert!(
4613+
metrics.spilled_rows().unwrap_or(0) > 0,
4614+
"test must spill group rows",
4615+
);
4616+
4617+
Ok(())
4618+
}
4619+
44274620
#[tokio::test]
44284621
async fn limited_distinct_aggregate_uses_migrated_hash_streams() -> Result<()> {
44294622
let schema =

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

Lines changed: 72 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,10 @@ pub(crate) struct SingleHashAggregateStream {
104104
/// Tracks the high-level stream lifecycle. The hash table owns the lower-level
105105
/// state for emitting output batches.
106106
state: Option<SingleHashAggregateState>,
107+
108+
/// When set, there are no aggregate expressions: AggregateExec routes
109+
/// limited non-DISTINCT aggregates to a different stream.
110+
group_values_soft_limit: Option<usize>,
107111
}
108112

109113
/// Spill configuration and accumulated runs for single hash aggregation.
@@ -374,6 +378,7 @@ impl SingleHashAggregateStream {
374378
hash_table,
375379
spill_context,
376380
}),
381+
group_values_soft_limit: agg.limit_options().map(|config| config.limit()),
377382
})
378383
}
379384

@@ -449,6 +454,27 @@ impl SingleHashAggregateStream {
449454
return Self::break_with_err(e);
450455
}
451456

457+
// Soft limit optimization:
458+
//
459+
// Stop reading input once the in-memory table contains enough distinct
460+
// groups to satisfy the soft limit.
461+
//
462+
// When a limit is present, AggregateExec routes only unordered,
463+
// unfiltered DISTINCT aggregates to this stream.
464+
//
465+
// With no aggregate expressions, additional input can only match existing
466+
// groups or add new ones; it cannot change any existing group's output.
467+
// Since there is no ordering requirement and we already have enough
468+
// distinct groups, we can finish reading as if the input were exhausted.
469+
//
470+
// Reuse the input-exhausted transition to merge any existing spills
471+
// before producing output. The downstream limit operator enforces
472+
// the exact output row count.
473+
if self.hit_soft_group_limit(&hash_table) {
474+
return self
475+
.close_input_and_prepare_output(hash_table, spill_context);
476+
}
477+
452478
// Check memory reservation, and potentially spill.
453479
let timer = elapsed_compute.timer();
454480
let resize_result =
@@ -490,30 +516,53 @@ impl SingleHashAggregateStream {
490516
}
491517
Poll::Ready(Some(Err(e))) => Self::break_with_err(e),
492518
Poll::Ready(None) => {
493-
self.close_input();
494-
match spill_context {
495-
Some(spill_context) if spill_context.has_spills() => {
496-
ControlFlow::Continue(
497-
SingleHashAggregateState::PreparingMergeInput {
498-
hash_table,
499-
spill_context,
500-
},
501-
)
502-
}
503-
_ => {
504-
let elapsed_compute =
505-
self.baseline_metrics.elapsed_compute().clone();
506-
let timer = elapsed_compute.timer();
507-
let result = hash_table.start_output();
508-
timer.done();
509-
510-
match result {
511-
Ok(()) => ControlFlow::Continue(
512-
SingleHashAggregateState::ProducingOutput { hash_table },
513-
),
514-
Err(e) => Self::break_with_err(e),
515-
}
519+
self.close_input_and_prepare_output(hash_table, spill_context)
520+
}
521+
}
522+
}
523+
524+
/// See comments in [`Self::group_values_soft_limit`] for details.
525+
fn hit_soft_group_limit(
526+
&self,
527+
hash_table: &AggregateHashTable<SingleMarker>,
528+
) -> bool {
529+
self.group_values_soft_limit
530+
.is_some_and(|limit| limit <= hash_table.building_group_count())
531+
}
532+
533+
/// Stops consuming input and prepares the next execution phase.
534+
/// Called when the input is exhausted or the distinct soft limit is reached.
535+
///
536+
/// If data has been spilled, transitions to `PreparingMergeInput` so the
537+
/// spilled and in-memory groups can be merged before output. Otherwise,
538+
/// starts output from the in-memory hash table and transitions to
539+
/// `ProducingOutput`.
540+
fn close_input_and_prepare_output(
541+
&mut self,
542+
mut hash_table: AggregateHashTable<SingleMarker>,
543+
spill_context: Option<Box<SingleSpillContext>>,
544+
) -> SingleHashAggregateStateTransition {
545+
self.close_input();
546+
match spill_context {
547+
Some(spill_context) if spill_context.has_spills() => {
548+
ControlFlow::Continue(SingleHashAggregateState::PreparingMergeInput {
549+
hash_table,
550+
spill_context,
551+
})
552+
}
553+
_ => {
554+
let elapsed_compute = self.baseline_metrics.elapsed_compute().clone();
555+
let timer = elapsed_compute.timer();
556+
let result = hash_table.start_output();
557+
timer.done();
558+
559+
match result {
560+
Ok(()) => {
561+
ControlFlow::Continue(SingleHashAggregateState::ProducingOutput {
562+
hash_table,
563+
})
516564
}
565+
Err(e) => Self::break_with_err(e),
517566
}
518567
}
519568
}

0 commit comments

Comments
 (0)