Skip to content

feat: add spill-backed sorting and aggregation#377

Merged
KKould merged 10 commits into
mainfrom
feat/spill
Jul 20, 2026
Merged

feat: add spill-backed sorting and aggregation#377
KKould merged 10 commits into
mainfrom
feat/spill

Conversation

@KKould

@KKould KKould commented Jul 20, 2026

Copy link
Copy Markdown
Member

What problem does this PR solve?

Sort and aggregation currently need to keep their working rows in memory, and equi-join implementation selection always prefers HashJoin. This makes large ORDER BY, GROUP BY, and DISTINCT workloads more memory-sensitive, and leaves no SQL-level escape hatch for forcing a bounded-memory aggregate or nested-loop join plan.

Issue link: N/A

What is changed and how it works?

  • Adds an optional spill feature with a spill-file backed SpillVec and codec support for temporary executor rows.
  • Uses a spill-backed ExternalSort when the spill feature is enabled, including sorted segments and merge passes.
  • Adds StreamAggregate and generalizes ordered-input optimization so DISTINCT and grouped aggregation can reuse existing ordering.
  • Adds the FORCE_AGG_SPILL optimizer hint, routing grouped aggregates and distinct aggregates through ordered stream execution and inserting a Sort only when the input is not already ordered.
  • Adds the FORCE_NEST_LOOP_JOIN optimizer hint to override equi-join HashJoin selection when needed.
  • Documents the spill feature and optimizer hints, and enables spill coverage in sqllogictest.

Code changes

  • Has Rust code change
  • Has CI related scripts change

Check List

Tests

  • Unit test
  • Integration test
  • Manual test (add detailed scripts or steps below)
  • No code

The coverage includes SpillVec and codec behavior, external sort segment/merge correctness, stream aggregate and distinct planning/results, forced aggregate spill planning/results, and forced nested-loop join Explain coverage.

Side effects

  • Performance regression: Consumes more CPU
  • Performance regression: Consumes more Memory
  • Breaking backward compatibility

Note for reviewer

The spill-backed sort path is gated by the spill feature and remains unavailable for wasm. FORCE_AGG_SPILL first reuses existing ordered input when possible, so it only adds an explicit Sort for unordered aggregate inputs.

@KKould KKould self-assigned this Jul 20, 2026
@KKould KKould added the enhancement New feature or request label Jul 20, 2026
@codecov

codecov Bot commented Jul 20, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.64879% with 50 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.91%. Comparing base (3f0df6f) to head (506bd78).

Files with missing lines Patch % Lines
src/execution/dql/external_sort.rs 96.17% 12 Missing ⚠️
src/optimizer/rule/normalization/elimination.rs 92.48% 10 Missing ⚠️
src/binder/parser.rs 90.41% 7 Missing ⚠️
src/execution/spill/mod.rs 98.75% 6 Missing ⚠️
src/execution/dql/aggregate/mod.rs 84.37% 5 Missing ⚠️
src/execution/dql/aggregate/stream_agg.rs 98.00% 3 Missing ⚠️
src/orm/mod.rs 76.92% 3 Missing ⚠️
src/parser/mod.rs 77.77% 2 Missing ⚠️
src/execution/dql/sort.rs 98.00% 1 Missing ⚠️
src/optimizer/rule/implementation/dql/join.rs 66.66% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #377      +/-   ##
==========================================
+ Coverage   92.85%   92.91%   +0.05%     
==========================================
  Files         249      253       +4     
  Lines       41844    43141    +1297     
==========================================
+ Hits        38856    40084    +1228     
- Misses       2988     3057      +69     
Flag Coverage Δ
rust 92.91% <96.64%> (+0.05%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/binder/aggregate.rs 97.48% <100.00%> (+<0.01%) ⬆️
src/binder/distinct.rs 98.48% <100.00%> (+0.01%) ⬆️
src/binder/mod.rs 85.58% <100.00%> (+0.06%) ⬆️
src/binder/select.rs 94.31% <100.00%> (+0.01%) ⬆️
src/db.rs 92.96% <ø> (+0.05%) ⬆️
src/errors.rs 98.55% <ø> (ø)
src/execution/dql/aggregate/hash_agg.rs 98.42% <100.00%> (+3.06%) ⬆️
src/execution/dql/aggregate/stream_distinct.rs 97.54% <100.00%> (+0.03%) ⬆️
src/execution/dql/join/hash_join.rs 97.05% <100.00%> (+0.02%) ⬆️
src/execution/dql/join/nested_loop_join.rs 97.90% <100.00%> (-0.32%) ⬇️
... and 27 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@KKould
KKould merged commit b0dbc30 into main Jul 20, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant