docs: missing documentation for aggregate _STATE combinator

Open Beginner friendly
#3,266 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
Half a day
Newbie friendliness
76/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
rust
Domain
documentation

Research direction

Start with the existing combinator documentation at docs/en/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-combinators.md, then read the registration in src/query/functions/src/aggregates/aggregator.rs and implementation in src/query/functions/src/aggregates/adaptors/aggregate_combinator_state.rs. Document the _state suffix, serialized binary return type, partial-aggregation use cases, example queries, and its relationship to _merge or finalization; done means the behavior is clear to SQL users.

Written by the indexing model from the issue text.

Description

documentation

Summary

Databend registers a _state aggregate combinator suffix that allows any aggregate function to return its intermediate serialized state instead of the final result. This combinator is completely undocumented.

Source

File: src/query/functions/src/aggregates/aggregator.rs

Registration (line ~199):

factory.register_combinator("_state", AggregateStateCombinator::combinator_desc());

Implementation: src/query/functions/src/aggregates/adaptors/aggregate_combinator_state.rs

The combinator wraps any aggregate function and changes its return type to the serialized binary state of that aggregate (via serialize_data_type()), enabling incremental/partial aggregation workflows.

What it does

Appending _state to any aggregate function name returns the intermediate binary state of that aggregate rather than the final computed value. This is useful for:

  • Storing partial aggregation results for later merging
  • Implementing two-phase aggregation pipelines
  • Passing aggregate state between queries

Example:

-- Returns the intermediate binary state of SUM, not the final sum
SELECT sum_state(number) FROM numbers(10);

-- The state can later be merged/finalized
SELECT sum_merge(state_col) FROM partial_results;

Suggested doc location

docs/en/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-combinators.md

Or a dedicated page covering all three combinators (_if, _distinct, _state) as a general concept. The page should cover:

  • How the _state suffix works
  • Return type (serialized binary aggregate state)
  • Use cases (partial aggregation, incremental computation)
  • Example queries
  • Relationship to _merge / finalization patterns
Dominant language
TypeScript
Stars
17
Forks
44
Avg merge
2d 7m
Merged PRs (30d)
4

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from databendlabs/databend-docs

All issues in databendlabs/databend-docs

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.