Expand description
Whole-vector operations (DuckDB 1.5.0+).
SelectionVector is DuckDB’s
zero-copy filtering primitive — and on its own it does nothing. These are the
operations that consume one, plus the standalone OwnedVector that gives a
copy somewhere to land.
§The one thing to know before slicing
slice() turns its vector into a dictionary vector: the payload stays
put and the vector gains an indirection through the selection. That is the
point — no data is copied — but it also means
duckdb_vector_get_data no longer maps row i to element i, so a
VectorReader over a sliced vector reads the
wrong rows, silently.
quack-rs’s readers are flat readers, which is correct everywhere DuckDB
hands an extension a vector — CAPIScalarFunction, CAPIAggregateUpdate,
the cast bridge and the copy sink all call Flatten() on their inputs first
(verified in DuckDB 1.5.4’s src/main/capi/*.cpp), and
duckdb_fetch_chunk flattens query results. Three operations can make a
vector non-flat, and after each the guarantee has to be re-established by
hand: slice() (a dictionary vector), reference_value() (a constant
vector) and reference_vector() from a non-flat source (the target takes
the source’s layout). arrow::data_chunk_from_arrow also receives non-flat
vectors from DuckDB — dictionary vectors for dictionary-encoded columns,
constant vectors for null-typed ones — and flattens them itself before
returning.
Prefer copy_selected(): it writes the selected rows into a flat
destination, which every reader in this crate can then read normally.
§Example: filter without copying the payload
use quack_rs::selection_vector::SelectionVector;
use quack_rs::vector::ops::{copy_selected, OwnedVector};
use quack_rs::types::{LogicalType, TypeId};
// Keep every third row.
let kept: Vec<u32> = (0..row_count as u32).step_by(3).collect();
let mut sel = SelectionVector::new(kept.len())?;
sel.as_mut_slice().copy_from_slice(&kept);
let dst = OwnedVector::new(&LogicalType::new(TypeId::BigInt), kept.len())?;
// SAFETY: `src` holds BIGINT, every index in `sel` is a valid `src` row,
// and `dst` has room for `kept.len()` of them.
unsafe { copy_selected(src, dst.as_raw(), &sel, kept.len(), 0, 0) };Structs§
- Owned
Vector - A flat
duckdb_vectorthis crate allocated, destroyed on drop.
Constants§
- MAX_
CAPACITY - The most elements
OwnedVector::newwill askDuckDBto put in one vector.
Functions§
- copy_
selected ⚠ - Copies the rows
selnames fromsrcintodst. - reference_
value ⚠ - Fills
vectorwith a single constant value. - reference_
vector ⚠ - Makes
toreferencefrom’s data instead of its own. - slice⚠
- Reorders or filters
vectorin place throughsel, without copying its payload.