Skip to main content

AggregateFunctionBuilder

Struct AggregateFunctionBuilder 

Source
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 explicit ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING frame (OVER (PARTITION BY p) without ORDER BY crashed on 1.4.4 only in the shapes tried) — WindowConstantAggregator (src/function/window/window_constant_aggregator.cpp, ~lines 106 and 296–299 in DuckDB 1.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

Source

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 a TypeId cannot express. Build it as a LogicalType and use the *_logical method; the error names the slot.
  • DuckDB reports 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
  • con must be a valid, open duckdb_connection.
  • The state_size, init and destructor callbacks, and the ones that read the state, must describe the same state; see ffi_state.
Source§

impl AggregateFunctionBuilder

Source

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.

Source

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.

Source

pub fn name(&self) -> &str

Returns the function name.

Useful for introspection and for MockRegistrar.

Source

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.

Source

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(())
// }
Source

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.

Source

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(())
// }
Source

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.

Source

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.

Source

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.

Source

pub fn update(self, f: UpdateFn) -> Self

Sets the update callback.

Source

pub fn combine(self, f: CombineFn) -> Self

Sets the combine callback.

Source

pub fn finalize(self, f: FinalizeFn) -> Self

Sets the finalize callback.

Source

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.

Source

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.

Source

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
  • data must stay valid until destroy frees it (with no destroy, for as long as the database lives), and destroy must 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 its destroy to DuckDB separately.
  • The pointee must be Send + Sync. DuckDB hands the same pointer to the callbacks on every thread that executes the function, possibly at the same moment, and destroy runs on whichever thread releases the function — or, if the builder is dropped unregistered, the thread that drops it.
  • destroy must not unwind: it is an extern "C" fn, so a panic escaping it aborts the process. Wrap a body that can panic in catch_ffi_panic.

The typical pattern is to box your data: Box::into_raw(Box::new(my_data)).cast().

Source

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)
}

Trait Implementations§

Source§

impl Debug for AggregateFunctionBuilder

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.