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}