Skip to main content

Module ops

Module ops 

Source
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§

OwnedVector
A flat duckdb_vector this crate allocated, destroyed on drop.

Constants§

MAX_CAPACITY
The most elements OwnedVector::new will ask DuckDB to put in one vector.

Functions§

copy_selected⚠
Copies the rows sel names from src into dst.
reference_value⚠
Fills vector with a single constant value.
reference_vector⚠
Makes to reference from’s data instead of its own.
slice⚠
Reorders or filters vector in place through sel, without copying its payload.