Expand description
Scalar functions written as ordinary Rust closures.
ScalarFunctionBuilder::function
takes an unsafe extern "C" fn, which means every scalar function — the most
common kind of extension function by far — starts with raw pointers, manual
offset arithmetic, and the NULL-propagation contract described in
NullHandling. The constructors here take a
safe closure instead:
use quack_rs::scalar::ScalarFunctionBuilder;
// SAFETY: `con` is the connection DuckDB handed the entry point.
unsafe {
ScalarFunctionBuilder::map1("double_it", |x: i64| x * 2)?.register(con)?;
ScalarFunctionBuilder::map2("add", |a: i64, b: i64| a + b)?.register(con)?;
ScalarFunctionBuilder::map1_str("shout", |s: &str| s.to_uppercase())?
.register(con)?;
// `None` is SQL NULL.
ScalarFunctionBuilder::map1_str("email_domain", |s: &str| {
s.split_once('@').map(|(_, domain)| domain.to_owned())
})?
.register(con)?;
// `Err` fails the query with its message.
ScalarFunctionBuilder::try_map1_str("parse_int", |s: &str| s.trim().parse::<i64>())?
.register(con)?;
}§What they take care of
- Types. Parameter and return types are derived from the closure’s signature, so a mismatch is a compile error rather than a registration failure or a misread vector.
- NULLs.
map1/map2/map3/map1_str/map2_strand theirtry_*forms implement SQL’s NULL-in-NULL-out: a row with any NULL argument is skipped and its result set NULL.DuckDBdoes not do this for you — seeDataChunk::propagate_nulls. The*_optvariants hand the closureOptions instead and registerSpecialNullHandling. - NULL results. Every constructor accepts a closure returning
Option<R>:Nonewrites SQL NULL for that row. This is independent of NULL arguments — the NULL-propagating constructors still never call the closure for those. - Panics and errors. The closure runs inside
catch_unwind, and a panic becomes aDuckDBerror on that query rather than a process abort. Thetry_*constructors (try_map1,try_map2,try_map3,try_map1_str,try_map2_str) take a closure returningResult<R, E>; anErrfails the query withE’sDisplaytext. ReturnOk(None)for NULL andErrfor bad input. - A fixed signature. They return a
TypedScalarFunctionBuilder, not aScalarFunctionBuilder: it has noreturns/param/function/extra_info, because redeclaring the signature after the fact would make the closure read and write vectors of the wrong width. Register it withTypedScalarFunctionBuilder::registerorRegistrar::register_typed_scalar. To overload one name with several closures (one per argument type), add each to one set withScalarFunctionSetBuilder::overload_typed: beforeDuckDBv1.5.0 a second registration under a taken name fails.
§Cost
One indirect call per chunk, not per row: the closure is monomorphised into
a per-chunk executor when the function is built, and only that executor is
reached through dyn. The inner row loop is the same code the hand-written
callback would have been.
§When to drop down
Reach for scalar_callback! and the raw builder
when the function needs STRUCT / LIST / MAP arguments, variable arity,
bind-time constant folding, or per-thread local state.
Traits§
- Scalar
Out - A Rust type a scalar closure can return.
- Scalar
Value - A Rust type that maps 1:1 onto a
DuckDBscalar column type.