quack_rs/vector/writer.rs
1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Safe typed writing to `DuckDB` result vectors.
7//!
8//! [`VectorWriter`] provides safe methods for writing typed values and NULL
9//! flags to a `DuckDB` output vector from within a `finalize` callback.
10//!
11//! # Pitfall L4: `ensure_validity_writable`
12//!
13//! When writing NULL values, you must call `duckdb_vector_ensure_validity_writable`
14//! before `duckdb_vector_get_validity`. A vector with no NULLs yet usually has no
15//! validity mask at all, and then `get_validity` returns NULL; the
16//! `duckdb_validity_set_row_*` functions return early on a NULL mask, so the
17//! NULL is **silently dropped** and the row reads back as a valid value.
18//!
19//! [`VectorWriter::set_null`] calls `ensure_validity_writable` automatically.
20//!
21//! # NULLs in nested vectors
22//!
23//! Marking a `STRUCT` or `ARRAY` row NULL also marks its children NULL — every
24//! field of the struct row, every element of the array row, recursively —
25//! exactly as `DuckDB`'s internal `FlatVector::SetNull` does. Without that,
26//! `struct_extract(s, 'a')` on a NULL row returns whatever was last written to
27//! field `a`. `LIST` and `MAP` children are not touched, matching `DuckDB`.
28
29use libduckdb_sys::{
30 duckdb_validity_set_row_invalid, duckdb_validity_set_row_valid, duckdb_vector,
31 duckdb_vector_assign_string_element_len, duckdb_vector_ensure_validity_writable,
32 duckdb_vector_get_data, duckdb_vector_get_validity, idx_t,
33};
34
35use super::nested_null::{self, NullTarget};
36use super::string::check_string_len;
37use crate::error::ExtensionError;
38
39/// A typed writer for a `DuckDB` output vector in a `finalize` callback.
40///
41/// # Example
42///
43/// ```rust,no_run
44/// use quack_rs::vector::VectorWriter;
45/// use libduckdb_sys::duckdb_vector;
46///
47/// // Inside finalize:
48/// // let mut writer = unsafe { VectorWriter::new(result_vector) };
49/// // for row in 0..count {
50/// // if let Some(val) = compute_result(row) {
51/// // unsafe { writer.write_i64(row, val) };
52/// // } else {
53/// // unsafe { writer.set_null(row) };
54/// // }
55/// // }
56/// ```
57#[derive(Debug)]
58pub struct VectorWriter {
59 vector: duckdb_vector,
60 data: *mut u8,
61 /// Lazily-resolved NULL-writing state; `None` until the first
62 /// `set_null` / `set_valid`. Boxed so a writer that never writes a NULL
63 /// stays three words and allocates nothing.
64 nulls: Option<Box<NullState>>,
65}
66
67/// What [`VectorWriter`] resolves once, on its first NULL write.
68#[derive(Debug)]
69struct NullState {
70 /// The writable validity bitmap.
71 ///
72 /// `duckdb_vector_ensure_validity_writable` allocates the mask on first use
73 /// and is a no-op afterwards, and the resulting pointer is stable until the
74 /// vector's buffers are reallocated — which only a `reserve` on a `LIST` or
75 /// `MAP` whose child holds this vector (directly, or through STRUCT fields
76 /// and ARRAY elements) does, and which `from_vector`'s contract rules out
77 /// while the writer is in use. Caching it turns "two FFI calls per NULL" into "two
78 /// FFI calls per vector", which matters when a column is mostly NULL: a full
79 /// 2048-row vector went from 4096 calls to 2.
80 validity: *mut u64,
81 /// Child masks a NULL must also clear (STRUCT fields, ARRAY elements),
82 /// resolved on the first `set_null`. `None` until then; empty for a
83 /// vector that is neither STRUCT nor ARRAY. Resolving walks the type once
84 /// per writer rather than once per NULL row.
85 nested: Option<Vec<NullTarget>>,
86}
87
88impl VectorWriter {
89 /// Creates a new `VectorWriter` for the given result vector.
90 ///
91 /// # Safety
92 ///
93 /// `vector` must be a valid `DuckDB` output vector obtained in a `finalize`
94 /// callback. The vector must not be destroyed while this writer is live.
95 pub unsafe fn new(vector: duckdb_vector) -> Self {
96 // SAFETY: Caller guarantees vector is valid.
97 let data = unsafe { duckdb_vector_get_data(vector) }.cast::<u8>();
98 Self {
99 vector,
100 data,
101 nulls: None,
102 }
103 }
104
105 /// Creates a `VectorWriter` directly from a raw `duckdb_vector` handle.
106 ///
107 /// Use this when you need to write into a child vector (e.g., a STRUCT field
108 /// or LIST element vector) obtained from
109 /// [`StructVector::get_child`][crate::vector::complex::StructVector::get_child] or
110 /// [`ListVector::get_child`][crate::vector::complex::ListVector::get_child].
111 ///
112 /// # Safety
113 ///
114 /// `vector` must be a valid, writable `duckdb_vector`. The vector must not be
115 /// destroyed while this writer is live. If `vector` lies inside the child
116 /// of a `LIST` or `MAP` vector — is that child, or a STRUCT field or ARRAY
117 /// element vector below it with no other `LIST` or `MAP` in between — the
118 /// writer must not be used after that `LIST` or `MAP` is grown with a
119 /// `reserve`: growing reallocates the data and validity buffers of every
120 /// such vector, and the writer caches pointers to both. (Measured by
121 /// `tests/ffi_roundtrip/nested_reserve.rs`.)
122 pub unsafe fn from_vector(vector: duckdb_vector) -> Self {
123 // SAFETY: caller guarantees vector is valid.
124 let data = unsafe { duckdb_vector_get_data(vector) }.cast::<u8>();
125 Self {
126 vector,
127 data,
128 nulls: None,
129 }
130 }
131
132 /// Writes an `i8` (TINYINT) value at row `idx`.
133 ///
134 /// # Safety
135 ///
136 /// - `idx` must be within the vector's capacity.
137 /// - The vector must have `TINYINT` type.
138 #[inline]
139 pub const unsafe fn write_i8(&mut self, idx: usize, value: i8) {
140 // SAFETY: data points to a valid writable TINYINT array. idx is in bounds.
141 unsafe { core::ptr::write_unaligned(self.data.add(idx).cast::<i8>(), value) };
142 }
143
144 /// Writes an `i16` (SMALLINT) value at row `idx`.
145 ///
146 /// # Safety
147 ///
148 /// See [`write_i8`][Self::write_i8].
149 #[inline]
150 pub const unsafe fn write_i16(&mut self, idx: usize, value: i16) {
151 // SAFETY: 2-byte aligned write to valid SMALLINT vector.
152 unsafe { core::ptr::write_unaligned(self.data.add(idx * 2).cast::<i16>(), value) };
153 }
154
155 /// Writes an `i32` (INTEGER) value at row `idx`.
156 ///
157 /// # Safety
158 ///
159 /// See [`write_i8`][Self::write_i8].
160 #[inline]
161 pub const unsafe fn write_i32(&mut self, idx: usize, value: i32) {
162 // SAFETY: 4-byte aligned write to valid INTEGER vector.
163 unsafe { core::ptr::write_unaligned(self.data.add(idx * 4).cast::<i32>(), value) };
164 }
165
166 /// Writes an `i64` (BIGINT / TIMESTAMP) value at row `idx`.
167 ///
168 /// # Safety
169 ///
170 /// See [`write_i8`][Self::write_i8].
171 #[inline]
172 pub const unsafe fn write_i64(&mut self, idx: usize, value: i64) {
173 // SAFETY: 8-byte aligned write to valid BIGINT vector.
174 unsafe { core::ptr::write_unaligned(self.data.add(idx * 8).cast::<i64>(), value) };
175 }
176
177 /// Writes a `u8` (UTINYINT) value at row `idx`.
178 ///
179 /// # Safety
180 ///
181 /// See [`write_i8`][Self::write_i8].
182 #[inline]
183 pub const unsafe fn write_u8(&mut self, idx: usize, value: u8) {
184 // SAFETY: 1-byte write to valid UTINYINT vector.
185 unsafe { *self.data.add(idx) = value };
186 }
187
188 /// Writes a `u32` (UINTEGER) value at row `idx`.
189 ///
190 /// # Safety
191 ///
192 /// See [`write_i8`][Self::write_i8].
193 #[inline]
194 pub const unsafe fn write_u32(&mut self, idx: usize, value: u32) {
195 // SAFETY: 4-byte aligned write to valid UINTEGER vector.
196 unsafe { core::ptr::write_unaligned(self.data.add(idx * 4).cast::<u32>(), value) };
197 }
198
199 /// Writes a `u64` (UBIGINT) value at row `idx`.
200 ///
201 /// # Safety
202 ///
203 /// See [`write_i8`][Self::write_i8].
204 #[inline]
205 pub const unsafe fn write_u64(&mut self, idx: usize, value: u64) {
206 // SAFETY: 8-byte aligned write to valid UBIGINT vector.
207 unsafe { core::ptr::write_unaligned(self.data.add(idx * 8).cast::<u64>(), value) };
208 }
209
210 /// Writes an `f32` (FLOAT) value at row `idx`.
211 ///
212 /// # Safety
213 ///
214 /// See [`write_i8`][Self::write_i8].
215 #[inline]
216 pub const unsafe fn write_f32(&mut self, idx: usize, value: f32) {
217 // SAFETY: 4-byte aligned write to valid FLOAT vector.
218 unsafe { core::ptr::write_unaligned(self.data.add(idx * 4).cast::<f32>(), value) };
219 }
220
221 /// Writes an `f64` (DOUBLE) value at row `idx`.
222 ///
223 /// # Safety
224 ///
225 /// See [`write_i8`][Self::write_i8].
226 #[inline]
227 pub const unsafe fn write_f64(&mut self, idx: usize, value: f64) {
228 // SAFETY: 8-byte aligned write to valid DOUBLE vector.
229 unsafe { core::ptr::write_unaligned(self.data.add(idx * 8).cast::<f64>(), value) };
230 }
231
232 /// Writes a `bool` (BOOLEAN) value at row `idx`.
233 ///
234 /// Booleans are stored as a single byte: `1` for `true`, `0` for `false`.
235 ///
236 /// # Safety
237 ///
238 /// - `idx` must be within the vector's capacity.
239 /// - The vector must have `BOOLEAN` type.
240 #[inline]
241 pub unsafe fn write_bool(&mut self, idx: usize, value: bool) {
242 // SAFETY: BOOLEAN stored as 1 byte.
243 unsafe { *self.data.add(idx) = u8::from(value) };
244 }
245
246 /// Writes an `i128` (HUGEINT) value at row `idx`.
247 ///
248 /// `DuckDB` stores HUGEINT as `{ lower: u64, upper: i64 }`, `lower` first,
249 /// each in the target's byte order: 16 bytes per value.
250 ///
251 /// # Safety
252 ///
253 /// - `idx` must be within the vector's capacity.
254 /// - The vector must have `HUGEINT` type.
255 #[inline]
256 pub const unsafe fn write_i128(&mut self, idx: usize, value: i128) {
257 // SAFETY: HUGEINT = { lower: u64, upper: i64 } = 16 bytes.
258 let base = unsafe { self.data.add(idx * 16) };
259 #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
260 let lower = value as u64;
261 #[allow(clippy::cast_possible_truncation)]
262 let upper = (value >> 64) as i64;
263 // SAFETY: `base` and `base + 8` are the `lower`/`upper` halves of row
264 // `idx`'s 16-byte `duckdb_hugeint` ({uint64_t lower; int64_t upper},
265 // duckdb.h) in `self.data`, the flat data buffer the constructor's contract
266 // keeps valid. Both 8-byte writes stay in bounds because `idx` is within
267 // the vector's capacity (`# Safety` clause 1) and a HUGEINT vector (clause
268 // 2) stores 16 bytes per row; `write_unaligned` needs no alignment.
269 unsafe {
270 core::ptr::write_unaligned(base.cast::<u64>(), lower);
271 core::ptr::write_unaligned(base.add(8).cast::<i64>(), upper);
272 }
273 }
274
275 /// Writes a `u16` (USMALLINT) value at row `idx`.
276 ///
277 /// # Safety
278 ///
279 /// See [`write_i8`][Self::write_i8].
280 #[inline]
281 pub const unsafe fn write_u16(&mut self, idx: usize, value: u16) {
282 // SAFETY: 2-byte aligned write to valid USMALLINT vector.
283 unsafe { core::ptr::write_unaligned(self.data.add(idx * 2).cast::<u16>(), value) };
284 }
285
286 /// Writes a VARCHAR string value at row `idx`.
287 ///
288 /// This uses `duckdb_vector_assign_string_element_len` which handles both
289 /// the inline (≤12 bytes) and pointer (>12 bytes) storage formats
290 /// automatically. `DuckDB` manages the memory for the string data.
291 ///
292 /// # Panics
293 ///
294 /// Panics if `value` is longer than
295 /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN] (4 GiB − 1),
296 /// the most a `DuckDB` string can hold. Writing it anyway would store the
297 /// length modulo 2^32 — a silently truncated value. Inside
298 /// [`scalar_callback!`][crate::scalar_callback] and the typed scalar
299 /// constructors the panic becomes a SQL error; use
300 /// [`try_write_varchar`][Self::try_write_varchar] to handle it yourself.
301 ///
302 /// # Safety
303 ///
304 /// - `idx` must be within the vector's capacity.
305 /// - The vector must have `VARCHAR` type.
306 pub unsafe fn write_varchar(&mut self, idx: usize, value: &str) {
307 // SAFETY: forwarded from this method's own contract.
308 if let Err(e) = unsafe { self.try_write_varchar(idx, value) } {
309 panic!("write_varchar: {e}");
310 }
311 }
312
313 /// Writes a VARCHAR string value at row `idx`, or returns an error — writing
314 /// nothing — if `value` is longer than
315 /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN].
316 ///
317 /// # Errors
318 ///
319 /// Returns an error if `value.len()` exceeds `MAX_STRING_LEN`.
320 ///
321 /// # Safety
322 ///
323 /// See [`write_varchar`][Self::write_varchar].
324 pub unsafe fn try_write_varchar(
325 &mut self,
326 idx: usize,
327 value: &str,
328 ) -> Result<(), ExtensionError> {
329 // SAFETY: forwarded from this method's own contract.
330 unsafe { self.try_assign_string(idx, value.as_bytes()) }
331 }
332
333 /// Stores `bytes` as the `duckdb_string_t` at row `idx` after checking its
334 /// length. `DuckDB` copies the bytes.
335 ///
336 /// # Safety
337 ///
338 /// `idx` must be within the vector's capacity, and the vector must be
339 /// `VARCHAR` (with `bytes` valid UTF-8) or `BLOB`.
340 unsafe fn try_assign_string(&mut self, idx: usize, bytes: &[u8]) -> Result<(), ExtensionError> {
341 check_string_len(bytes.len())?;
342 // SAFETY: self.vector is valid and idx in bounds per the caller's
343 // contract; the length fits in `u32`, so DuckDB's narrowing is exact.
344 unsafe {
345 duckdb_vector_assign_string_element_len(
346 self.vector,
347 idx as idx_t,
348 bytes.as_ptr().cast::<std::os::raw::c_char>(),
349 bytes.len() as idx_t,
350 );
351 }
352 Ok(())
353 }
354
355 /// Writes a `DATE` value at row `idx` as days since the Unix epoch.
356 ///
357 /// `DuckDB` stores DATE as a 4-byte `i32`. This is a semantic alias for
358 /// [`write_i32`][Self::write_i32].
359 ///
360 /// # Safety
361 ///
362 /// - `idx` must be within the vector's capacity.
363 /// - The vector must have `DATE` type.
364 #[inline]
365 pub const unsafe fn write_date(&mut self, idx: usize, days_since_epoch: i32) {
366 // SAFETY: DATE is stored as i32.
367 unsafe { self.write_i32(idx, days_since_epoch) };
368 }
369
370 /// Writes a `TIMESTAMP` value at row `idx` as microseconds since the Unix epoch.
371 ///
372 /// `DuckDB` stores TIMESTAMP as an 8-byte `i64`. This is a semantic alias for
373 /// [`write_i64`][Self::write_i64]. The value is not range-checked: one below
374 /// `DuckDB`'s earliest timestamp (other than `-infinity`, `-i64::MAX`) makes
375 /// every later cast or rendering of the row fail with "Date out of range in
376 /// timestamp conversion". The same holds for the other timestamp writers.
377 ///
378 /// # Safety
379 ///
380 /// - `idx` must be within the vector's capacity.
381 /// - The vector must have `TIMESTAMP` type.
382 #[inline]
383 pub const unsafe fn write_timestamp(&mut self, idx: usize, micros_since_epoch: i64) {
384 // SAFETY: TIMESTAMP is stored as i64.
385 unsafe { self.write_i64(idx, micros_since_epoch) };
386 }
387
388 /// Writes a `TIME` value at row `idx` as microseconds since midnight.
389 ///
390 /// `DuckDB` stores TIME as an 8-byte `i64`. This is a semantic alias for
391 /// [`write_i64`][Self::write_i64].
392 ///
393 /// # Safety
394 ///
395 /// - `idx` must be within the vector's capacity.
396 /// - The vector must have `TIME` type.
397 /// - `micros_since_midnight` must be in `0..=86_400_000_000` (`00:00:00`
398 /// to `24:00:00`). `DuckDB` does not check a `TIME` it reads back: when
399 /// it renders one, `i64::MIN` crashes the process (a segfault in
400 /// `Time::Convert`, checked on 1.5.5), `i64::MAX` raises an internal
401 /// error, and `-1` renders as `00:00:00.00000/`.
402 #[inline]
403 pub const unsafe fn write_time(&mut self, idx: usize, micros_since_midnight: i64) {
404 // SAFETY: TIME is stored as i64.
405 unsafe { self.write_i64(idx, micros_since_midnight) };
406 }
407
408 /// Writes an INTERVAL value at row `idx`.
409 ///
410 /// `DuckDB` stores INTERVAL as `{ months: i32, days: i32, micros: i64 }` in a
411 /// 16-byte layout. This method writes all three components at the correct offsets.
412 ///
413 /// # Safety
414 ///
415 /// - `idx` must be within the vector's capacity.
416 /// - The vector must have `INTERVAL` type.
417 #[inline]
418 pub const unsafe fn write_interval(
419 &mut self,
420 idx: usize,
421 value: crate::interval::DuckInterval,
422 ) {
423 // SAFETY: INTERVAL = { months: i32 @ 0, days: i32 @ 4, micros: i64 @ 8 } = 16 bytes.
424 let base = unsafe { self.data.add(idx * 16) };
425 // SAFETY: `base`, `base + 4` and `base + 8` are the `months`, `days` and
426 // `micros` fields of row `idx`'s 16-byte `duckdb_interval` ({int32_t;
427 // int32_t; int64_t}, duckdb.h) in `self.data`, the flat data buffer the
428 // constructor's contract keeps valid. All writes stay in bounds because
429 // `idx` is within the vector's capacity (`# Safety` clause 1) and an
430 // INTERVAL vector (clause 2) stores 16 bytes per row; `write_unaligned`
431 // needs no alignment.
432 unsafe {
433 core::ptr::write_unaligned(base.cast::<i32>(), value.months);
434 core::ptr::write_unaligned(base.add(4).cast::<i32>(), value.days);
435 core::ptr::write_unaligned(base.add(8).cast::<i64>(), value.micros);
436 }
437 }
438
439 /// Writes a `BLOB` (binary) value at row `idx`.
440 ///
441 /// This uses the same underlying storage as VARCHAR — `DuckDB` stores BLOBs
442 /// using `duckdb_vector_assign_string_element_len`, which copies the data.
443 ///
444 /// # Panics
445 ///
446 /// Panics if `value` is longer than
447 /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN]; see
448 /// [`write_varchar`][Self::write_varchar]. Use
449 /// [`try_write_blob`][Self::try_write_blob] to handle it yourself.
450 ///
451 /// # Safety
452 ///
453 /// - `idx` must be within the vector's capacity.
454 /// - The vector must have `BLOB` type.
455 pub unsafe fn write_blob(&mut self, idx: usize, value: &[u8]) {
456 // SAFETY: forwarded from this method's own contract.
457 if let Err(e) = unsafe { self.try_write_blob(idx, value) } {
458 panic!("write_blob: {e}");
459 }
460 }
461
462 /// Writes a `BLOB` value at row `idx`, or returns an error — writing
463 /// nothing — if `value` is longer than
464 /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN].
465 ///
466 /// # Errors
467 ///
468 /// Returns an error if `value.len()` exceeds `MAX_STRING_LEN`.
469 ///
470 /// # Safety
471 ///
472 /// See [`write_blob`][Self::write_blob].
473 pub unsafe fn try_write_blob(
474 &mut self,
475 idx: usize,
476 value: &[u8],
477 ) -> Result<(), ExtensionError> {
478 // SAFETY: forwarded from this method's own contract.
479 unsafe { self.try_assign_string(idx, value) }
480 }
481
482 /// Writes a `UUID` value at row `idx`.
483 ///
484 /// Writes `bits` — the UUID's **textual** 128 bits, as every Rust `Uuid`
485 /// type holds them — at row `idx`.
486 ///
487 /// A `UUID` column is physically a `HUGEINT`, but `DuckDB` stores it with
488 /// the top bit flipped so that signed integer ordering matches UUID string
489 /// ordering. This applies that flip, so the value you pass is the value the
490 /// column renders. Use [`write_i128`][Self::write_i128] to write the raw
491 /// storage instead, and [`uuid_to_storage`][crate::vector::uuid_to_storage]
492 /// to convert between the two.
493 ///
494 /// # Safety
495 ///
496 /// - `idx` must be within the vector's capacity.
497 /// - The vector must have `UUID` type.
498 #[inline]
499 pub const unsafe fn write_uuid(&mut self, idx: usize, bits: u128) {
500 // SAFETY: UUID is stored as HUGEINT, with DuckDB's top-bit flip applied.
501 unsafe { self.write_i128(idx, crate::vector::uuid::uuid_to_storage(bits)) };
502 }
503
504 /// Writes a VARCHAR string value at row `idx`.
505 ///
506 /// This is an alias for [`write_varchar`][VectorWriter::write_varchar] provided
507 /// for discoverability — extension authors often look for `write_str` first.
508 ///
509 /// # Safety
510 ///
511 /// - `idx` must be within the vector's capacity.
512 /// - The vector must have `VARCHAR` type.
513 #[inline]
514 pub unsafe fn write_str(&mut self, idx: usize, value: &str) {
515 // SAFETY: Delegates to write_varchar; same contract.
516 unsafe { self.write_varchar(idx, value) };
517 }
518
519 /// Writes a `u128` (UHUGEINT) value at row `idx`.
520 ///
521 /// `DuckDB` stores UHUGEINT as `{ lower: u64, upper: u64 }`, `lower` first,
522 /// each in the target's byte order: 16 bytes per value.
523 ///
524 /// # Safety
525 ///
526 /// - `idx` must be within the vector's capacity.
527 /// - The vector must have `UHUGEINT` type.
528 #[inline]
529 pub const unsafe fn write_u128(&mut self, idx: usize, value: u128) {
530 // SAFETY: UHUGEINT = { lower: u64, upper: u64 } = 16 bytes.
531 let base = unsafe { self.data.add(idx * 16) };
532 #[allow(clippy::cast_possible_truncation)]
533 let lower = value as u64;
534 #[allow(clippy::cast_possible_truncation)]
535 let upper = (value >> 64) as u64;
536 // SAFETY: `base` and `base + 8` are the `lower`/`upper` halves of row
537 // `idx`'s 16-byte `duckdb_uhugeint` ({uint64_t lower; uint64_t upper},
538 // duckdb.h) in `self.data`, the flat data buffer the constructor's contract
539 // keeps valid. Both 8-byte writes stay in bounds because `idx` is within
540 // the vector's capacity (`# Safety` clause 1) and a UHUGEINT vector (clause
541 // 2) stores 16 bytes per row; `write_unaligned` needs no alignment.
542 unsafe {
543 core::ptr::write_unaligned(base.cast::<u64>(), lower);
544 core::ptr::write_unaligned(base.add(8).cast::<u64>(), upper);
545 }
546 }
547
548 /// Writes a `TIMESTAMP WITH TIME ZONE` value at row `idx`, as microseconds
549 /// since the Unix epoch in UTC.
550 ///
551 /// `TIMESTAMPTZ` shares `TIMESTAMP`'s 8-byte `i64` storage; only the logical
552 /// type differs.
553 ///
554 /// # Safety
555 ///
556 /// - `idx` must be within the vector's capacity.
557 /// - The vector must have `TIMESTAMPTZ` type.
558 #[inline]
559 pub const unsafe fn write_timestamp_tz(&mut self, idx: usize, micros_since_epoch: i64) {
560 // SAFETY: TIMESTAMPTZ is stored as i64 microseconds.
561 unsafe { self.write_i64(idx, micros_since_epoch) };
562 }
563
564 /// Writes a `TIMESTAMP_S` value at row `idx`, as seconds since the epoch.
565 ///
566 /// # Safety
567 ///
568 /// - `idx` must be within the vector's capacity.
569 /// - The vector must have `TIMESTAMP_S` type.
570 #[inline]
571 pub const unsafe fn write_timestamp_s(&mut self, idx: usize, seconds_since_epoch: i64) {
572 // SAFETY: TIMESTAMP_S is stored as i64 seconds.
573 unsafe { self.write_i64(idx, seconds_since_epoch) };
574 }
575
576 /// Writes a `TIMESTAMP_MS` value at row `idx`, as milliseconds since the
577 /// epoch.
578 ///
579 /// # Safety
580 ///
581 /// - `idx` must be within the vector's capacity.
582 /// - The vector must have `TIMESTAMP_MS` type.
583 #[inline]
584 pub const unsafe fn write_timestamp_ms(&mut self, idx: usize, millis_since_epoch: i64) {
585 // SAFETY: TIMESTAMP_MS is stored as i64 milliseconds.
586 unsafe { self.write_i64(idx, millis_since_epoch) };
587 }
588
589 /// Writes a `TIMESTAMP_NS` value at row `idx`, as nanoseconds since the
590 /// epoch.
591 ///
592 /// # Safety
593 ///
594 /// - `idx` must be within the vector's capacity.
595 /// - The vector must have `TIMESTAMP_NS` type.
596 #[inline]
597 pub const unsafe fn write_timestamp_ns(&mut self, idx: usize, nanos_since_epoch: i64) {
598 // SAFETY: TIMESTAMP_NS is stored as i64 nanoseconds.
599 unsafe { self.write_i64(idx, nanos_since_epoch) };
600 }
601
602 /// Writes a `TIMESTAMPTZ_NS` value at row `idx`, as nanoseconds since the
603 /// epoch (`DuckDB` 2.0.0+).
604 ///
605 /// # Safety
606 ///
607 /// - `idx` must be within the vector's capacity.
608 /// - The vector must have `TIMESTAMPTZ_NS` type.
609 #[inline]
610 pub const unsafe fn write_timestamp_tz_ns(&mut self, idx: usize, nanos_since_epoch: i64) {
611 // SAFETY: TIMESTAMPTZ_NS is stored as i64 nanoseconds
612 // (`timestamp_tz_ns_t` wraps a `timestamp_ns_t`).
613 unsafe { self.write_i64(idx, nanos_since_epoch) };
614 }
615
616 /// Writes a `TIME WITH TIME ZONE` value at row `idx`.
617 ///
618 /// `bits` is `DuckDB`'s packed representation; build one with
619 /// [`datetime::time_tz_bits`][crate::datetime::time_tz_bits] rather than
620 /// assembling it by hand. `DuckDB` does not check it: an encoding with a
621 /// time past `24:00:00` or an offset past `±15:59:59` renders as garbage
622 /// (`u64::MAX` as `b}:25:11.627775-4644:20:16`).
623 ///
624 /// # Safety
625 ///
626 /// - `idx` must be within the vector's capacity.
627 /// - The vector must have `TIMETZ` type.
628 #[inline]
629 pub const unsafe fn write_time_tz(&mut self, idx: usize, bits: u64) {
630 // SAFETY: TIMETZ is stored as a 64-bit packed value.
631 unsafe { self.write_u64(idx, bits) };
632 }
633
634 /// Writes a `DECIMAL` value at row `idx` from its unscaled representation.
635 ///
636 /// `DuckDB` stores a `DECIMAL` in the narrowest integer that fits its
637 /// declared width — `i16` up to 4 digits, `i32` up to 9, `i64` up to 18, and
638 /// `i128` beyond — so the width must match the column's type. Get it from
639 /// [`LogicalType::decimal_width`][crate::types::LogicalType::decimal_width].
640 ///
641 /// # Safety
642 ///
643 /// - `idx` must be within the vector's capacity.
644 /// - The vector must have `DECIMAL` type with exactly this `width`.
645 #[inline]
646 pub const unsafe fn write_decimal(&mut self, idx: usize, width: u8, unscaled: i128) {
647 // SAFETY: the caller guarantees `width` matches the column's declared
648 // width, which fixes the physical storage type.
649 unsafe {
650 #[allow(clippy::cast_possible_truncation)]
651 if width <= 4 {
652 self.write_i16(idx, unscaled as i16);
653 } else if width <= 9 {
654 self.write_i32(idx, unscaled as i32);
655 } else if width <= 18 {
656 self.write_i64(idx, unscaled as i64);
657 } else {
658 self.write_i128(idx, unscaled);
659 }
660 }
661 }
662
663 /// Marks row `idx` as NULL in the output vector.
664 ///
665 /// For a `STRUCT` vector this also marks row `idx` NULL in every field,
666 /// recursively; for an `ARRAY` vector of size `n`, child rows
667 /// `idx * n .. idx * n + n`. See the
668 /// [module docs](crate::vector::writer#nulls-in-nested-vectors).
669 /// [`set_valid`][Self::set_valid] undoes all of it.
670 ///
671 /// # Pitfall L4: `ensure_validity_writable`
672 ///
673 /// This method calls `duckdb_vector_ensure_validity_writable` before
674 /// `duckdb_vector_get_validity`, which is required before writing any NULL
675 /// flags. Without it, a vector that has no mask yet yields a NULL mask
676 /// pointer and the NULL is silently dropped.
677 ///
678 /// # Safety
679 ///
680 /// - `idx` must be within the vector's capacity.
681 pub unsafe fn set_null(&mut self, idx: usize) {
682 // SAFETY: self.vector is valid per constructor's contract.
683 let validity = unsafe { self.writable_validity() };
684 // `duckdb_vector_get_validity` has no mask to give for a vector that is
685 // not flat or constant (a sliced or dictionary vector); the C function
686 // this replaced returned early on a null mask, and so does this.
687 debug_assert!(
688 !validity.is_null(),
689 "set_null on a vector with no validity mask"
690 );
691 if validity.is_null() {
692 return;
693 }
694 // Clears bit `idx % 64` of word `idx / 64`, which is all
695 // `duckdb_validity_set_row_invalid` does, without the FFI call (see
696 // `VectorReader::is_valid`).
697 // SAFETY: validity is now initialized and idx is in bounds per caller's
698 // contract, so word `idx / 64` lies inside the mask.
699 unsafe { *validity.add(idx >> 6) &= !(1_u64 << (idx & 63)) };
700 // SAFETY: self.vector is valid; idx is in bounds per caller's contract.
701 unsafe { self.clear_nested(idx..idx + 1) };
702 }
703
704 /// Marks every row in `range` as NULL.
705 ///
706 /// Equivalent to calling [`set_null`][Self::set_null] for each index, but
707 /// resolves the validity bitmap once.
708 ///
709 /// # Safety
710 ///
711 /// Every index in `range` must be within the vector's capacity.
712 pub unsafe fn set_null_range(&mut self, range: core::ops::Range<usize>) {
713 if range.is_empty() {
714 return;
715 }
716 // SAFETY: self.vector is valid per constructor's contract.
717 let validity = unsafe { self.writable_validity() };
718 for idx in range.clone() {
719 // SAFETY: idx is in bounds per caller's contract.
720 unsafe { duckdb_validity_set_row_invalid(validity, idx as idx_t) };
721 }
722 // SAFETY: self.vector is valid; range is in bounds per caller's contract.
723 unsafe { self.clear_nested(range) };
724 }
725
726 /// Marks `rows` NULL in every STRUCT field / ARRAY element below this
727 /// vector, mirroring `DuckDB`'s `FlatVector::SetNull`.
728 ///
729 /// # Safety
730 ///
731 /// `self.vector` must still be a valid, flat, writable vector and every
732 /// index in `rows` within its capacity.
733 unsafe fn clear_nested(&mut self, rows: core::ops::Range<usize>) {
734 let vector = self.vector;
735 // Every caller resolved the validity mask first, so this is `Some`.
736 let Some(state) = self.nulls.as_deref_mut() else {
737 return;
738 };
739 let targets = state
740 .nested
741 // SAFETY: `vector` is valid, flat and writable per this function's
742 // contract.
743 .get_or_insert_with(|| unsafe { nested_null::resolve(vector) });
744 for target in targets.iter() {
745 // SAFETY: `rows` is in bounds per this function's contract.
746 unsafe { target.clear(rows.clone()) };
747 }
748 }
749
750 /// Resolves (once) and returns the writable validity bitmap pointer.
751 ///
752 /// # Pitfall L4: `ensure_validity_writable`
753 ///
754 /// For a vector with no mask yet, `duckdb_vector_get_validity` returns NULL
755 /// (writes through which are silently ignored) until
756 /// `duckdb_vector_ensure_validity_writable` has allocated the mask. This
757 /// does both, then caches the result — `EnsureWritable` is a no-op after the
758 /// first call and the pointer is stable until the vector's buffers are
759 /// reallocated (see the `validity` field of `NullState`).
760 ///
761 /// # Safety
762 ///
763 /// `self.vector` must still be a valid, flat, writable vector.
764 unsafe fn writable_validity(&mut self) -> *mut u64 {
765 let vector = self.vector;
766 self.nulls
767 .get_or_insert_with(|| {
768 // SAFETY: `vector` is valid per constructor's contract.
769 unsafe { duckdb_vector_ensure_validity_writable(vector) };
770 // SAFETY: the mask was just allocated, so the pointer is usable.
771 let validity = unsafe { duckdb_vector_get_validity(vector) };
772 Box::new(NullState {
773 validity,
774 nested: None,
775 })
776 })
777 .validity
778 }
779
780 /// Marks row `idx` as valid (non-NULL) in the output vector.
781 ///
782 /// Use this to undo a previous [`set_null`][Self::set_null] call for a row,
783 /// or to explicitly mark a row as valid after writing its value.
784 ///
785 /// If the row is NULL, this also marks valid everything
786 /// [`set_null`][Self::set_null] marked NULL below it — every field of a
787 /// `STRUCT` row and every element of an `ARRAY` row, recursively — so
788 /// that values written there afterwards are read. Write any field or
789 /// element NULLs *after* this call. If the row is already valid, nothing
790 /// below it is touched, so marking a row valid after writing its fields
791 /// keeps any field NULLs.
792 ///
793 /// Like [`set_null`][Self::set_null], this calls `ensure_validity_writable`
794 /// before modifying the validity bitmap.
795 ///
796 /// # Safety
797 ///
798 /// - `idx` must be within the vector's capacity.
799 pub unsafe fn set_valid(&mut self, idx: usize) {
800 // SAFETY: self.vector is valid per constructor's contract.
801 let validity = unsafe { self.writable_validity() };
802 // SAFETY: validity is initialized and idx is in bounds per caller's contract.
803 let was_null =
804 !unsafe { libduckdb_sys::duckdb_validity_row_is_valid(validity, idx as idx_t) };
805 // SAFETY: validity is now initialized and idx is in bounds per caller's contract.
806 unsafe {
807 duckdb_validity_set_row_valid(validity, idx as idx_t);
808 }
809 if was_null {
810 // SAFETY: self.vector is valid; idx is in bounds per caller's contract.
811 unsafe { self.restore_nested(idx..idx + 1) };
812 }
813 }
814
815 /// Marks `rows` valid in every STRUCT field / ARRAY element below this
816 /// vector: the inverse of [`clear_nested`][Self::clear_nested].
817 ///
818 /// # Safety
819 ///
820 /// As for [`clear_nested`][Self::clear_nested].
821 unsafe fn restore_nested(&mut self, rows: core::ops::Range<usize>) {
822 let vector = self.vector;
823 // Every caller resolved the validity mask first, so this is `Some`.
824 let Some(state) = self.nulls.as_deref_mut() else {
825 return;
826 };
827 let targets = state
828 .nested
829 // SAFETY: `vector` is valid, flat and writable per this function's
830 // contract.
831 .get_or_insert_with(|| unsafe { nested_null::resolve(vector) });
832 for target in targets.iter() {
833 // SAFETY: `rows` is in bounds per this function's contract.
834 unsafe { target.restore(rows.clone()) };
835 }
836 }
837
838 /// Returns the underlying raw vector handle.
839 #[must_use]
840 #[inline]
841 pub const fn as_raw(&self) -> duckdb_vector {
842 self.vector
843 }
844
845 /// A writer attached to no vector, for layout tests that never write.
846 #[cfg(test)]
847 pub(crate) const fn detached() -> Self {
848 Self {
849 vector: core::ptr::null_mut(),
850 data: core::ptr::null_mut(),
851 nulls: None,
852 }
853 }
854}
855
856#[cfg(test)]
857mod tests {
858 // Functional tests for VectorWriter require a live DuckDB instance and are
859 // located in tests/integration_test.rs. Unit tests here verify the struct
860 // layout and any pure-Rust logic.
861
862 #[test]
863 fn size_of_vector_writer() {
864 use super::VectorWriter;
865 use std::mem::size_of;
866 // vector + data + the boxed, lazily-resolved NULL state (validity
867 // pointer and nested masks).
868 assert_eq!(size_of::<VectorWriter>(), 3 * size_of::<usize>());
869 }
870}