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}