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