Skip to main content

ScalarFunctionSetBuilder

Struct ScalarFunctionSetBuilder 

Source
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

Source

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.

Source

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.

Source

pub fn name(&self) -> &str

Returns the function set name.

Useful for introspection and for MockRegistrar.

Source

pub fn overload(self, builder: ScalarOverloadBuilder) -> Self

Adds a single overload to this function set.

Source

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) }
Source

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 a TypeId cannot express. Build it as a LogicalType and use the *_logical method; 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 DuckDB handle 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) and f(BIGINT, BIGINT...) both take f(1)). It tells DECIMAL, MAP and ENUM parameters apart by type alone, also inside a LIST, ARRAY, STRUCT or UNION, so DECIMAL(4,1) and DECIMAL(18,3) collide, as do MAP(VARCHAR, BIGINT) and MAP(BIGINT, VARCHAR); LIST(INTEGER) and LIST(VARCHAR) do not. DuckDB itself 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 on reject_duplicate_overloads in src/scalar/builder/signature.rs.
  • An overload accepts the same call as a scalar function that already exists (see “Name collisions”).
  • DuckDB reports 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.

Trait Implementations§

Source§

impl Debug for ScalarFunctionSetBuilder

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.