Skip to main content

quack_rs/aggregate/
mod.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
6//! Builders for registering `DuckDB` aggregate functions.
7//!
8//! This module provides two builder types:
9//!
10//! - [`AggregateFunctionBuilder`]: Register a single aggregate function with
11//!   one fixed signature. Supports complex parameter types via
12//!   [`param_logical`][AggregateFunctionBuilder::param_logical] and complex
13//!   return types via [`returns_logical`][AggregateFunctionBuilder::returns_logical].
14//! - [`AggregateFunctionSetBuilder`]: Register a function set — several
15//!   overloads under one name, differing in arity (the variadic case, since
16//!   `DuckDB` has no aggregate varargs), in parameter types, or in **return
17//!   type**. `DuckDB` resolves an overload from its parameter types and arity
18//!   alone, so each may return something different. Set it per overload with
19//!   [`AggregateOverloadBuilder::returns`] /
20//!   [`returns_logical`][AggregateOverloadBuilder::returns_logical], or once on
21//!   the set as a default via
22//!   [`AggregateFunctionSetBuilder::returns_logical`]. Complex parameter types
23//!   go through [`AggregateOverloadBuilder::param_logical`].
24//!
25//! # Pitfalls solved
26//!
27//! - **L6** ([Problem 2][super]): The builder enforces that every function in a
28//!   function set has its name set individually. Without this, `DuckDB` silently
29//!   returns `DuckDBError` when you call `duckdb_register_aggregate_function_set`,
30//!   and the function is never registered.
31//! - **L7**: [`LogicalType`][crate::types::LogicalType] handles memory management
32//!   for all type handles.
33//!
34//! # Example: Single function
35//!
36//! ```rust,no_run
37//! use quack_rs::aggregate::AggregateFunctionBuilder;
38//! use quack_rs::types::TypeId;
39//! use libduckdb_sys::{duckdb_connection, duckdb_function_info, duckdb_aggregate_state,
40//!                     duckdb_data_chunk, duckdb_vector, idx_t};
41//!
42//! // Define your callbacks
43//! unsafe extern "C" fn state_size(_: duckdb_function_info) -> idx_t { 8 }
44//! unsafe extern "C" fn state_init(_: duckdb_function_info, _: duckdb_aggregate_state) {}
45//! unsafe extern "C" fn update(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_aggregate_state) {}
46//! unsafe extern "C" fn combine(_: duckdb_function_info, _: duckdb_aggregate_state, _: duckdb_aggregate_state, _: idx_t) {}
47//! unsafe extern "C" fn finalize(_: duckdb_function_info, _: duckdb_aggregate_state, _: duckdb_vector, _: idx_t, _: idx_t) {}
48//!
49//! // fn register(con: duckdb_connection) {
50//! //     AggregateFunctionBuilder::new("my_count")
51//! //         .param(TypeId::BigInt)
52//! //         .returns(TypeId::BigInt)
53//! //         .state_size(state_size)
54//! //         .init(state_init)
55//! //         .update(update)
56//! //         .combine(combine)
57//! //         .finalize(finalize)
58//! //         .register(con)
59//! //         .expect("registration failed");
60//! // }
61//! ```
62
63pub mod builder;
64pub mod callbacks;
65pub mod info;
66pub mod state;
67
68pub use builder::{
69    AggregateFunctionBuilder, AggregateFunctionSetBuilder, AggregateOverloadBuilder,
70};
71// Callback signature aliases, re-exported at the module root for symmetry with
72// `scalar` and `table`.
73pub use callbacks::{CombineFn, DestroyFn, FinalizeFn, StateInitFn, StateSizeFn, UpdateFn};
74pub use info::AggregateFunctionInfo;
75pub use state::{AggregateState, FfiState};