Skip to main content

Module callbacks

Module callbacks 

Source
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):

CallbackWhen calledPurpose
StateSizeFnWhenever an operator sizes its state buffers — at least once per query that uses the aggregate, never at registrationReturns sizeof(FfiState) in bytes; must return the same value every time
StateInitFnPer state allocation, including every combine targetInitializes a fresh state
UpdateFnPer batch of input rowsAccumulates data from a chunk into the states
CombineFnParallel merge, window segment treesMerges source states into target states
FinalizeFnPer batch of result rows, with a count and an offsetWrites results from count states to the output vector starting at offset
DestroyFnAfter 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§

CombineFn
Merges source states into target states.
DestroyFn
Frees memory allocated by StateInitFn.
FinalizeFn
Writes final results from aggregate states to the output vector.
StateInitFn
Initializes a freshly allocated aggregate state.
StateSizeFn
Returns the size of the aggregate state struct in bytes.
UpdateFn
Accumulates data from a chunk into the aggregate states.