Skip to main content

quack_rs/vector/
validity.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//! Validity bitmap helpers for `DuckDB` NULL tracking.
7//!
8//! `DuckDB` tracks NULL values using a packed validity bitmap. Each row's validity
9//! is represented by a single bit in a `u64` array. This module provides a safe
10//! wrapper that encapsulates the bit manipulation.
11//!
12//! # Pitfall L4: `ensure_validity_writable`
13//!
14//! When writing NULL values, `duckdb_vector_get_validity` returns NULL for a
15//! vector that has no validity mask yet (the usual state of a vector no NULL
16//! has been written to) unless `duckdb_vector_ensure_validity_writable` has
17//! been called first — and `duckdb_validity_set_row_invalid` silently ignores a
18//! NULL mask, so the NULL would be dropped.
19//! [`ValidityBitmap::ensure_writable`] wraps this requirement so it cannot be
20//! forgotten.
21
22use libduckdb_sys::{
23    duckdb_validity_row_is_valid, duckdb_validity_set_row_invalid, duckdb_validity_set_row_valid,
24    duckdb_vector, duckdb_vector_ensure_validity_writable, duckdb_vector_get_validity, idx_t,
25};
26
27/// A wrapper around a `DuckDB` validity bitmap for reading or writing NULL flags.
28///
29/// Obtain a writable instance via [`ValidityBitmap::ensure_writable`]. For
30/// read-only access, use [`ValidityBitmap::get_read_only`].
31///
32/// # Safety invariants
33///
34/// The underlying `duckdb_vector` must remain valid for the lifetime `'v` of
35/// this wrapper. Do not call `duckdb_destroy_data_chunk` while a `ValidityBitmap`
36/// that references the vector is live.
37#[derive(Debug)]
38pub struct ValidityBitmap<'v> {
39    validity: *mut u64,
40    _phantom: std::marker::PhantomData<&'v mut duckdb_vector>,
41}
42
43impl ValidityBitmap<'_> {
44    /// Ensures the validity bitmap is writable and returns a [`ValidityBitmap`].
45    ///
46    /// This calls `duckdb_vector_ensure_validity_writable` before
47    /// `duckdb_vector_get_validity`, which is required before writing NULL flags.
48    ///
49    /// # Pitfall L4
50    ///
51    /// Calling `duckdb_vector_get_validity` without first calling
52    /// `duckdb_vector_ensure_validity_writable` returns NULL when the vector
53    /// has no mask yet, and NULLs written through that are silently dropped.
54    ///
55    /// # Safety
56    ///
57    /// `vector` must be a valid `DuckDB` vector handle obtained from a data chunk
58    /// within the current callback invocation. The vector must not be destroyed
59    /// while the returned `ValidityBitmap` is live. If `vector` lies inside the
60    /// child of a `LIST` or `MAP` vector — is that child, or a STRUCT field or
61    /// ARRAY element vector below it with no other `LIST` or `MAP` in between —
62    /// the bitmap must not be used after that `LIST` or `MAP` is grown with a
63    /// `reserve`, which reallocates the validity buffer of every such vector.
64    pub unsafe fn ensure_writable(vector: duckdb_vector) -> Self {
65        // SAFETY: `vector` is a valid DuckDB vector handle. This call marks the
66        // vector's validity buffer as writable and allocates it if it doesn't exist.
67        unsafe { duckdb_vector_ensure_validity_writable(vector) };
68        // SAFETY: The bitmap was just ensured to be writable and allocated.
69        let validity = unsafe { duckdb_vector_get_validity(vector) };
70        Self {
71            validity,
72            _phantom: std::marker::PhantomData,
73        }
74    }
75
76    /// Gets the validity bitmap for read-only NULL checks.
77    ///
78    /// # Safety
79    ///
80    /// `vector` must be a valid `DuckDB` vector handle. The returned pointer may
81    /// be null if the vector has no validity bitmap (all rows are valid).
82    pub unsafe fn get_read_only(vector: duckdb_vector) -> Self {
83        // SAFETY: Caller guarantees `vector` is valid.
84        let validity = unsafe { duckdb_vector_get_validity(vector) };
85        Self {
86            validity,
87            _phantom: std::marker::PhantomData,
88        }
89    }
90
91    /// Returns `true` if the row at `idx` is valid (non-NULL).
92    ///
93    /// If the validity bitmap pointer is null (all rows are valid), always returns
94    /// `true`.
95    ///
96    /// # Safety
97    ///
98    /// `idx` must be less than the number of rows in the vector.
99    #[inline]
100    pub unsafe fn row_is_valid(&self, idx: idx_t) -> bool {
101        if self.validity.is_null() {
102            return true;
103        }
104        // SAFETY: `validity` is non-null and `idx` is in bounds per the caller's contract.
105        unsafe { duckdb_validity_row_is_valid(self.validity, idx) }
106    }
107
108    /// Marks the row at `idx` as NULL (invalid).
109    ///
110    /// This touches only this one mask. For a `STRUCT` or `ARRAY` vector, use
111    /// [`VectorWriter::set_null`][crate::vector::VectorWriter::set_null]
112    /// instead, which also nulls the children as `DuckDB` expects.
113    ///
114    /// # Safety
115    ///
116    /// - This bitmap must have been created via [`ensure_writable`][ValidityBitmap::ensure_writable].
117    /// - `idx` must be less than the number of rows in the vector.
118    #[inline]
119    pub unsafe fn set_row_invalid(&mut self, idx: idx_t) {
120        debug_assert!(
121            !self.validity.is_null(),
122            "set_row_invalid called on a non-writable bitmap"
123        );
124        // SAFETY: Bitmap is writable (ensured in constructor) and idx is in bounds.
125        unsafe { duckdb_validity_set_row_invalid(self.validity, idx) };
126    }
127
128    /// Marks the row at `idx` as valid (non-NULL).
129    ///
130    /// # Safety
131    ///
132    /// - This bitmap must have been created via [`ensure_writable`][ValidityBitmap::ensure_writable].
133    /// - `idx` must be less than the number of rows in the vector.
134    #[inline]
135    pub unsafe fn set_row_valid(&mut self, idx: idx_t) {
136        debug_assert!(
137            !self.validity.is_null(),
138            "set_row_valid called on a non-writable bitmap"
139        );
140        // SAFETY: Bitmap is writable and idx is in bounds.
141        unsafe { duckdb_validity_set_row_valid(self.validity, idx) };
142    }
143
144    /// Returns the raw validity bitmap pointer.
145    ///
146    /// This is an escape hatch for code that needs direct bitmap access.
147    /// Prefer the safe methods on this type when possible.
148    #[must_use]
149    #[inline]
150    pub const fn as_raw(&self) -> *mut u64 {
151        self.validity
152    }
153}
154
155#[cfg(test)]
156mod tests {
157    // Note: validity bitmap tests that require a real DuckDB vector are in
158    // tests/ffi_roundtrip/validity_api.rs and nested_validity.rs. Unit tests
159    // here cover the struct size and null-bitmap logic.
160
161    #[test]
162    fn read_only_with_null_ptr() {
163        // When the validity pointer is null, all rows are considered valid.
164        use super::ValidityBitmap;
165        use libduckdb_sys::duckdb_vector;
166        // We cannot easily construct a real vector here without a full DuckDB connection,
167        // but we can test the null-pointer code path using get_read_only on a null vector.
168        // This is a known-unsafe call but acceptable in a controlled test.
169        // Instead, test the invariant: if validity ptr is null, row_is_valid returns true.
170        let bm = ValidityBitmap {
171            validity: std::ptr::null_mut(),
172            _phantom: std::marker::PhantomData::<&mut duckdb_vector>,
173        };
174        // SAFETY: idx 0 is vacuously valid when bitmap is null.
175        assert!(unsafe { bm.row_is_valid(0) });
176    }
177}