Skip to main content

Module typed

Module typed 

Source
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_str and their try_* forms implement SQL’s NULL-in-NULL-out: a row with any NULL argument is skipped and its result set NULL. DuckDB does not do this for you — see DataChunk::propagate_nulls. The *_opt variants hand the closure Options instead and register SpecialNullHandling.
  • NULL results. Every constructor accepts a closure returning Option<R>: None writes 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 a DuckDB error on that query rather than a process abort. The try_* constructors (try_map1, try_map2, try_map3, try_map1_str, try_map2_str) take a closure returning Result<R, E>; an Err fails the query with E’s Display text. Return Ok(None) for NULL and Err for bad input.
  • A fixed signature. They return a TypedScalarFunctionBuilder, not a ScalarFunctionBuilder: it has no returns / 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 with TypedScalarFunctionBuilder::register or Registrar::register_typed_scalar. To overload one name with several closures (one per argument type), add each to one set with ScalarFunctionSetBuilder::overload_typed: before DuckDB v1.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§

ScalarOut
A Rust type a scalar closure can return.
ScalarValue
A Rust type that maps 1:1 onto a DuckDB scalar column type.