Struct VectorReader

Source

pub struct VectorReader { /* private fields */ }

Expand description

A typed reader for a single column in a DuckDB data chunk.

VectorReader wraps a pointer to a DuckDB vector’s data buffer and provides ergonomic, type-checked access methods for common DuckDB types.

§Lifetimes

The reader borrows from the data chunk. Do not call duckdb_destroy_data_chunk while a VectorReader that references it is live.

Implementations§

Source §

impl VectorReader

Source

pub unsafe fn new(chunk: duckdb_data_chunk, col_idx: usize) -> Self

Creates a new VectorReader for the given column in a data chunk.

§Safety

chunk must be a valid duckdb_data_chunk for the duration of this reader’s lifetime.
col_idx must be a valid column index in the chunk.

Source

pub unsafe fn from_vector(vector: duckdb_vector, row_count: usize) -> Self

Creates a VectorReader directly from a raw duckdb_vector handle.

Use this when you already have a child vector (e.g., from StructVector::get_child or ListVector::get_child).

§Safety

vector must be a valid duckdb_vector for the duration of this reader’s lifetime.
row_count must equal the number of valid rows in the vector.

Source

pub const fn row_count(&self) -> usize

Returns the number of rows in this vector.

Source

pub unsafe fn is_valid(&self, idx: usize) -> bool

Returns true if the value at row idx is not NULL.

§Safety

idx must be less than self.row_count().

Source

pub const unsafe fn read_i8(&self, idx: usize) -> i8

Reads an i8 (TINYINT) value at row idx.

§Safety

idx must be less than self.row_count().
The column must contain TINYINT data.
The value at idx must not be NULL (check with is_valid).

Source

pub const unsafe fn read_i16(&self, idx: usize) -> i16

Reads an i16 (SMALLINT) value at row idx.

§Safety

idx must be less than self.row_count().
The column must contain SMALLINT data.

Source

pub const unsafe fn read_i32(&self, idx: usize) -> i32

Reads an i32 (INTEGER) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_i64(&self, idx: usize) -> i64

Reads an i64 (BIGINT / TIMESTAMP) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_u8(&self, idx: usize) -> u8

Reads a u8 (UTINYINT) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_u16(&self, idx: usize) -> u16

Reads a u16 (USMALLINT) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_u32(&self, idx: usize) -> u32

Reads a u32 (UINTEGER) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_u64(&self, idx: usize) -> u64

Reads a u64 (UBIGINT) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_f32(&self, idx: usize) -> f32

Reads an f32 (FLOAT) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_f64(&self, idx: usize) -> f64

Reads an f64 (DOUBLE) value at row idx.

§Safety

See read_i8.

Source

pub const unsafe fn read_bool(&self, idx: usize) -> bool

Reads a bool (BOOLEAN) value at row idx.

§Pitfall L5: Defensive boolean reading

This method reads the underlying byte as u8 and compares with != 0, rather than casting directly to bool. DuckDB’s C API does not guarantee the Rust bool invariant (must be exactly 0 or 1), so a direct cast could cause undefined behaviour.

§Safety

idx must be less than self.row_count().
The column must contain BOOLEAN data.

Source

pub const unsafe fn read_i128(&self, idx: usize) -> i128

Reads an i128 (HUGEINT) value at row idx.

DuckDB stores HUGEINT as { lower: u64, upper: i64 } in little-endian layout, totaling 16 bytes per value.

§Safety

idx must be less than self.row_count().
The column must contain HUGEINT data.
The value at idx must not be NULL (check with is_valid).

Source

pub const unsafe fn read_u128(&self, idx: usize) -> u128

Reads a u128 (UHUGEINT) value at row idx.

DuckDB stores UHUGEINT as { lower: u64, upper: u64 } in little-endian layout, totalling 16 bytes per value.

§Safety

idx must be less than self.row_count().
The column must contain UHUGEINT data.

Source

pub const unsafe fn read_timestamp_tz(&self, idx: usize) -> i64

Reads a TIMESTAMP WITH TIME ZONE value at row idx, as microseconds since the Unix epoch in UTC.

§Safety

idx must be less than self.row_count().
The column must contain TIMESTAMPTZ data.

Source

pub const unsafe fn read_timestamp_s(&self, idx: usize) -> i64

Reads a TIMESTAMP_S value at row idx, as seconds since the epoch.

§Safety

idx must be less than self.row_count().
The column must contain TIMESTAMP_S data.

Source

pub const unsafe fn read_timestamp_ms(&self, idx: usize) -> i64

Reads a TIMESTAMP_MS value at row idx, as milliseconds since the epoch.

§Safety

idx must be less than self.row_count().
The column must contain TIMESTAMP_MS data.

Source

pub const unsafe fn read_timestamp_ns(&self, idx: usize) -> i64

Reads a TIMESTAMP_NS value at row idx, as nanoseconds since the epoch.

§Safety

idx must be less than self.row_count().
The column must contain TIMESTAMP_NS data.

Source

pub const unsafe fn read_time_tz(&self, idx: usize) -> u64

Reads a TIME WITH TIME ZONE value at row idx as DuckDB’s packed 64-bit representation.

Decode it with datetime::time_tz_from_bits.

§Safety

idx must be less than self.row_count().
The column must contain TIMETZ data.

Source

pub const unsafe fn read_decimal(&self, idx: usize, width: u8) -> i128

Reads a DECIMAL value at row idx as its unscaled integer.

DuckDB stores a DECIMAL in the narrowest integer that fits its declared width — i16 up to 4 digits, i32 up to 9, i64 up to 18, and i128 up to 38 — so width must be the column’s declared width. Get it from LogicalType::decimal_width.

The represented number is result / 10^scale.

§Safety

idx must be less than self.row_count().
The column must contain DECIMAL data with exactly this width.

Source

pub const fn contains(&self, idx: usize) -> bool

Returns true if idx addresses a row of this vector.

Every read_* method requires idx < row_count(); this is the check to pair with them when the index comes from somewhere other than a 0..row_count() loop.

Source

pub unsafe fn read_str(&self, idx: usize) -> &str

Reads a VARCHAR value at row idx.

Returns an empty string if the data is not valid UTF-8 or if the internal string pointer is null.

§Pitfall P7

DuckDB stores strings in a 16-byte duckdb_string_t with two formats (inline for ≤ 12 bytes, pointer otherwise). This method handles both.

§Safety

idx must be less than self.row_count().
The column must contain VARCHAR data.
For pointer-format strings, the pointed-to heap memory must be valid for the lifetime of the returned &str.

Source

pub unsafe fn read_blob(&self, idx: usize) -> &[u8] ⓘ

Reads a BLOB (binary) value at row idx.

DuckDB stores BLOBs using the same 16-byte duckdb_string_t layout as VARCHAR (inline for ≤12 bytes, pointer for larger values). The returned slice borrows from the vector’s data buffer.

The bytes are returned without UTF-8 validation.

§Safety

idx must be less than self.row_count().
The column must contain BLOB data.
The pointed-to memory must be valid for the lifetime of the returned slice.

Source

pub const unsafe fn read_uuid(&self, idx: usize) -> u128

Reads a UUID value at row idx as an i128.

Reads the UUID’s textual 128 bits — the value the column renders, and what every Rust Uuid type holds.

A UUID column is physically a HUGEINT, but DuckDB stores it with the top bit flipped so that signed integer ordering matches UUID string ordering, so the raw storage of '11111111-2222-3333-4444-555555555555' is 0x9111..., not 0x1111.... This undoes that. Use read_i128 for the raw storage, and uuid_from_storage to convert.