pub struct AggregateOverloadBuilder { /* private fields */ }Expand description
A builder for one overload within an AggregateFunctionSetBuilder.
Obtain one either from the closure passed to
AggregateFunctionSetBuilder::overloads (one per arity in a range) or by
calling AggregateOverloadBuilder::new and handing it to
AggregateFunctionSetBuilder::overload.
§Return types
An overload may carry its own return type via returns or
returns_logical. DuckDB resolves an aggregate
overload from the parameter types and arity only — the return type takes
no part in resolution — so overloads in one set are free to return different
types, exactly as DuckDB’s own arg_max does:
arg_max(ANY, ANY) -> ANY
arg_max(ANY, ANY, ANY) -> ANY[]If an overload sets no return type, the set-level default from
AggregateFunctionSetBuilder::returns /
AggregateFunctionSetBuilder::returns_logical applies. Registration fails
if an overload has neither.
§Example
Two overloads under one name with different return types:
use quack_rs::aggregate::{AggregateFunctionSetBuilder, AggregateOverloadBuilder};
use quack_rs::types::TypeId;
// AggregateFunctionSetBuilder::new("my_agg")
// .overload(
// AggregateOverloadBuilder::new()
// .param(TypeId::Integer)
// .returns(TypeId::Integer)
// .state_size(int_state_size)
// .init(int_init)
// .update(int_update)
// .combine(int_combine)
// .finalize(int_finalize),
// )
// .overload(
// AggregateOverloadBuilder::new()
// .param(TypeId::Varchar)
// .returns(TypeId::Varchar)
// .state_size(str_state_size)
// .init(str_init)
// .update(str_update)
// .combine(str_combine)
// .finalize(str_finalize),
// )
// .register(con)Implementations§
Source§impl AggregateOverloadBuilder
impl AggregateOverloadBuilder
Sourcepub fn new() -> Self
pub fn new() -> Self
Creates a new AggregateOverloadBuilder with no parameters, no return
type and no callbacks set.
Sourcepub fn param(self, type_id: TypeId) -> Self
pub fn param(self, type_id: TypeId) -> Self
Adds a positional parameter to this overload.
For complex types like LIST(BIGINT), use
param_logical.
Sourcepub fn param_logical(self, logical_type: LogicalType) -> Self
pub fn param_logical(self, logical_type: LogicalType) -> Self
Adds a positional parameter with a complex LogicalType.
Use this for parameterized types that TypeId cannot express, such as
LIST(BIGINT), MAP(VARCHAR, INTEGER), or STRUCT(...).
Sourcepub const fn returns(self, type_id: TypeId) -> Self
pub const fn returns(self, type_id: TypeId) -> Self
Sets the return type for this overload only, overriding any set-level default.
For complex return types like LIST(BIGINT), use
returns_logical instead.
Sourcepub fn returns_logical(self, logical_type: LogicalType) -> Self
pub fn returns_logical(self, logical_type: LogicalType) -> Self
Sets the return type for this overload only to a complex
LogicalType, overriding any set-level default.
Use this for parameterized return types that TypeId cannot express,
such as LIST(BOOLEAN), MAP(VARCHAR, INTEGER), or STRUCT(...).
If both returns and returns_logical are called on the same overload,
the logical type takes precedence.
Sourcepub const fn ffi_state<T: AggregateState>(self) -> Self
pub const fn ffi_state<T: AggregateState>(self) -> Self
Installs FfiState<T>’s state_size,
init and destructor callbacks together, so they cannot describe
different states (setting them one by one, a size callback for one T
with an init callback for another wrote past DuckDB’s allocation).
update, combine and finalize still read the state through
FfiState::<T>::with_state / with_state_mut with the same T.
Sourcepub const fn state_size(self, f: StateSizeFn) -> Self
pub const fn state_size(self, f: StateSizeFn) -> Self
Sets the state_size callback for this overload.
The state_size, init and destructor callbacks must describe the
same state: DuckDB allocates what state_size returns and hands that
allocation to init and, later, to destructor and the other
callbacks. FfiState<A>’s size callback
with FfiState<B>’s init callback writes a B into space sized for an
A, past the allocation when B is larger. Prefer
ffi_state, which installs all three for one T.
Sourcepub const fn init(self, f: StateInitFn) -> Self
pub const fn init(self, f: StateInitFn) -> Self
Sets the init callback for this overload.
The state_size, init and destructor callbacks must describe the
same state: DuckDB allocates what state_size returns and hands that
allocation to init and, later, to destructor and the other
callbacks. FfiState<A>’s size callback
with FfiState<B>’s init callback writes a B into space sized for an
A, past the allocation when B is larger. Prefer
ffi_state, which installs all three for one T.
Sourcepub const fn finalize(self, f: FinalizeFn) -> Self
pub const fn finalize(self, f: FinalizeFn) -> Self
Sets the finalize callback for this overload.
Sourcepub const fn destructor(self, f: DestroyFn) -> Self
pub const fn destructor(self, f: DestroyFn) -> Self
Sets the optional destructor callback for this overload.
When none is set, register installs a no-op destructor rather than
none at all. DuckDB evaluates an aggregate without a state destructor
as a streaming window for running frames
(agg(x) OVER (ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)), and
through the C API that path feeds update the first row of each chunk
in place of every later one — a wrong answer with no error (Pitfall
L13). The cost is the streaming shortcut: such windows are evaluated by
DuckDB’s general window operator instead.
Sourcepub const fn null_handling(self, handling: NullHandling) -> Self
pub const fn null_handling(self, handling: NullHandling) -> Self
Sets the NULL handling behaviour for this overload.
This does not decide whether update sees NULL rows: it receives
every row under either setting, so an aggregate that ignores NULLs must
skip rows whose
VectorReader::is_valid is
false. SpecialNullHandling
declares that the aggregate may return non-NULL for NULL input; see
NullHandling for the one planner decision that reads it.
Sourcepub unsafe fn extra_info(
self,
data: *mut c_void,
destroy: duckdb_delete_callback_t,
) -> Self
pub unsafe fn extra_info( self, data: *mut c_void, destroy: duckdb_delete_callback_t, ) -> Self
Attaches arbitrary data to this overload.
Mirrors
AggregateFunctionBuilder::extra_info:
the pointer is available inside this overload’s callbacks via
AggregateFunctionInfo::get_extra_info,
and destroy frees it exactly once — by DuckDB once registration has
handed it over (whether or not registration then succeeds), or by the
builder if it is dropped, or registration is rejected, before that.
§Safety
datamust stay valid untildestroyfrees it (with nodestroy, for as long as the database lives), anddestroymust be able to free it exactly once with no one else freeing it — so one pointer must not be given to two builders or overloads, each of which hands itsdestroytoDuckDBseparately.- The pointee must be
Send + Sync.DuckDBhands the same pointer to the callbacks on every thread that executes the function, possibly at the same moment, anddestroyruns on whichever thread releases the function — or, if the builder is dropped unregistered, the thread that drops it. destroymust not unwind: it is anextern "C" fn, so a panic escaping it aborts the process. Wrap a body that can panic incatch_ffi_panic.
The typical pattern is to box your data:
Box::into_raw(Box::new(my_data)).cast().
Sourcepub fn extra_info_typed<T: Send + Sync + 'static>(self, value: T) -> Self
pub fn extra_info_typed<T: Send + Sync + 'static>(self, value: T) -> Self
Attaches value as this overload’s extra info: the safe, typed form
of extra_info, read back with
AggregateFunctionInfo::extra_info_ref.
See
AggregateFunctionBuilder::extra_info_typed
for the ownership and threading rules and an example.