Skip to content

refactor(hash-aggr): Support spilling for partial and final mode aggregation - #24061

Draft
2010YOUY01 wants to merge 1 commit into
apache:mainfrom
2010YOUY01:split-aggr-spill-partial-final
Draft

refactor(hash-aggr): Support spilling for partial and final mode aggregation#24061
2010YOUY01 wants to merge 1 commit into
apache:mainfrom
2010YOUY01:split-aggr-spill-partial-final

Conversation

@2010YOUY01

Copy link
Copy Markdown
Contributor

Which issue does this PR close?

Part of #22710

Rationale for this change

This PR adds existing spilling feature into the new 2-staged (partial and final) aggregation. The high-level implementation idea is the same as the legacy implementation.

For the algorithm description for this feature, see top comment change at datafusion/physical-plan/src/aggregates/hash_stream.rs

What changes are included in this PR?

The key changes to the operator state machine are:
In file datafusion/physical-plan/src/aggregates/hash_stream.rs

  • PartialHashAggregateStream::poll_next()
  • FinalHashAggregateStream::poll_next()

Use this as the starting point, you can navigate to all the related changes, for example adding new states to implement larger-than-memory execution.

Are these changes tested?

Existing tests

  • TODO for myself: double check the codecov

Are there any user-facing changes?

No

@2010YOUY01 2010YOUY01 changed the title feat: implement spilling for migrated partial/final hash aggregation refactor(hash-aggr): Support spilling for partial and final mode aggregation Aug 3, 2026
/// into an ordered streaming aggregation, which ensures bounded memory usage and
/// evaluates the final result.
/// - [`OrderedFinalAggregateStream`] is reused for the streaming aggregation.
pub(crate) struct PartialHashAggregateStream {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could put partial and final stream to two different files, I plan to this after this PR.

| 3 | 1 | 2.0 |
| 3 | 2 | 5.0 |
| 4 | 3 | 11.0 |
| 4 | 1 | 4.0 |

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

they're both valid partial aggregation output, due to early emitting under memory limit.

// enlarge memory limit to let the final aggregation finish
new_spill_ctx(2, 2600)
// Enlarge the memory limit enough to replay spilled states.
new_spill_ctx(2, 4640)

@2010YOUY01 2010YOUY01 Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The legacy implementation underestimate the memory usage somehow, so here it relaxes the memory budget needs further invstigation


assert_eq!(3, output_rows);
if spill {
// When spilling, the output rows metrics become partial output size + final output size

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a bug in the legacy implementation. Final aggregation should return the same output_rows regardless of the spilling condition.

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 83.89831% with 76 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.88%. Comparing base (21ad189) to head (3066f51).
⚠️ Report is 3 commits behind head on main.

Files with missing lines Patch % Lines
...fusion/physical-plan/src/aggregates/hash_stream.rs 83.94% 64 Missing and 11 partials ⚠️
datafusion/physical-plan/src/aggregates/mod.rs 80.00% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@           Coverage Diff            @@
##             main   #24061    +/-   ##
========================================
  Coverage   80.88%   80.88%            
========================================
  Files        1101     1101            
  Lines      375720   376048   +328     
  Branches   375720   376048   +328     
========================================
+ Hits       303895   304164   +269     
- Misses      53729    53774    +45     
- Partials    18096    18110    +14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@2010YOUY01
2010YOUY01 marked this pull request as draft August 3, 2026 11:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants