Skip to main content

quack_rs/types/
null_handling.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! NULL propagation behaviour for `DuckDB` functions.
7
8/// Declares whether a function is prepared to see NULL arguments.
9///
10/// # This does not make `DuckDB` propagate NULLs for you
11///
12/// The name invites the reading "`DefaultNullHandling` means `DuckDB` returns
13/// NULL when an argument is NULL, without calling me". For a **scalar function
14/// registered through the C API that is false at run time**, and the difference
15/// is silent wrong answers rather than an error:
16///
17/// - `CAPIScalarFunction` calls the extension's callback for the whole
18///   flattened chunk, NULL rows included, and never inspects the result's
19///   validity.
20/// - `ExpressionExecutor::Execute` then calls `VerifyNullHandling`, which only
21///   *asserts* that the function already produced NULL wherever an input was
22///   NULL. Through `DuckDB` 1.5.6 it is compiled **only under `#ifdef DEBUG`**; in
23///   2.0.0 it is compiled in but runs only after
24///   `SET debug_verification_mode = 'VERIFY_FUNCTIONS'`, so a default session
25///   still believes the callback.
26///
27/// A quick `SELECT my_func(NULL)` does not reveal this, because a literal NULL
28/// is constant-folded before the function is ever called. The wrong answers
29/// start once the argument is a column. Verified against `DuckDB` 1.5.4: a
30/// scalar function writing `999` unconditionally, registered with
31/// `DefaultNullHandling`, returned `999` — valid, not NULL — for the NULL row
32/// of a real table.
33///
34/// So: under `DefaultNullHandling`, propagate NULLs yourself. The one-line way
35/// is [`DataChunk::propagate_nulls`][crate::data_chunk::DataChunk::propagate_nulls]
36/// at the end of the callback.
37///
38/// What the setting *does* control is `DuckDB`'s own expectations —
39/// `SpecialNullHandling` tells the planner and the debug assertion that this
40/// function means to see NULLs and will not necessarily return NULL for them,
41/// which is what a `coalesce`-like or `is_null`-like function needs.
42///
43/// # Aggregates see NULL rows too
44///
45/// The same is true of aggregates: under **either** setting, `update` receives
46/// every row of the chunk, NULL rows included. `CAPIAggregateUpdate`
47/// (`src/main/capi/aggregate_function-c.cpp`) flattens each input vector and
48/// hands the whole chunk to the callback without looking at validity, and the
49/// aggregate executor applies no NULL filter of its own. An aggregate that must
50/// ignore NULLs checks
51/// [`VectorReader::is_valid`][crate::vector::VectorReader::is_valid] per row
52/// and skips the invalid ones; reading an invalid row's value reads whatever
53/// happens to be in the data buffer.
54///
55/// For an aggregate the setting is read only by the correlated subquery
56/// decorrelator (`flatten_dependent_join.cpp`). Before `DuckDB` 2.0.0 it
57/// reads it in one place, `BoundAggregateExpression::PropagatesNullValues`,
58/// to choose an `INNER` or `LEFT` join, and no query tried against 1.5.5 —
59/// correlated scalar subqueries with and without arithmetic or `coalesce`
60/// over the aggregate, `LATERAL`, and a correlated subquery in `WHERE` — gave
61/// a different answer under the two settings.
62///
63/// The difference that shows is an outer row with no matching inner rows.
64/// Under `DefaultNullHandling` (and, before 2.0.0, under both settings) the
65/// correlated subquery yields NULL there without ever finalizing an empty
66/// state; `DuckDB` special-cases only its own `count` and `count(*)` to
67/// return 0, so a count-like aggregate that returns 0 for empty input returns
68/// NULL for such a row. From 2.0.0 the decorrelator finalizes an empty state
69/// of every `SpecialNullHandling` aggregate and uses it for those rows
70/// (`FlattenDependentJoins::PushDownAggregate`), so such an aggregate answers
71/// as it would for an empty uncorrelated input. On older releases, or under
72/// `DefaultNullHandling`, wrap the subquery in `coalesce(..., 0)` if that
73/// matters.
74///
75/// # Example
76///
77/// ```rust,no_run
78/// use quack_rs::scalar::ScalarFunctionBuilder;
79/// use quack_rs::types::{TypeId, NullHandling};
80///
81/// // fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
82/// //     unsafe {
83/// //         ScalarFunctionBuilder::new("coalesce_custom")
84/// //             .param(TypeId::BigInt)
85/// //             .returns(TypeId::BigInt)
86/// //             .null_handling(NullHandling::SpecialNullHandling)
87/// //             .function(my_func)
88/// //             .register(con)
89/// //     }
90/// // }
91/// ```
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
93pub enum NullHandling {
94    /// The function is expected to return NULL wherever an argument is NULL.
95    ///
96    /// This is `DuckDB`'s default, so quack-rs makes no FFI call for it. For a
97    /// **scalar** function it is a promise the callback must keep itself — see
98    /// the type-level documentation, and
99    /// [`DataChunk::propagate_nulls`][crate::data_chunk::DataChunk::propagate_nulls].
100    /// An **aggregate**'s `update` also receives NULL rows under this setting
101    /// and must skip them itself — see the type-level documentation.
102    #[default]
103    DefaultNullHandling,
104    /// The function means to see NULLs and may return non-NULL for them.
105    ///
106    /// Registers `FunctionNullHandling::SPECIAL_HANDLING`, which suppresses
107    /// `DuckDB`'s debug-build assertion that NULL in implies NULL out. It does
108    /// not change which rows a callback receives: scalar and aggregate
109    /// callbacks see NULL rows under either setting. The callback must check
110    /// [`VectorReader::is_valid`][crate::vector::VectorReader::is_valid] itself.
111    SpecialNullHandling,
112}
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117
118    #[test]
119    fn default_is_default_handling() {
120        assert_eq!(NullHandling::default(), NullHandling::DefaultNullHandling);
121    }
122
123    #[test]
124    fn debug_display() {
125        let s = format!("{:?}", NullHandling::SpecialNullHandling);
126        assert!(s.contains("SpecialNullHandling"));
127    }
128}