Skip to main content

quack_rs/aggregate/builder/
single.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6use std::ffi::CString;
7use std::os::raw::c_void;
8
9use libduckdb_sys::duckdb_delete_callback_t;
10
11use crate::aggregate::callbacks::{
12    CombineFn, DestroyFn, FinalizeFn, StateInitFn, StateSizeFn, UpdateFn,
13};
14use crate::error::ExtensionError;
15use crate::types::logical_type::SlotCheck;
16use crate::types::{LogicalType, NullHandling, TypeId};
17use crate::validate::validate_function_name;
18
19mod register;
20
21/// Builder for registering a single-signature `DuckDB` aggregate function.
22///
23/// # Known `DuckDB` limitation
24///
25/// **Before `DuckDB` 2.0.0, two query shapes make every C-API aggregate read
26/// out of bounds.** In them `DuckDB` calls `update` with a state array holding
27/// **one** state while
28/// passing `count > 1` rows, so the callback reads `states[1..count]` past the
29/// end of the array — undefined behaviour in *any* C-API aggregate, whether
30/// built with quack-rs or by hand:
31///
32/// - **Window aggregates whose frame is the whole partition**, e.g.
33///   `agg(x) OVER ()` or an explicit `ROWS BETWEEN UNBOUNDED PRECEDING AND
34///   UNBOUNDED FOLLOWING` frame (`OVER (PARTITION BY p)` without `ORDER BY`
35///   crashed on 1.4.4 only in the shapes tried) — `WindowConstantAggregator`
36///   (`src/function/window/window_constant_aggregator.cpp`, ~lines 106 and
37///   296–299 in `DuckDB` 1.5.5).
38/// - **Ordered aggregates**, e.g. `agg(x ORDER BY y)` —
39///   `src/function/aggregate/sorted_aggregate_function.cpp`, ~lines 630–633.
40///
41/// Both pass a `CONSTANT_VECTOR` of states because the function has no
42/// `simple_update` (the C API cannot set one), and `CAPIAggregateUpdate`
43/// (`src/main/capi/aggregate_function-c.cpp`, ~lines 92–110) hands the
44/// vector's data pointer to the extension without flattening it. This is a
45/// defect in `DuckDB`'s C API, not in quack-rs, and it cannot be detected
46/// from inside the callback — reading `states[1]` to check is itself the
47/// out-of-bounds read. Reported upstream as
48/// [duckdb/duckdb#26109](https://github.com/duckdb/duckdb/issues/26109).
49/// On `DuckDB` 1.4.x and 1.5.x, do not use C-API aggregates in those two
50/// query shapes.
51///
52/// **Fixed in `DuckDB` 2.0.0:** `CAPIAggregateUpdate` flattens a non-flat
53/// state vector into one state pointer per row before calling `update`
54/// (`src/main/capi/v1/aggregate_function-c.cpp`, lines 104–108 at v2.0.0).
55/// Both shapes then give the right answer, and a plain C aggregate runs them
56/// clean under Valgrind; on 1.5.6 the same program segfaults.
57///
58/// # Pitfall L6
59///
60/// Unlike `duckdb_register_aggregate_function`, this builder also handles
61/// the case where you later want to convert to a function set — it sets the
62/// function name correctly.
63///
64/// # Example
65///
66/// ```rust,no_run
67/// use quack_rs::aggregate::AggregateFunctionBuilder;
68/// use quack_rs::types::TypeId;
69/// use libduckdb_sys::{duckdb_connection, duckdb_function_info, duckdb_aggregate_state,
70///                     duckdb_data_chunk, duckdb_vector, idx_t};
71///
72/// unsafe extern "C" fn state_size(_: duckdb_function_info) -> idx_t { 8 }
73/// unsafe extern "C" fn state_init(_: duckdb_function_info, _: duckdb_aggregate_state) {}
74/// unsafe extern "C" fn update(
75///     _: duckdb_function_info,
76///     _: duckdb_data_chunk,
77///     _: *mut duckdb_aggregate_state,
78/// ) {}
79/// unsafe extern "C" fn combine(
80///     _: duckdb_function_info,
81///     _: *mut duckdb_aggregate_state,
82///     _: *mut duckdb_aggregate_state,
83///     _: idx_t,
84/// ) {}
85/// unsafe extern "C" fn finalize(
86///     _: duckdb_function_info,
87///     _: *mut duckdb_aggregate_state,
88///     _: duckdb_vector,
89///     _: idx_t,
90///     _: idx_t,
91/// ) {}
92///
93/// /// # Safety
94/// ///
95/// /// `con` must be a valid, open connection.
96/// unsafe fn register(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
97///     // SAFETY: `con` is valid per this function's contract.
98///     unsafe {
99///         AggregateFunctionBuilder::new("word_count")
100///             .param(TypeId::Varchar)
101///             .returns(TypeId::BigInt)
102///             .state_size(state_size)
103///             .init(state_init)
104///             .update(update)
105///             .combine(combine)
106///             .finalize(finalize)
107///             .register(con)
108///     }
109/// }
110/// ```
111#[must_use]
112pub struct AggregateFunctionBuilder {
113    pub(super) name: CString,
114    pub(super) params: Vec<TypeId>,
115    pub(super) logical_params: Vec<(usize, LogicalType)>,
116    pub(super) return_type: Option<TypeId>,
117    pub(super) return_logical: Option<LogicalType>,
118    pub(super) state_size: Option<StateSizeFn>,
119    pub(super) init: Option<StateInitFn>,
120    pub(super) update: Option<UpdateFn>,
121    pub(super) combine: Option<CombineFn>,
122    pub(super) finalize: Option<FinalizeFn>,
123    pub(super) destructor: Option<DestroyFn>,
124    pub(super) null_handling: NullHandling,
125    pub(super) extra_info: Option<crate::extra_info::ExtraInfo>,
126}
127
128impl AggregateFunctionBuilder {
129    /// Creates a new builder for an aggregate function with the given name.
130    ///
131    /// # Panics
132    ///
133    /// Panics if `name` contains an interior null byte.
134    pub fn new(name: &str) -> Self {
135        Self {
136            name: CString::new(name).expect("function name must not contain null bytes"),
137            params: Vec::new(),
138            logical_params: Vec::new(),
139            return_type: None,
140            return_logical: None,
141            state_size: None,
142            init: None,
143            update: None,
144            combine: None,
145            finalize: None,
146            destructor: None,
147            null_handling: NullHandling::DefaultNullHandling,
148            extra_info: None,
149        }
150    }
151
152    /// Creates a new builder with function name validation.
153    ///
154    /// Unlike [`new`][Self::new], this method validates the function name against
155    /// `DuckDB` naming conventions and returns an error instead of panicking.
156    ///
157    /// # Errors
158    ///
159    /// Returns `ExtensionError` if the name is empty, too long, contains invalid
160    /// characters, or does not start with a lowercase letter or underscore.
161    pub fn try_new(name: &str) -> Result<Self, ExtensionError> {
162        validate_function_name(name)?;
163        let c_name = CString::new(name)
164            .map_err(|_| ExtensionError::new("function name contains interior null byte"))?;
165        Ok(Self {
166            name: c_name,
167            params: Vec::new(),
168            logical_params: Vec::new(),
169            return_type: None,
170            return_logical: None,
171            state_size: None,
172            init: None,
173            update: None,
174            combine: None,
175            finalize: None,
176            destructor: None,
177            null_handling: NullHandling::DefaultNullHandling,
178            extra_info: None,
179        })
180    }
181
182    /// Returns the function name.
183    ///
184    /// Useful for introspection and for [`MockRegistrar`][crate::testing::MockRegistrar].
185    pub fn name(&self) -> &str {
186        self.name.to_str().unwrap_or("")
187    }
188
189    /// Adds a positional parameter with the given type.
190    ///
191    /// Call this once per parameter in order. For complex types like
192    /// `LIST(BIGINT)` or `MAP(VARCHAR, INTEGER)`, use [`param_logical`][Self::param_logical].
193    pub fn param(mut self, type_id: TypeId) -> Self {
194        self.params.push(type_id);
195        self
196    }
197
198    /// Adds a positional parameter with a complex [`LogicalType`].
199    ///
200    /// Use this for parameterized types that [`TypeId`] cannot express, such as
201    /// `LIST(BIGINT)`, `MAP(VARCHAR, INTEGER)`, or `STRUCT(...)`.
202    ///
203    /// The parameter position is determined by the total number of `param` and
204    /// `param_logical` calls made so far.
205    ///
206    /// # Example
207    ///
208    /// ```rust,no_run
209    /// use quack_rs::aggregate::AggregateFunctionBuilder;
210    /// use quack_rs::types::{LogicalType, TypeId};
211    ///
212    /// // fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
213    /// //     AggregateFunctionBuilder::new("my_func")
214    /// //         .param(TypeId::Varchar)
215    /// //         .param_logical(LogicalType::list(TypeId::BigInt))
216    /// //         .returns(TypeId::BigInt)
217    /// //         // ... callbacks ...
218    /// //         ;
219    /// //     Ok(())
220    /// // }
221    /// ```
222    #[cfg_attr(test, mutants::skip)] // position arithmetic tested via E2E
223    pub fn param_logical(mut self, logical_type: LogicalType) -> Self {
224        let position = self.params.len() + self.logical_params.len();
225        self.logical_params.push((position, logical_type));
226        self
227    }
228
229    /// Sets the return type for this function.
230    ///
231    /// For complex return types like `LIST(BIGINT)`, use
232    /// [`returns_logical`][Self::returns_logical] instead.
233    pub const fn returns(mut self, type_id: TypeId) -> Self {
234        self.return_type = Some(type_id);
235        self
236    }
237
238    /// Sets the return type to a complex [`LogicalType`].
239    ///
240    /// Use this for parameterized return types that [`TypeId`] cannot express,
241    /// such as `LIST(BOOLEAN)`, `LIST(TIMESTAMP)`, `MAP(VARCHAR, INTEGER)`, etc.
242    ///
243    /// If both `returns` and `returns_logical` are called, the logical type takes
244    /// precedence.
245    ///
246    /// # Example
247    ///
248    /// ```rust,no_run
249    /// use quack_rs::aggregate::AggregateFunctionBuilder;
250    /// use quack_rs::types::{LogicalType, TypeId};
251    ///
252    /// // fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
253    /// //     AggregateFunctionBuilder::new("retention")
254    /// //         .param(TypeId::Boolean)
255    /// //         .param(TypeId::Boolean)
256    /// //         .returns_logical(LogicalType::list(TypeId::Boolean))
257    /// //         // ... callbacks ...
258    /// //         ;
259    /// //     Ok(())
260    /// // }
261    /// ```
262    pub fn returns_logical(mut self, logical_type: LogicalType) -> Self {
263        self.return_logical = Some(logical_type);
264        self
265    }
266
267    /// Installs [`FfiState<T>`][crate::aggregate::FfiState]'s `state_size`,
268    /// `init` and `destructor` callbacks together, so they cannot describe
269    /// different states (setting them one by one, a size callback for one `T`
270    /// with an init callback for another wrote past `DuckDB`'s allocation).
271    /// `update`, `combine` and `finalize` still read the state through
272    /// `FfiState::<T>::with_state` / `with_state_mut` with the same `T`.
273    pub fn ffi_state<T: crate::aggregate::AggregateState>(self) -> Self {
274        self.state_size(crate::aggregate::FfiState::<T>::size_callback)
275            .init(crate::aggregate::FfiState::<T>::init_callback)
276            .destructor(crate::aggregate::FfiState::<T>::destroy_callback)
277    }
278
279    /// Sets the `state_size` callback.
280    ///
281    /// The `state_size`, `init` and `destructor` callbacks must describe the
282    /// same state: `DuckDB` allocates what `state_size` returns and hands that
283    /// allocation to `init` and, later, to `destructor` and the other
284    /// callbacks. [`FfiState<A>`][crate::aggregate::FfiState]'s size callback
285    /// with `FfiState<B>`'s init callback writes a `B` into space sized for an
286    /// `A`, past the allocation when `B` is larger. Prefer
287    /// [`ffi_state`][Self::ffi_state], which installs all three for one `T`.
288    pub fn state_size(mut self, f: StateSizeFn) -> Self {
289        self.state_size = Some(f);
290        self
291    }
292
293    /// Sets the `state_init` callback.
294    ///
295    /// The `state_size`, `init` and `destructor` callbacks must describe the
296    /// same state: `DuckDB` allocates what `state_size` returns and hands that
297    /// allocation to `init` and, later, to `destructor` and the other
298    /// callbacks. [`FfiState<A>`][crate::aggregate::FfiState]'s size callback
299    /// with `FfiState<B>`'s init callback writes a `B` into space sized for an
300    /// `A`, past the allocation when `B` is larger. Prefer
301    /// [`ffi_state`][Self::ffi_state], which installs all three for one `T`.
302    pub fn init(mut self, f: StateInitFn) -> Self {
303        self.init = Some(f);
304        self
305    }
306
307    /// Sets the `update` callback.
308    pub fn update(mut self, f: UpdateFn) -> Self {
309        self.update = Some(f);
310        self
311    }
312
313    /// Sets the `combine` callback.
314    pub fn combine(mut self, f: CombineFn) -> Self {
315        self.combine = Some(f);
316        self
317    }
318
319    /// Sets the `finalize` callback.
320    pub fn finalize(mut self, f: FinalizeFn) -> Self {
321        self.finalize = Some(f);
322        self
323    }
324
325    /// Sets the optional `destructor` callback.
326    ///
327    /// Required when you use [`FfiState<T>`][crate::aggregate::FfiState]: its
328    /// `destroy_callback` is what drops each `T`.
329    ///
330    /// When none is set, `register` installs a no-op destructor rather than
331    /// none at all. `DuckDB` evaluates an aggregate without a state destructor
332    /// as a *streaming* window for running frames
333    /// (`agg(x) OVER (ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)`), and
334    /// through the C API that path feeds `update` the first row of each chunk
335    /// in place of every later one — a wrong answer with no error (Pitfall
336    /// L13). The cost is the streaming shortcut: such windows are evaluated by
337    /// `DuckDB`'s general window operator instead.
338    pub fn destructor(mut self, f: DestroyFn) -> Self {
339        self.destructor = Some(f);
340        self
341    }
342
343    /// Sets the NULL handling behaviour for this aggregate function.
344    ///
345    /// This does **not** decide whether `update` sees NULL rows: it receives
346    /// every row under either setting, so an aggregate that ignores NULLs must
347    /// skip rows whose
348    /// [`VectorReader::is_valid`][crate::vector::VectorReader::is_valid] is
349    /// false. [`SpecialNullHandling`][NullHandling::SpecialNullHandling]
350    /// declares that the aggregate may return non-NULL for NULL input; see
351    /// [`NullHandling`] for the one planner decision that reads it.
352    pub const fn null_handling(mut self, handling: NullHandling) -> Self {
353        self.null_handling = handling;
354        self
355    }
356
357    /// Attaches arbitrary data to this aggregate function.
358    ///
359    /// The data pointer is available inside callbacks via
360    /// `duckdb_aggregate_function_get_extra_info`. The `destroy` callback is
361    /// called by `DuckDB` when the function is dropped to free the data.
362    ///
363    /// # Safety
364    ///
365    /// - `data` must stay valid until `destroy` frees it (with no `destroy`,
366    ///   for as long as the database lives), and `destroy` must be able to
367    ///   free it exactly once with no one else freeing it — so one pointer
368    ///   must not be given to two builders or overloads, each of which hands
369    ///   its `destroy` to `DuckDB` separately.
370    /// - The pointee must be `Send + Sync`. `DuckDB` hands the same pointer to
371    ///   the callbacks on every thread that executes the function, possibly at
372    ///   the same moment, and `destroy` runs on whichever thread releases the
373    ///   function — or, if the builder is dropped unregistered, the thread
374    ///   that drops it.
375    /// - `destroy` must not unwind: it is an `extern "C" fn`, so a panic
376    ///   escaping it aborts the process. Wrap a body that can panic in
377    ///   [`catch_ffi_panic`][crate::callback::catch_ffi_panic].
378    ///
379    /// The typical pattern is to box your data:
380    /// `Box::into_raw(Box::new(my_data)).cast()`.
381    pub unsafe fn extra_info(
382        mut self,
383        data: *mut c_void,
384        destroy: duckdb_delete_callback_t,
385    ) -> Self {
386        // SAFETY: forwarded from this method's own contract.
387        self.extra_info = Some(unsafe { crate::extra_info::ExtraInfo::new(data, destroy) });
388        self
389    }
390
391    /// Attaches `value` as this function's extra info: the safe, typed form
392    /// of [`extra_info`][Self::extra_info].
393    ///
394    /// quack-rs boxes `value` behind a type tag and generates its destructor,
395    /// which contains a panic in `T::drop` and runs once — when `DuckDB`
396    /// releases the function, or when this builder is dropped unregistered.
397    /// Read it in a callback with
398    /// [`AggregateFunctionInfo::extra_info_ref`][crate::aggregate::AggregateFunctionInfo::extra_info_ref],
399    /// which returns `None` for any other type instead of reinterpreting
400    /// memory. `T` is `Send + Sync` because every thread running the function
401    /// reads the same value.
402    ///
403    /// # Example
404    ///
405    /// ```rust,no_run
406    /// use quack_rs::aggregate::{AggregateFunctionBuilder, AggregateFunctionInfo};
407    ///
408    /// struct Scale(f64);
409    ///
410    /// let builder = AggregateFunctionBuilder::new("scaled_sum").extra_info_typed(Scale(2.5));
411    /// # drop(builder);
412    ///
413    /// // In `finalize`:
414    /// fn scale(info: &AggregateFunctionInfo) -> f64 {
415    ///     // SAFETY: this function's extra info is only ever set with `extra_info_typed`.
416    ///     unsafe { info.extra_info_ref::<Scale>() }.map_or(1.0, |s| s.0)
417    /// }
418    /// ```
419    pub fn extra_info_typed<T: Send + Sync + 'static>(self, value: T) -> Self {
420        let (data, destroy) = crate::extra_info::into_tagged(value);
421        // SAFETY: `into_tagged` returns a fresh allocation, used by no one
422        // else, and the destructor that frees it exactly once without
423        // unwinding; `T: Send + Sync`.
424        unsafe { self.extra_info(data, Some(destroy)) }
425    }
426
427    /// The completeness checks that need no `DuckDB` call: a return type and
428    /// the five required callbacks. [`MockRegistrar`][crate::testing::MockRegistrar]
429    /// runs them too, so a builder it accepts is not refused at `LOAD` for a
430    /// missing part.
431    pub(crate) fn check_parts(&self) -> Result<(), ExtensionError> {
432        if self.return_type.is_none() && self.return_logical.is_none() {
433            return Err(ExtensionError::new("return type not set"));
434        }
435        let missing = [
436            ("state_size", self.state_size.is_none()),
437            ("init", self.init.is_none()),
438            ("update", self.update.is_none()),
439            ("combine", self.combine.is_none()),
440            ("finalize", self.finalize.is_none()),
441        ]
442        .into_iter()
443        .find_map(|(name, absent)| absent.then_some(name));
444        if let Some(callback) = missing {
445            return Err(ExtensionError::new(format!("{callback} callback not set")));
446        }
447        // Last, so an incomplete builder is told what it lacks before it is told
448        // about its arity.
449        if self.params.is_empty() && self.logical_params.is_empty() {
450            let name = self.name.to_string_lossy();
451            return Err(super::zero_parameter_error(
452                &format!("aggregate function '{name}'"),
453                &name,
454            ));
455        }
456        Ok(())
457    }
458
459    /// Refuses a type [`register`][Self::register] refuses before its first
460    /// `DuckDB` call; `slot` checks each `TypeId` (see [`SlotCheck`]).
461    pub(crate) fn check_types(&self, slot: SlotCheck) -> Result<(), ExtensionError> {
462        for (i, id) in self.params.iter().enumerate() {
463            slot(*id, &format!("aggregate function parameter {i}"))?;
464        }
465        if let Some(id) = self.return_type {
466            slot(id, "aggregate function return type")?;
467        }
468        crate::table::type_check::refuse_any_return(
469            "aggregate function return type",
470            self.return_type,
471            self.return_logical.as_ref(),
472        )
473    }
474}
475
476impl core::fmt::Debug for AggregateFunctionBuilder {
477    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
478        use crate::debug_repr::Callback;
479        f.debug_struct("AggregateFunctionBuilder")
480            .field("name", &self.name)
481            .field("params", &self.params)
482            .field("logical_params", &self.logical_params.len())
483            .field("return_type", &self.return_type)
484            .field("return_logical", &self.return_logical)
485            .field("state_size", &Callback::of(&self.state_size))
486            .field("init", &Callback::of(&self.init))
487            .field("update", &Callback::of(&self.update))
488            .field("combine", &Callback::of(&self.combine))
489            .field("finalize", &Callback::of(&self.finalize))
490            .field("destructor", &Callback::of(&self.destructor))
491            .field("null_handling", &self.null_handling)
492            .field("extra_info", &Callback::of(&self.extra_info))
493            .finish()
494    }
495}