pub struct VectorWriter { /* private fields */ }Expand description
A typed writer for a DuckDB output vector in a finalize callback.
§Example
use quack_rs::vector::VectorWriter;
use libduckdb_sys::duckdb_vector;
// Inside finalize:
// let mut writer = unsafe { VectorWriter::new(result_vector) };
// for row in 0..count {
// if let Some(val) = compute_result(row) {
// unsafe { writer.write_i64(row, val) };
// } else {
// unsafe { writer.set_null(row) };
// }
// }Implementations§
Source§impl VectorWriter
impl VectorWriter
Sourcepub unsafe fn new(vector: duckdb_vector) -> Self
pub unsafe fn new(vector: duckdb_vector) -> Self
Creates a new VectorWriter for the given result vector.
§Safety
vector must be a valid DuckDB output vector obtained in a finalize
callback. The vector must not be destroyed while this writer is live.
Sourcepub unsafe fn from_vector(vector: duckdb_vector) -> Self
pub unsafe fn from_vector(vector: duckdb_vector) -> Self
Creates a VectorWriter directly from a raw duckdb_vector handle.
Use this when you need to write into a child vector (e.g., a STRUCT field
or LIST element vector) obtained from
StructVector::get_child or
ListVector::get_child.
§Safety
vector must be a valid, writable duckdb_vector. The vector must not be
destroyed while this writer is live. If vector lies inside the child
of a LIST or MAP vector — is that child, or a STRUCT field or ARRAY
element vector below it with no other LIST or MAP in between — the
writer must not be used after that LIST or MAP is grown with a
reserve: growing reallocates the data and validity buffers of every
such vector, and the writer caches pointers to both. (Measured by
tests/ffi_roundtrip/nested_reserve.rs.)
Sourcepub const unsafe fn write_i8(&mut self, idx: usize, value: i8)
pub const unsafe fn write_i8(&mut self, idx: usize, value: i8)
Writes an i8 (TINYINT) value at row idx.
§Safety
idxmust be within the vector’s capacity.- The vector must have
TINYINTtype.
Sourcepub unsafe fn write_bool(&mut self, idx: usize, value: bool)
pub unsafe fn write_bool(&mut self, idx: usize, value: bool)
Writes a bool (BOOLEAN) value at row idx.
Booleans are stored as a single byte: 1 for true, 0 for false.
§Safety
idxmust be within the vector’s capacity.- The vector must have
BOOLEANtype.
Sourcepub const unsafe fn write_i128(&mut self, idx: usize, value: i128)
pub const unsafe fn write_i128(&mut self, idx: usize, value: i128)
Writes an i128 (HUGEINT) value at row idx.
DuckDB stores HUGEINT as { lower: u64, upper: i64 }, lower first,
each in the target’s byte order: 16 bytes per value.
§Safety
idxmust be within the vector’s capacity.- The vector must have
HUGEINTtype.
Sourcepub unsafe fn write_varchar(&mut self, idx: usize, value: &str)
pub unsafe fn write_varchar(&mut self, idx: usize, value: &str)
Writes a VARCHAR string value at row idx.
This uses duckdb_vector_assign_string_element_len which handles both
the inline (≤12 bytes) and pointer (>12 bytes) storage formats
automatically. DuckDB manages the memory for the string data.
§Panics
Panics if value is longer than
MAX_STRING_LEN (4 GiB − 1),
the most a DuckDB string can hold. Writing it anyway would store the
length modulo 2^32 — a silently truncated value. Inside
scalar_callback! and the typed scalar
constructors the panic becomes a SQL error; use
try_write_varchar to handle it yourself.
§Safety
idxmust be within the vector’s capacity.- The vector must have
VARCHARtype.
Sourcepub unsafe fn try_write_varchar(
&mut self,
idx: usize,
value: &str,
) -> Result<(), ExtensionError>
pub unsafe fn try_write_varchar( &mut self, idx: usize, value: &str, ) -> Result<(), ExtensionError>
Writes a VARCHAR string value at row idx, or returns an error — writing
nothing — if value is longer than
MAX_STRING_LEN.
§Errors
Returns an error if value.len() exceeds MAX_STRING_LEN.
§Safety
See write_varchar.
Sourcepub const unsafe fn write_date(&mut self, idx: usize, days_since_epoch: i32)
pub const unsafe fn write_date(&mut self, idx: usize, days_since_epoch: i32)
Sourcepub const unsafe fn write_timestamp(
&mut self,
idx: usize,
micros_since_epoch: i64,
)
pub const unsafe fn write_timestamp( &mut self, idx: usize, micros_since_epoch: i64, )
Writes a TIMESTAMP value at row idx as microseconds since the Unix epoch.
DuckDB stores TIMESTAMP as an 8-byte i64. This is a semantic alias for
write_i64. The value is not range-checked: one below
DuckDB’s earliest timestamp (other than -infinity, -i64::MAX) makes
every later cast or rendering of the row fail with “Date out of range in
timestamp conversion”. The same holds for the other timestamp writers.
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMESTAMPtype.
Sourcepub const unsafe fn write_time(
&mut self,
idx: usize,
micros_since_midnight: i64,
)
pub const unsafe fn write_time( &mut self, idx: usize, micros_since_midnight: i64, )
Writes a TIME value at row idx as microseconds since midnight.
DuckDB stores TIME as an 8-byte i64. This is a semantic alias for
write_i64.
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMEtype. micros_since_midnightmust be in0..=86_400_000_000(00:00:00to24:00:00).DuckDBdoes not check aTIMEit reads back: when it renders one,i64::MINcrashes the process (a segfault inTime::Convert, checked on 1.5.5),i64::MAXraises an internal error, and-1renders as00:00:00.00000/.
Sourcepub const unsafe fn write_interval(&mut self, idx: usize, value: DuckInterval)
pub const unsafe fn write_interval(&mut self, idx: usize, value: DuckInterval)
Writes an INTERVAL value at row idx.
DuckDB stores INTERVAL as { months: i32, days: i32, micros: i64 } in a
16-byte layout. This method writes all three components at the correct offsets.
§Safety
idxmust be within the vector’s capacity.- The vector must have
INTERVALtype.
Sourcepub unsafe fn write_blob(&mut self, idx: usize, value: &[u8])
pub unsafe fn write_blob(&mut self, idx: usize, value: &[u8])
Writes a BLOB (binary) value at row idx.
This uses the same underlying storage as VARCHAR — DuckDB stores BLOBs
using duckdb_vector_assign_string_element_len, which copies the data.
§Panics
Panics if value is longer than
MAX_STRING_LEN; see
write_varchar. Use
try_write_blob to handle it yourself.
§Safety
idxmust be within the vector’s capacity.- The vector must have
BLOBtype.
Sourcepub unsafe fn try_write_blob(
&mut self,
idx: usize,
value: &[u8],
) -> Result<(), ExtensionError>
pub unsafe fn try_write_blob( &mut self, idx: usize, value: &[u8], ) -> Result<(), ExtensionError>
Writes a BLOB value at row idx, or returns an error — writing
nothing — if value is longer than
MAX_STRING_LEN.
§Errors
Returns an error if value.len() exceeds MAX_STRING_LEN.
§Safety
See write_blob.
Sourcepub const unsafe fn write_uuid(&mut self, idx: usize, bits: u128)
pub const unsafe fn write_uuid(&mut self, idx: usize, bits: u128)
Writes a UUID value at row idx.
Writes bits — the UUID’s textual 128 bits, as every Rust Uuid
type holds them — at row idx.
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. This applies that flip, so the value you pass is the value the
column renders. Use write_i128 to write the raw
storage instead, and uuid_to_storage
to convert between the two.
§Safety
idxmust be within the vector’s capacity.- The vector must have
UUIDtype.
Sourcepub unsafe fn write_str(&mut self, idx: usize, value: &str)
pub unsafe fn write_str(&mut self, idx: usize, value: &str)
Writes a VARCHAR string value at row idx.
This is an alias for write_varchar provided
for discoverability — extension authors often look for write_str first.
§Safety
idxmust be within the vector’s capacity.- The vector must have
VARCHARtype.
Sourcepub const unsafe fn write_u128(&mut self, idx: usize, value: u128)
pub const unsafe fn write_u128(&mut self, idx: usize, value: u128)
Writes a u128 (UHUGEINT) value at row idx.
DuckDB stores UHUGEINT as { lower: u64, upper: u64 }, lower first,
each in the target’s byte order: 16 bytes per value.
§Safety
idxmust be within the vector’s capacity.- The vector must have
UHUGEINTtype.
Sourcepub const unsafe fn write_timestamp_tz(
&mut self,
idx: usize,
micros_since_epoch: i64,
)
pub const unsafe fn write_timestamp_tz( &mut self, idx: usize, micros_since_epoch: i64, )
Writes a TIMESTAMP WITH TIME ZONE value at row idx, as microseconds
since the Unix epoch in UTC.
TIMESTAMPTZ shares TIMESTAMP’s 8-byte i64 storage; only the logical
type differs.
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMESTAMPTZtype.
Sourcepub const unsafe fn write_timestamp_s(
&mut self,
idx: usize,
seconds_since_epoch: i64,
)
pub const unsafe fn write_timestamp_s( &mut self, idx: usize, seconds_since_epoch: i64, )
Writes a TIMESTAMP_S value at row idx, as seconds since the epoch.
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMESTAMP_Stype.
Sourcepub const unsafe fn write_timestamp_ms(
&mut self,
idx: usize,
millis_since_epoch: i64,
)
pub const unsafe fn write_timestamp_ms( &mut self, idx: usize, millis_since_epoch: i64, )
Writes a TIMESTAMP_MS value at row idx, as milliseconds since the
epoch.
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMESTAMP_MStype.
Sourcepub const unsafe fn write_timestamp_ns(
&mut self,
idx: usize,
nanos_since_epoch: i64,
)
pub const unsafe fn write_timestamp_ns( &mut self, idx: usize, nanos_since_epoch: i64, )
Writes a TIMESTAMP_NS value at row idx, as nanoseconds since the
epoch.
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMESTAMP_NStype.
Sourcepub const unsafe fn write_timestamp_tz_ns(
&mut self,
idx: usize,
nanos_since_epoch: i64,
)
pub const unsafe fn write_timestamp_tz_ns( &mut self, idx: usize, nanos_since_epoch: i64, )
Writes a TIMESTAMPTZ_NS value at row idx, as nanoseconds since the
epoch (DuckDB 2.0.0+).
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMESTAMPTZ_NStype.
Sourcepub const unsafe fn write_time_tz(&mut self, idx: usize, bits: u64)
pub const unsafe fn write_time_tz(&mut self, idx: usize, bits: u64)
Writes a TIME WITH TIME ZONE value at row idx.
bits is DuckDB’s packed representation; build one with
datetime::time_tz_bits rather than
assembling it by hand. DuckDB does not check it: an encoding with a
time past 24:00:00 or an offset past ±15:59:59 renders as garbage
(u64::MAX as b}:25:11.627775-4644:20:16).
§Safety
idxmust be within the vector’s capacity.- The vector must have
TIMETZtype.
Sourcepub const unsafe fn write_decimal(
&mut self,
idx: usize,
width: u8,
unscaled: i128,
)
pub const unsafe fn write_decimal( &mut self, idx: usize, width: u8, unscaled: i128, )
Writes a DECIMAL value at row idx from its unscaled representation.
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 beyond — so the width must match the column’s type. Get it from
LogicalType::decimal_width.
§Safety
idxmust be within the vector’s capacity.- The vector must have
DECIMALtype with exactly thiswidth.
Sourcepub unsafe fn set_null(&mut self, idx: usize)
pub unsafe fn set_null(&mut self, idx: usize)
Marks row idx as NULL in the output vector.
For a STRUCT vector this also marks row idx NULL in every field,
recursively; for an ARRAY vector of size n, child rows
idx * n .. idx * n + n. See the
module docs.
set_valid undoes all of it.
§Pitfall L4: ensure_validity_writable
This method calls duckdb_vector_ensure_validity_writable before
duckdb_vector_get_validity, which is required before writing any NULL
flags. Without it, a vector that has no mask yet yields a NULL mask
pointer and the NULL is silently dropped.
§Safety
idxmust be within the vector’s capacity.
Sourcepub unsafe fn set_null_range(&mut self, range: Range<usize>)
pub unsafe fn set_null_range(&mut self, range: Range<usize>)
Sourcepub unsafe fn set_valid(&mut self, idx: usize)
pub unsafe fn set_valid(&mut self, idx: usize)
Marks row idx as valid (non-NULL) in the output vector.
Use this to undo a previous set_null call for a row,
or to explicitly mark a row as valid after writing its value.
If the row is NULL, this also marks valid everything
set_null marked NULL below it — every field of a
STRUCT row and every element of an ARRAY row, recursively — so
that values written there afterwards are read. Write any field or
element NULLs after this call. If the row is already valid, nothing
below it is touched, so marking a row valid after writing its fields
keeps any field NULLs.
Like set_null, this calls ensure_validity_writable
before modifying the validity bitmap.
§Safety
idxmust be within the vector’s capacity.