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}