This is an automated email from the ASF dual-hosted git repository.
zeroshade pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-go.git
The following commit(s) were added to refs/heads/main by this push:
new 4d5bd6aa docs(arrow/compute): say what MergeAll returns for no states
and where Ordered takes effect (#1338)
4d5bd6aa is described below
commit 4d5bd6aae022ec31f0f9d9b3f9953d459dd3611b
Author: singhpratech <[email protected]>
AuthorDate: Mon Oct 5 19:07:07 2026 -0400
docs(arrow/compute): say what MergeAll returns for no states and where
Ordered takes effect (#1338)
Follow-up to #1336, docs only.
The review noted two things worth a sentence in the comments:
- `MergeAll` returns `(nil, nil)` for an empty `states` slice, and a
caller reading "returns the state you then finalize" could finalize nil.
The comment now says so, and says what to do instead: aggregate the
empty input the way the executor does, one state from init, then
finalize.
- `Ordered` has no effect on the in-tree executor, which consumes the
whole input into a single state in order. The comment now says that it
is a contract for `MergeAll` and for callers that partition the input
themselves.
No code change. `gofmt`, `go vet` and `go test` on `arrow/compute` and
`arrow/compute/exec` are clean.
---
arrow/compute/exec/aggregate.go | 16 +++++++++++++---
1 file changed, 13 insertions(+), 3 deletions(-)
diff --git a/arrow/compute/exec/aggregate.go b/arrow/compute/exec/aggregate.go
index 439b7af9..a8abd880 100644
--- a/arrow/compute/exec/aggregate.go
+++ b/arrow/compute/exec/aggregate.go
@@ -141,9 +141,9 @@ type ScalarAggFinalize = func(ctx *KernelCtx)
(*AggregateResult, error)
// ScalarAggCleanup releases any resources held by an aggregate state. It is
// called exactly once for every state that the init function produced,
-// whether the aggregation succeeded, produced no result because the input was
-// empty, was cancelled, or failed in init, consume, merge or finalize. It
-// must not invalidate a result that finalize already returned.
+// whether the aggregation succeeded, saw no input, was cancelled, or failed in
+// init, consume, merge or finalize. It must not invalidate a result that
+// finalize already returned.
type ScalarAggCleanup = func(ctx *KernelCtx, state KernelState) error
// AggKernel builds on the base Kernel interface for aggregate execution
@@ -184,6 +184,11 @@ type ScalarAggKernel struct {
// for merging partitions in the logical order of the input. Kernels
// whose result does not depend on the order of the input leave this
// false.
+ //
+ // The executor in the compute package consumes the whole input into a
single
+ // state, in order, so the flag does not change what it does; it is a
+ // contract for MergeAll and for callers that partition the input
+ // themselves.
Ordered bool
}
@@ -250,6 +255,11 @@ var _ AggKernel = (*ScalarAggKernel)(nil)
// not the merge succeeded; on an error the first state is cleaned up as well
// and the returned state is nil, so that the caller never has to clean up a
// state MergeAll was given.
+//
+// With no states there is nothing to merge or to finalize, and MergeAll
+// returns (nil, nil). A caller that ended up with zero partitions aggregates
+// the empty input the way the executor does: create one state with the init
+// function and finalize it, then clean it up.
func MergeAll(kernel AggKernel, ctx *KernelCtx, states []KernelState)
(KernelState, error) {
if len(states) == 0 {
return nil, nil
