pub struct ScalarOverloadBuilder { /* private fields */ }Expand description
A builder for one overload within a ScalarFunctionSetBuilder.
Implementations§
Source§impl ScalarOverloadBuilder
impl ScalarOverloadBuilder
Sourcepub fn param(self, type_id: TypeId) -> Self
pub fn param(self, type_id: TypeId) -> Self
Adds a positional parameter to this overload.
For complex types like LIST(BIGINT), use
param_logical.
Sourcepub fn param_logical(self, logical_type: LogicalType) -> Self
pub fn param_logical(self, logical_type: LogicalType) -> Self
Adds a positional parameter with a complex LogicalType.
Use this for parameterized types that TypeId cannot express, such as
LIST(BIGINT), MAP(VARCHAR, INTEGER), or STRUCT(...).
Sourcepub const fn returns(self, type_id: TypeId) -> Self
pub const fn returns(self, type_id: TypeId) -> Self
Sets the return type for this overload.
For complex return types like LIST(BIGINT), use
returns_logical instead.
Sourcepub fn returns_logical(self, logical_type: LogicalType) -> Self
pub fn returns_logical(self, logical_type: LogicalType) -> Self
Sets the return type to a complex LogicalType for this overload.
Use this for parameterized return types that TypeId cannot express,
such as LIST(BOOLEAN), LIST(TIMESTAMP), MAP(VARCHAR, INTEGER), etc.
If both returns and returns_logical are called, the logical type takes
precedence.
Sourcepub fn function(self, f: ScalarFn) -> Self
pub fn function(self, f: ScalarFn) -> Self
Sets the scalar function callback for this overload.
Sourcepub fn varargs(self, type_id: TypeId) -> Self
pub fn varargs(self, type_id: TypeId) -> Self
Marks this overload as accepting variadic arguments of the given type, after its fixed parameters.
Mirrors ScalarFunctionBuilder::varargs,
including the error from register for a composite type_id.
Sourcepub fn varargs_logical(self, logical_type: LogicalType) -> Self
pub fn varargs_logical(self, logical_type: LogicalType) -> Self
Marks this overload as accepting variadic arguments with a complex type.
Sourcepub const fn volatile(self) -> Self
pub const fn volatile(self) -> Self
Marks this overload as volatile: re-evaluated for every row even when its arguments are constant.
Mirrors ScalarFunctionBuilder::volatile.
Each overload of a set has its own stability.
Sourcepub fn bind(self, f: ScalarBindFn) -> Self
pub fn bind(self, f: ScalarBindFn) -> Self
Sets a bind callback for this overload (DuckDB 1.5.0+).
Mirrors ScalarFunctionBuilder::bind.
Guard it against panics with
scalar_bind_callback!, not
table_bind_callback!. The compiler refuses the table macro here — its
function takes a table function’s bind info, not a
RawScalarBindInfo — because a
table callback reports a panic through duckdb_bind_set_error, which
would write past the smaller scalar bind info and corrupt the stack.
Sourcepub fn init(self, f: ScalarInitFn) -> Self
pub fn init(self, f: ScalarInitFn) -> Self
Sets an init callback for this overload (DuckDB 1.5.0+).
Mirrors ScalarFunctionBuilder::init.
Guard it against panics with
scalar_init_callback!, not
table_init_callback!. The compiler refuses the table macro here — its
function takes a table function’s init info, not a
RawScalarInitInfo — because a
table callback reports a panic through duckdb_init_set_error, which
would write past the smaller scalar init info and corrupt the stack.
Sourcepub const fn null_handling(self, handling: NullHandling) -> Self
pub const fn null_handling(self, handling: NullHandling) -> Self
Sets the NULL handling behaviour for this overload.
Under either setting the callback receives NULL rows. With the default,
DefaultNullHandling, the callback
promises NULL-in-NULL-out and must keep that promise itself —
DuckDB does not write NULL for it (pitfall L8; see NullHandling and
DataChunk::propagate_nulls).
SpecialNullHandling declares that
it may return non-NULL for NULL input.
Sourcepub unsafe fn extra_info(
self,
data: *mut c_void,
destroy: duckdb_delete_callback_t,
) -> Self
pub unsafe fn extra_info( self, data: *mut c_void, destroy: duckdb_delete_callback_t, ) -> Self
Attaches arbitrary data to this overload.
The data pointer is available inside the callback via
duckdb_function_get_extra_info. The destroy callback is called by
DuckDB when the function is dropped to free the data.
§Safety
datamust stay valid untildestroyfrees it (with nodestroy, for as long as the database lives), anddestroymust be able to free it exactly once with no one else freeing it — so one pointer must not be given to two builders or overloads, each of which hands itsdestroytoDuckDBseparately.- The pointee must be
Send + Sync.DuckDBhands the same pointer to the callbacks on every thread that executes the function, possibly at the same moment, anddestroyruns on whichever thread releases the function — or, if the builder is dropped unregistered, the thread that drops it. destroymust not unwind: it is anextern "C" fn, so a panic escaping it aborts the process. Wrap a body that can panic incatch_ffi_panic.
The typical pattern is to box your data:
Box::into_raw(Box::new(my_data)).cast().