Skip to main content

AggregateOverloadBuilder

Struct AggregateOverloadBuilder 

Source
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

Source

pub fn new() -> Self

Creates a new AggregateOverloadBuilder with no parameters, no return type and no callbacks set.

Source

pub fn param(self, type_id: TypeId) -> Self

Adds a positional parameter to this overload.

For complex types like LIST(BIGINT), 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(...).

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Sets the update callback for this overload.

Source

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

Sets the combine callback for this overload.

Source

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

Sets the finalize callback for this overload.

Source

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.

Source

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.

Source

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
  • 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 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.

Trait Implementations§

Source§

impl Debug for AggregateOverloadBuilder

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for AggregateOverloadBuilder

Source§

fn default() -> Self

Returns the “default value” for a type. 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.