pub struct AggregateFunctionBuilder { /* private fields */ }Expand description
Builder for registering a single-signature DuckDB aggregate function.
§Known DuckDB limitation
Before DuckDB 2.0.0, two query shapes make every C-API aggregate read
out of bounds. In them DuckDB calls update with a state array holding
one state while
passing count > 1 rows, so the callback reads states[1..count] past the
end of the array — undefined behaviour in any C-API aggregate, whether
built with quack-rs or by hand:
- Window aggregates whose frame is the whole partition, e.g.
agg(x) OVER ()or an explicitROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWINGframe (OVER (PARTITION BY p)withoutORDER BYcrashed on 1.4.4 only in the shapes tried) —WindowConstantAggregator(src/function/window/window_constant_aggregator.cpp, ~lines 106 and 296–299 inDuckDB1.5.5). - Ordered aggregates, e.g.
agg(x ORDER BY y)—src/function/aggregate/sorted_aggregate_function.cpp, ~lines 630–633.
Both pass a CONSTANT_VECTOR of states because the function has no
simple_update (the C API cannot set one), and CAPIAggregateUpdate
(src/main/capi/aggregate_function-c.cpp, ~lines 92–110) hands the
vector’s data pointer to the extension without flattening it. This is a
defect in DuckDB’s C API, not in quack-rs, and it cannot be detected
from inside the callback — reading states[1] to check is itself the
out-of-bounds read. Reported upstream as
duckdb/duckdb#26109.
On DuckDB 1.4.x and 1.5.x, do not use C-API aggregates in those two
query shapes.
Fixed in DuckDB 2.0.0: CAPIAggregateUpdate flattens a non-flat
state vector into one state pointer per row before calling update
(src/main/capi/v1/aggregate_function-c.cpp, lines 104–108 at v2.0.0).
Both shapes then give the right answer, and a plain C aggregate runs them
clean under Valgrind; on 1.5.6 the same program segfaults.
§Pitfall L6
Unlike duckdb_register_aggregate_function, this builder also handles
the case where you later want to convert to a function set — it sets the
function name correctly.
§Example
use quack_rs::aggregate::AggregateFunctionBuilder;
use quack_rs::types::TypeId;
use libduckdb_sys::{duckdb_connection, duckdb_function_info, duckdb_aggregate_state,
duckdb_data_chunk, duckdb_vector, idx_t};
unsafe extern "C" fn state_size(_: duckdb_function_info) -> idx_t { 8 }
unsafe extern "C" fn state_init(_: duckdb_function_info, _: duckdb_aggregate_state) {}
unsafe extern "C" fn update(
_: duckdb_function_info,
_: duckdb_data_chunk,
_: *mut duckdb_aggregate_state,
) {}
unsafe extern "C" fn combine(
_: duckdb_function_info,
_: *mut duckdb_aggregate_state,
_: *mut duckdb_aggregate_state,
_: idx_t,
) {}
unsafe extern "C" fn finalize(
_: duckdb_function_info,
_: *mut duckdb_aggregate_state,
_: duckdb_vector,
_: idx_t,
_: idx_t,
) {}
/// # Safety
///
/// `con` must be a valid, open connection.
unsafe fn register(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
// SAFETY: `con` is valid per this function's contract.
unsafe {
AggregateFunctionBuilder::new("word_count")
.param(TypeId::Varchar)
.returns(TypeId::BigInt)
.state_size(state_size)
.init(state_init)
.update(update)
.combine(combine)
.finalize(finalize)
.register(con)
}
}Implementations§
Source§impl AggregateFunctionBuilder
impl AggregateFunctionBuilder
Sourcepub unsafe fn register(
self,
con: duckdb_connection,
) -> Result<(), ExtensionError>
pub unsafe fn register( self, con: duckdb_connection, ) -> Result<(), ExtensionError>
Registers the aggregate function on the given connection.
§Errors
Returns ExtensionError if:
- The return type was not set.
- Any required callback was not set.
- A parameter or return type was given as a bare composite
TypeId(DECIMAL,ENUM,LIST,STRUCT,MAP,ARRAY,UNION), which carries parameters aTypeIdcannot express. Build it as aLogicalTypeand use the*_logicalmethod; the error names the slot. DuckDBreports a registration failure.
§Name collisions
An aggregate can neither extend nor replace an existing catalog entry:
registration fails if the name is already taken by any scalar function,
aggregate function or macro, built-in or not — including an earlier
registration of this same aggregate. (DuckDB registers with
ALTER_ON_CONFLICT, and turning the create into an alter is not
implemented for aggregates: CreateInfo::GetAlterInfo throws.) The C
API reports only a failure, so after one quack-rs looks the name up in
duckdb_functions() and the error names the entry that holds it; a
registration that succeeds scans nothing.
§Safety
conmust be a valid, openduckdb_connection.- The
state_size,initanddestructorcallbacks, and the ones that read the state, must describe the same state; seeffi_state.
Source§impl AggregateFunctionBuilder
impl AggregateFunctionBuilder
Sourcepub fn new(name: &str) -> Self
pub fn new(name: &str) -> Self
Creates a new builder for an aggregate function with the given name.
§Panics
Panics if name contains an interior null byte.
Sourcepub fn try_new(name: &str) -> Result<Self, ExtensionError>
pub fn try_new(name: &str) -> Result<Self, ExtensionError>
Creates a new builder with function name validation.
Unlike new, this method validates the function name against
DuckDB naming conventions and returns an error instead of panicking.
§Errors
Returns ExtensionError if the name is empty, too long, contains invalid
characters, or does not start with a lowercase letter or underscore.
Sourcepub fn name(&self) -> &str
pub fn name(&self) -> &str
Returns the function name.
Useful for introspection and for MockRegistrar.
Sourcepub fn param(self, type_id: TypeId) -> Self
pub fn param(self, type_id: TypeId) -> Self
Adds a positional parameter with the given type.
Call this once per parameter in order. For complex types like
LIST(BIGINT) or MAP(VARCHAR, INTEGER), 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(...).
The parameter position is determined by the total number of param and
param_logical calls made so far.
§Example
use quack_rs::aggregate::AggregateFunctionBuilder;
use quack_rs::types::{LogicalType, TypeId};
// fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
// AggregateFunctionBuilder::new("my_func")
// .param(TypeId::Varchar)
// .param_logical(LogicalType::list(TypeId::BigInt))
// .returns(TypeId::BigInt)
// // ... callbacks ...
// ;
// Ok(())
// }Sourcepub const fn returns(self, type_id: TypeId) -> Self
pub const fn returns(self, type_id: TypeId) -> Self
Sets the return type for this function.
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 to a complex LogicalType.
Use this for parameterized return types that TypeId cannot express,
such as LIST(BOOLEAN), LIST(TIMESTAMP), MAP(VARCHAR, INTEGER), etc.
If both returns and returns_logical are called, the logical type takes
precedence.
§Example
use quack_rs::aggregate::AggregateFunctionBuilder;
use quack_rs::types::{LogicalType, TypeId};
// fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
// AggregateFunctionBuilder::new("retention")
// .param(TypeId::Boolean)
// .param(TypeId::Boolean)
// .returns_logical(LogicalType::list(TypeId::Boolean))
// // ... callbacks ...
// ;
// Ok(())
// }Sourcepub fn ffi_state<T: AggregateState>(self) -> Self
pub 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 fn state_size(self, f: StateSizeFn) -> Self
pub fn state_size(self, f: StateSizeFn) -> Self
Sets the state_size callback.
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 fn init(self, f: StateInitFn) -> Self
pub fn init(self, f: StateInitFn) -> Self
Sets the state_init callback.
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 fn finalize(self, f: FinalizeFn) -> Self
pub fn finalize(self, f: FinalizeFn) -> Self
Sets the finalize callback.
Sourcepub fn destructor(self, f: DestroyFn) -> Self
pub fn destructor(self, f: DestroyFn) -> Self
Sets the optional destructor callback.
Required when you use FfiState<T>: its
destroy_callback is what drops each T.
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 aggregate function.
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 aggregate function.
The data pointer is available inside callbacks via
duckdb_aggregate_function_get_extra_info. The destroy callback is
called by DuckDB when the function is dropped to free the data.
§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 function’s extra info: the safe, typed form
of extra_info.
quack-rs boxes value behind a type tag and generates its destructor,
which contains a panic in T::drop and runs once — when DuckDB
releases the function, or when this builder is dropped unregistered.
Read it in a callback with
AggregateFunctionInfo::extra_info_ref,
which returns None for any other type instead of reinterpreting
memory. T is Send + Sync because every thread running the function
reads the same value.
§Example
use quack_rs::aggregate::{AggregateFunctionBuilder, AggregateFunctionInfo};
struct Scale(f64);
let builder = AggregateFunctionBuilder::new("scaled_sum").extra_info_typed(Scale(2.5));
// In `finalize`:
fn scale(info: &AggregateFunctionInfo) -> f64 {
// SAFETY: this function's extra info is only ever set with `extra_info_typed`.
unsafe { info.extra_info_ref::<Scale>() }.map_or(1.0, |s| s.0)
}