Expand description
Type aliases for the five required DuckDB aggregate callback signatures.
Import these type aliases when defining your callback functions to ensure you use the correct signature. A mismatch in any parameter type is a silent bug that is extremely difficult to debug.
§The five required callbacks
Every DuckDB aggregate function requires exactly these five callbacks
(plus an optional Destructor):
| Callback | When called | Purpose |
|---|---|---|
StateSizeFn | Whenever an operator sizes its state buffers — at least once per query that uses the aggregate, never at registration | Returns sizeof(FfiState) in bytes; must return the same value every time |
StateInitFn | Per state allocation, including every combine target | Initializes a fresh state |
UpdateFn | Per batch of input rows | Accumulates data from a chunk into the states |
CombineFn | Parallel merge, window segment trees | Merges source states into target states |
FinalizeFn | Per batch of result rows, with a count and an offset | Writes results from count states to the output vector starting at offset |
DestroyFn | After finalize, on the source states once combine has merged them, and, after a failed state_init, on states that were never initialised; not on some states a stopped scan (or, before DuckDB 2.0.0, an EXCLUDE window frame) leaves behind (see DestroyFn) | Frees per-state memory |
Sources (DuckDB 1.5.5): CAPIAggregateStateSize, CAPIAggregateFinalize
and CAPIAggregateDestructor in src/main/capi/aggregate_function-c.cpp;
the state-size calls in aggregate_object.cpp,
physical_ungrouped_aggregate.cpp and the window executors; and
LocalUngroupedAggregateState, whose states are destroyed after
GlobalUngroupedAggregateState::Combine has merged them
(physical_ungrouped_aggregate.cpp).
§Important: Array-of-pointers calling convention
The update, combine, and finalize callbacks receive
*mut duckdb_aggregate_state — a pointer to an array of state pointers.
§Pitfall: COMBINE must propagate ALL config fields
See the crate-level documentation for a worked example of this critical bug.
§Example
use quack_rs::aggregate::callbacks::{StateSizeFn, StateInitFn, UpdateFn, CombineFn, FinalizeFn, DestroyFn};
use libduckdb_sys::{duckdb_function_info, duckdb_aggregate_state, duckdb_data_chunk, duckdb_vector, idx_t};
unsafe extern "C" fn my_state_size(_: duckdb_function_info) -> idx_t { 8 }
unsafe extern "C" fn my_init(_: duckdb_function_info, _: duckdb_aggregate_state) {}
unsafe extern "C" fn my_update(_: duckdb_function_info, _: duckdb_data_chunk, _: *mut duckdb_aggregate_state) {}
unsafe extern "C" fn my_combine(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: *mut duckdb_aggregate_state, _: idx_t) {}
unsafe extern "C" fn my_finalize(_: duckdb_function_info, _: *mut duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
unsafe extern "C" fn my_destroy(_: *mut duckdb_aggregate_state, _: idx_t) {}
let _: StateSizeFn = my_state_size;
let _: StateInitFn = my_init;
let _: UpdateFn = my_update;
let _: CombineFn = my_combine;
let _: FinalizeFn = my_finalize;
let _: DestroyFn = my_destroy;Type Aliases§
- Combine
Fn - Merges source states into target states.
- Destroy
Fn - Frees memory allocated by
StateInitFn. - Finalize
Fn - Writes final results from aggregate states to the output vector.
- State
Init Fn - Initializes a freshly allocated aggregate state.
- State
Size Fn - Returns the size of the aggregate state struct in bytes.
- Update
Fn - Accumulates data from a chunk into the aggregate states.