Skip to main content

quack_rs/
selection_vector.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//! Selection vectors (`DuckDB` 1.5.0+).
7//!
8//! A [`SelectionVector`] is a list of row indices used to logically reorder or
9//! filter a data vector without copying its payload — the building block behind
10//! `DuckDB`'s zero-copy filtering. Extensions that implement custom filtering or
11//! reordering in vectorized callbacks can allocate one, fill in the indices, and
12//! hand it to the relevant `DuckDB` vector operations.
13//!
14//! # Example
15//!
16//! ```rust,no_run
17//! use quack_rs::selection_vector::SelectionVector;
18//!
19//! // Select rows 3, 1, 4, 1, 5 (in that order) from a source vector.
20//! # fn demo() -> Result<(), quack_rs::error::ExtensionError> {
21//! let mut sel = SelectionVector::new(5)?;
22//! sel.as_mut_slice().copy_from_slice(&[3, 1, 4, 1, 5]);
23//! assert_eq!(sel.len(), 5);
24//! # Ok(())
25//! # }
26//! ```
27
28use libduckdb_sys::{
29    duckdb_create_selection_vector, duckdb_destroy_selection_vector, duckdb_selection_vector,
30    duckdb_selection_vector_get_data_ptr, idx_t, sel_t,
31};
32
33use crate::error::ExtensionError;
34
35/// Every index a [`sel_t`] can hold: `2^32`.
36const SEL_T_RANGE: u64 = sel_t::MAX as u64 + 1;
37
38/// The most indices `isize::MAX` bytes can hold, which caps any Rust slice.
39const SLICE_LIMIT: u64 = (isize::MAX as usize / core::mem::size_of::<sel_t>()) as u64;
40
41/// The largest length [`SelectionVector::new`] accepts.
42///
43/// This is `2^32` — the number of distinct source rows a [`sel_t`] (`u32`)
44/// index can name — on 64-bit targets, and the largest `sel_t` slice that fits
45/// in `isize::MAX` bytes on 32-bit ones.
46///
47/// `DuckDB` does no checking of its own here: `duckdb_create_selection_vector`
48/// computes `size * sizeof(sel_t)` without an overflow check (so a large enough
49/// `size` wraps to a tiny allocation while the caller believes it owns `size`
50/// indices), and at `Allocator::MAXIMUM_ALLOC_SIZE` (`2^48` bytes) or above it
51/// throws a C++ exception, which aborts an extension. Capping the length at the
52/// range of `sel_t` keeps the byte count at most `2^34`, far from both. Real
53/// selection vectors are sized in vector rows — `STANDARD_VECTOR_SIZE` (2048)
54/// in ordinary execution — so the cap rejects only lengths no operation could
55/// use.
56#[allow(
57    clippy::cast_possible_truncation,
58    reason = "the smaller of the two limits is at most SLICE_LIMIT, which came from a usize"
59)]
60pub const MAX_LEN: usize = if SEL_T_RANGE < SLICE_LIMIT {
61    SEL_T_RANGE as usize
62} else {
63    SLICE_LIMIT as usize
64};
65
66/// RAII wrapper for a `duckdb_selection_vector`.
67///
68/// Owns `size` 32-bit row indices ([`sel_t`]), zero-initialised by
69/// [`new`][SelectionVector::new]. Automatically destroyed on drop.
70#[derive(Debug)]
71pub struct SelectionVector {
72    sel: duckdb_selection_vector,
73    len: usize,
74}
75
76impl SelectionVector {
77    /// Allocates a selection vector holding `size` indices, all zero.
78    ///
79    /// Fill the indices via [`as_mut_slice`][SelectionVector::as_mut_slice].
80    ///
81    /// `DuckDB` leaves the buffer uninitialised in release builds, so this
82    /// zeroes it: every index starts as row 0, never as stale heap contents.
83    ///
84    /// # Errors
85    ///
86    /// Returns an error if `size` exceeds [`MAX_LEN`] — checked before `DuckDB`
87    /// is called, because above it `DuckDB` either miscomputes the allocation
88    /// size or throws — or if `DuckDB` returns a null handle or buffer.
89    ///
90    /// An allocation within the limit that the system cannot satisfy still
91    /// makes `DuckDB` throw, which aborts the process, just as a failed Rust
92    /// allocation does.
93    pub fn new(size: usize) -> Result<Self, ExtensionError> {
94        if size > MAX_LEN {
95            return Err(ExtensionError::new(format!(
96                "selection vector length {size} exceeds the maximum of {MAX_LEN}"
97            )));
98        }
99        // `size <= MAX_LEN <= 2^32`, which always fits in a 64-bit `idx_t`.
100        let raw_size = idx_t::try_from(size)
101            .map_err(|_| ExtensionError::new("selection vector length does not fit in idx_t"))?;
102        // SAFETY: duckdb_create_selection_vector allocates an owned handle; the
103        // length check above keeps `size * sizeof(sel_t)` from overflowing and
104        // below the allocator's throwing limit.
105        let sel = unsafe { duckdb_create_selection_vector(raw_size) };
106        if sel.is_null() {
107            return Err(ExtensionError::new(
108                "duckdb_create_selection_vector returned null",
109            ));
110        }
111        let mut this = Self { sel, len: size };
112        if size > 0 {
113            // SAFETY: `this.sel` is a valid handle.
114            let ptr = unsafe { duckdb_selection_vector_get_data_ptr(this.sel) };
115            if ptr.is_null() {
116                // Dropping `this` still releases the handle.
117                this.len = 0;
118                return Err(ExtensionError::new(
119                    "duckdb_selection_vector_get_data_ptr returned null",
120                ));
121            }
122            // SAFETY: `ptr` addresses `size` writable, aligned sel_t values that
123            // DuckDB allocated but did not initialise (it only fills them under
124            // `#ifdef DEBUG`); zeroing them is what makes `as_slice` sound.
125            unsafe { core::ptr::write_bytes(ptr, 0, size) };
126        }
127        Ok(this)
128    }
129
130    /// Returns the number of indices in this selection vector.
131    #[inline]
132    #[must_use]
133    pub const fn len(&self) -> usize {
134        self.len
135    }
136
137    /// Returns `true` if the selection vector holds no indices.
138    #[inline]
139    #[must_use]
140    pub const fn is_empty(&self) -> bool {
141        self.len == 0
142    }
143
144    /// Returns the indices as a read-only slice.
145    #[must_use]
146    pub fn as_slice(&self) -> &[sel_t] {
147        if self.sel.is_null() || self.len == 0 {
148            return &[];
149        }
150        // SAFETY: self.sel is valid; the data pointer addresses `self.len` sel_t
151        // elements that live as long as the selection vector.
152        let ptr = unsafe { duckdb_selection_vector_get_data_ptr(self.sel) };
153        if ptr.is_null() {
154            return &[];
155        }
156        // SAFETY: ptr points to `self.len` aligned sel_t values, all
157        // initialised by `new`; `self.len <= MAX_LEN` keeps the slice within
158        // `isize::MAX` bytes.
159        unsafe { std::slice::from_raw_parts(ptr, self.len) }
160    }
161
162    /// Returns the indices as a mutable slice for filling in.
163    #[must_use]
164    pub fn as_mut_slice(&mut self) -> &mut [sel_t] {
165        if self.sel.is_null() || self.len == 0 {
166            return &mut [];
167        }
168        // SAFETY: self.sel is valid; the data pointer addresses `self.len` sel_t
169        // elements that live as long as the selection vector.
170        let ptr = unsafe { duckdb_selection_vector_get_data_ptr(self.sel) };
171        if ptr.is_null() {
172            return &mut [];
173        }
174        // SAFETY: ptr points to `self.len` valid, aligned sel_t values and we hold
175        // a unique borrow of `self`.
176        unsafe { std::slice::from_raw_parts_mut(ptr, self.len) }
177    }
178
179    /// Returns the raw handle.
180    #[inline]
181    #[must_use]
182    pub const fn as_raw(&self) -> duckdb_selection_vector {
183        self.sel
184    }
185}
186
187impl Drop for SelectionVector {
188    fn drop(&mut self) {
189        if !self.sel.is_null() {
190            // SAFETY: self.sel is a valid handle that we own. This destroy variant
191            // takes the handle by value.
192            unsafe { duckdb_destroy_selection_vector(self.sel) };
193        }
194    }
195}
196
197#[cfg(test)]
198mod limit_tests {
199    use super::*;
200
201    #[test]
202    fn max_len_is_the_sel_t_range_on_64_bit() {
203        #[cfg(target_pointer_width = "64")]
204        assert_eq!(MAX_LEN as u64, 1_u64 << 32);
205        // On every target the byte count must fit a Rust slice.
206        let bytes = MAX_LEN.checked_mul(core::mem::size_of::<sel_t>());
207        assert!(bytes.is_some_and(|b| isize::try_from(b).is_ok()));
208    }
209
210    #[test]
211    fn oversized_lengths_are_rejected_before_duckdb_is_called() {
212        // No dispatch table is initialised here, so reaching DuckDB would
213        // fail; an `Err` proves the check runs first. On 64-bit these include
214        // `(1 << 62) + 4`, whose byte count DuckDB wraps to 16, and `1 << 47`,
215        // which makes DuckDB's allocator throw.
216        assert!(SelectionVector::new(MAX_LEN + 1).is_err());
217        assert!(SelectionVector::new(usize::MAX).is_err());
218        #[cfg(target_pointer_width = "64")]
219        {
220            assert!(SelectionVector::new((1 << 62) + 4).is_err());
221            assert!(SelectionVector::new(1 << 47).is_err());
222        }
223    }
224}
225
226#[cfg(all(test, feature = "_duckdb-testing"))]
227mod tests {
228    use super::*;
229
230    #[test]
231    fn round_trips_indices() {
232        // Ensure the dispatch table is populated.
233        let _db = crate::testing::InMemoryDb::open().unwrap();
234
235        let mut sel = SelectionVector::new(4).expect("allocate");
236        assert_eq!(sel.len(), 4);
237        assert!(!sel.is_empty());
238        sel.as_mut_slice().copy_from_slice(&[7, 0, 3, 1]);
239        assert_eq!(sel.as_slice(), &[7, 0, 3, 1]);
240    }
241}