pub struct ScalarFunctionSetBuilder { /* private fields */ }Expand description
Builder for registering a DuckDB scalar function set (multiple overloads).
Use this when your scalar function accepts different parameter types or arities by registering N overloads under a single name.
§Pitfall L6 (applies to scalar sets too)
This builder calls duckdb_scalar_function_set_name on EVERY individual
function before adding it to the set, matching the pattern established by
AggregateFunctionSetBuilder.
§Example
use quack_rs::scalar::{ScalarFunctionSetBuilder, ScalarOverloadBuilder};
use quack_rs::types::TypeId;
use libduckdb_sys::{duckdb_connection, duckdb_function_info, duckdb_data_chunk,
duckdb_vector};
unsafe extern "C" fn add_ints(
_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector,
) {}
unsafe extern "C" fn add_doubles(
_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector,
) {}
// fn register(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
// unsafe {
// ScalarFunctionSetBuilder::new("my_add")
// .overload(
// ScalarOverloadBuilder::new()
// .param(TypeId::Integer).param(TypeId::Integer)
// .returns(TypeId::Integer)
// .function(add_ints)
// )
// .overload(
// ScalarOverloadBuilder::new()
// .param(TypeId::Double).param(TypeId::Double)
// .returns(TypeId::Double)
// .function(add_doubles)
// )
// .register(con)
// }
// }Implementations§
Source§impl ScalarFunctionSetBuilder
impl ScalarFunctionSetBuilder
Sourcepub fn new(name: &str) -> Self
pub fn new(name: &str) -> Self
Creates a new builder for a scalar function set with the given name.
§Panics
Panics if name contains an interior null byte.
Sourcepub fn try_new(name: &str) -> Result<Self, ExtensionError>
pub fn try_new(name: &str) -> Result<Self, ExtensionError>
Creates a new builder with function name validation.
§Errors
Returns ExtensionError if the name is invalid.
See validate_function_name for the full set of rules.
Sourcepub fn name(&self) -> &str
pub fn name(&self) -> &str
Returns the function set name.
Useful for introspection and for MockRegistrar.
Sourcepub fn overload(self, builder: ScalarOverloadBuilder) -> Self
pub fn overload(self, builder: ScalarOverloadBuilder) -> Self
Adds a single overload to this function set.
Sourcepub fn overload_typed(self, function: TypedScalarFunctionBuilder) -> Self
pub fn overload_typed(self, function: TypedScalarFunctionBuilder) -> Self
Adds a closure-built function (ScalarFunctionBuilder::map1 and
its siblings) as one overload of this set.
This is how a closure-built function gets overloads: one set holding
one closure per argument type, registered once. Registering several
closure-built functions under one name one by one works only from
DuckDB v1.5.0 (before it, the C API cannot add an overload to an
existing name), and this works on every engine.
The overload keeps what the closure fixed — its parameter and return
types, callback and extra_info — and its stability
(volatile); the set offers no
way to change them. It takes the set’s name: one built under another
name (compared case-insensitively, as DuckDB compares names) makes
register fail, naming the overload, rather than
register it as something its builder did not say.
use quack_rs::scalar::{ScalarFunctionBuilder, ScalarFunctionSetBuilder};
let set = ScalarFunctionSetBuilder::new("double_it")
.overload_typed(ScalarFunctionBuilder::map1("double_it", |x: i32| x.wrapping_mul(2))?)
.overload_typed(ScalarFunctionBuilder::map1("double_it", |x: i64| x.wrapping_mul(2))?)
.overload_typed(ScalarFunctionBuilder::map1("double_it", |x: f64| x * 2.0)?);
// SAFETY: `con` is an open connection.
unsafe { set.register(con) }Sourcepub unsafe fn register(
self,
con: duckdb_connection,
) -> Result<(), ExtensionError>
pub unsafe fn register( self, con: duckdb_connection, ) -> Result<(), ExtensionError>
Registers the scalar function set on the given connection.
§Errors
Returns ExtensionError if:
- No overloads were added.
- A parameter, varargs or return type was given as a bare composite
TypeId(DECIMAL,ENUM,LIST,STRUCT,MAP,ARRAY,UNION), which carries parameters aTypeIdcannot express. Build it as aLogicalTypeand use the*_logicalmethod; the error names the slot. - Any overload is missing a return type or function callback. The error
names the overload’s index, and is reported before any
DuckDBhandle is allocated. - Two overloads accept the same call: argument types
DuckDB’s overload resolution cannot tell apart, or, with varargs, such types at some argument count (f(BIGINT)andf(BIGINT, BIGINT...)both takef(1)). It tellsDECIMAL,MAPandENUMparameters apart by type alone, also inside aLIST,ARRAY,STRUCTorUNION, soDECIMAL(4,1)andDECIMAL(18,3)collide, as doMAP(VARCHAR, BIGINT)andMAP(BIGINT, VARCHAR);LIST(INTEGER)andLIST(VARCHAR)do not.DuckDBitself would accept such a set and then fail every such call with “Could not choose a best candidate function”. The rule, and the two shapes it does not catch, are onreject_duplicate_overloadsinsrc/scalar/builder/signature.rs. - An overload accepts the same call as a scalar function that already exists (see “Name collisions”).
DuckDBreports registration failure.
§Name collisions
DuckDB registers scalar functions with ALTER_ON_CONFLICT
(duckdb_register_scalar_function_set in scalar_function-c.cpp), so a
scalar function that already has this name — built-in or not — never
makes DuckDB refuse the registration. A new signature is added as an
overload. One with the same parameter types as an existing overload
either silently replaces it for every connection to the database
(same return type: FunctionSet::MergeFunctionSet with
override = true) or makes every call ambiguous (“Could not choose a
best candidate function”, different return type). Registering
abs(BIGINT) would change the built-in abs for BIGINT.
quack-rs therefore refuses an overload, naming its index, before
registering, when duckdb_functions() already lists a scalar with this
name that accepts the same call — the rule and its coverage are those of
ScalarFunctionBuilder::register,
including its cost: one catalog scan per call, or one per extension load
through the entry point’s Connection.
DuckDB itself refuses a name that belongs to an aggregate function or
a macro (such as the built-in list_sum).
§Safety
con must be a valid, open duckdb_connection.