Skip to main content

NullHandling

Enum NullHandling 

Source
pub enum NullHandling {
    DefaultNullHandling,
    SpecialNullHandling,
}
Expand description

Declares whether a function is prepared to see NULL arguments.

§This does not make DuckDB propagate NULLs for you

The name invites the reading “DefaultNullHandling means DuckDB returns NULL when an argument is NULL, without calling me”. For a scalar function registered through the C API that is false at run time, and the difference is silent wrong answers rather than an error:

  • CAPIScalarFunction calls the extension’s callback for the whole flattened chunk, NULL rows included, and never inspects the result’s validity.
  • ExpressionExecutor::Execute then calls VerifyNullHandling, which only asserts that the function already produced NULL wherever an input was NULL. Through DuckDB 1.5.6 it is compiled only under #ifdef DEBUG; in 2.0.0 it is compiled in but runs only after SET debug_verification_mode = 'VERIFY_FUNCTIONS', so a default session still believes the callback.

A quick SELECT my_func(NULL) does not reveal this, because a literal NULL is constant-folded before the function is ever called. The wrong answers start once the argument is a column. Verified against DuckDB 1.5.4: a scalar function writing 999 unconditionally, registered with DefaultNullHandling, returned 999 — valid, not NULL — for the NULL row of a real table.

So: under DefaultNullHandling, propagate NULLs yourself. The one-line way is DataChunk::propagate_nulls at the end of the callback.

What the setting does control is DuckDB’s own expectations — SpecialNullHandling tells the planner and the debug assertion that this function means to see NULLs and will not necessarily return NULL for them, which is what a coalesce-like or is_null-like function needs.

§Aggregates see NULL rows too

The same is true of aggregates: under either setting, update receives every row of the chunk, NULL rows included. CAPIAggregateUpdate (src/main/capi/aggregate_function-c.cpp) flattens each input vector and hands the whole chunk to the callback without looking at validity, and the aggregate executor applies no NULL filter of its own. An aggregate that must ignore NULLs checks VectorReader::is_valid per row and skips the invalid ones; reading an invalid row’s value reads whatever happens to be in the data buffer.

For an aggregate the setting is read only by the correlated subquery decorrelator (flatten_dependent_join.cpp). Before DuckDB 2.0.0 it reads it in one place, BoundAggregateExpression::PropagatesNullValues, to choose an INNER or LEFT join, and no query tried against 1.5.5 — correlated scalar subqueries with and without arithmetic or coalesce over the aggregate, LATERAL, and a correlated subquery in WHERE — gave a different answer under the two settings.

The difference that shows is an outer row with no matching inner rows. Under DefaultNullHandling (and, before 2.0.0, under both settings) the correlated subquery yields NULL there without ever finalizing an empty state; DuckDB special-cases only its own count and count(*) to return 0, so a count-like aggregate that returns 0 for empty input returns NULL for such a row. From 2.0.0 the decorrelator finalizes an empty state of every SpecialNullHandling aggregate and uses it for those rows (FlattenDependentJoins::PushDownAggregate), so such an aggregate answers as it would for an empty uncorrelated input. On older releases, or under DefaultNullHandling, wrap the subquery in coalesce(..., 0) if that matters.

§Example

use quack_rs::scalar::ScalarFunctionBuilder;
use quack_rs::types::{TypeId, NullHandling};

// fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
//     unsafe {
//         ScalarFunctionBuilder::new("coalesce_custom")
//             .param(TypeId::BigInt)
//             .returns(TypeId::BigInt)
//             .null_handling(NullHandling::SpecialNullHandling)
//             .function(my_func)
//             .register(con)
//     }
// }

Variants§

§

DefaultNullHandling

The function is expected to return NULL wherever an argument is NULL.

This is DuckDB’s default, so quack-rs makes no FFI call for it. For a scalar function it is a promise the callback must keep itself — see the type-level documentation, and DataChunk::propagate_nulls. An aggregate’s update also receives NULL rows under this setting and must skip them itself — see the type-level documentation.

§

SpecialNullHandling

The function means to see NULLs and may return non-NULL for them.

Registers FunctionNullHandling::SPECIAL_HANDLING, which suppresses DuckDB’s debug-build assertion that NULL in implies NULL out. It does not change which rows a callback receives: scalar and aggregate callbacks see NULL rows under either setting. The callback must check VectorReader::is_valid itself.

Trait Implementations§

Source§

impl Clone for NullHandling

Source§

fn clone(&self) -> NullHandling

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for NullHandling

Source§

impl Debug for NullHandling

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for NullHandling

Source§

fn default() -> NullHandling

Returns the “default value” for a type. Read more
Source§

impl Eq for NullHandling

Source§

impl Hash for NullHandling

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for NullHandling

Source§

fn eq(&self, other: &NullHandling) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for NullHandling

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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. 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> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
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.