Struct VectorReader 

pub struct VectorReader { /* private fields */ }

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

impl VectorReader

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.

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.

pub const fn row_count(&self) -> usize

Returns the number of rows in this vector.

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().

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).

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.

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

Reads an i32 (INTEGER) value at row idx.

Safety

See read_i8.

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

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

Safety

See read_i8.

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

Reads a u8 (UTINYINT) value at row idx.

Safety

See read_i8.

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

Reads a u16 (USMALLINT) value at row idx.

Safety

See read_i8.

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

Reads a u32 (UINTEGER) value at row idx.

Safety

See read_i8.

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

Reads a u64 (UBIGINT) value at row idx.

Safety

See read_i8.

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

Reads an f32 (FLOAT) value at row idx.

Safety

See read_i8.

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

Reads an f64 (DOUBLE) value at row idx.

Safety

See read_i8.

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.

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).

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.

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.

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.

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

Reads a UUID value at row idx as an i128.

DuckDB stores UUID as a HUGEINT (128-bit integer). This is a semantic alias for read_i128.

Safety

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

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

Reads a DATE value at row idx as days since the Unix epoch.

DuckDB stores DATE as a 4-byte i32 representing the number of days since 1970-01-01. This is a semantic alias for read_i32.

Safety

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

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

Reads a TIMESTAMP value at row idx as microseconds since the Unix epoch.

DuckDB stores TIMESTAMP as an 8-byte i64 representing microseconds since 1970-01-01 00:00:00 UTC. This is a semantic alias for read_i64.

Safety

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

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

Reads a TIME value at row idx as microseconds since midnight.

DuckDB stores TIME as an 8-byte i64 representing microseconds since midnight. This is a semantic alias for read_i64.

Safety

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

pub const unsafe fn read_interval(&self, idx: usize) -> DuckInterval

Reads an INTERVAL value at row idx.

Returns a DuckInterval struct.

Pitfall P8

The INTERVAL struct is 16 bytes: { months: i32, days: i32, micros: i64 }. This method handles the layout correctly using read_interval_at.

Safety

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