pub struct ListVector;Expand description
Operations on LIST vectors.
A LIST vector stores a duckdb_list_entry { offset: u64, length: u64 } per row
in the parent vector, and all element values in a flat child vector.
§Write workflow
reserve— ensure child vector has capacity.- Write element values into the child via
get_child+VectorWriter. set_size— tellDuckDBhow many elements were written.set_entry— write the offset/length for each parent row.
Implementations§
Source§impl ListVector
impl ListVector
Sourcepub unsafe fn get_child(vector: duckdb_vector) -> duckdb_vector
pub unsafe fn get_child(vector: duckdb_vector) -> duckdb_vector
Returns the child vector containing all list elements (flat, across all rows).
§Safety
vectormust be a validDuckDBLIST vector.- The returned handle is borrowed from
vector.
Sourcepub unsafe fn get_size(vector: duckdb_vector) -> usize
pub unsafe fn get_size(vector: duckdb_vector) -> usize
Returns the total number of elements currently in the child vector.
§Safety
vector must be a valid DuckDB LIST vector.
Sourcepub unsafe fn set_size(vector: duckdb_vector, size: usize)
pub unsafe fn set_size(vector: duckdb_vector, size: usize)
Sets the number of elements in the child vector.
Call after writing all element values. DuckDB uses this to know how many
child elements are valid.
§Safety
vectormust be a validDuckDBLIST vector.sizemust equal the number of elements written into the child vector.
Sourcepub unsafe fn reserve(vector: duckdb_vector, capacity: usize)
pub unsafe fn reserve(vector: duckdb_vector, capacity: usize)
Reserves capacity in the child vector for at least capacity elements.
Call before writing elements to ensure the child vector has enough space.
ListBuilder checks the capacity limit
for you; prefer it when element counts come from input data.
§Safety
vectormust be a validDuckDBLIST vector.capacitymust not exceedmax_child_capacity(vector): 2^37 bytes in the widest buffer the child’s type grows, as a power-of-two element count. Above itDuckDBthrows anOutOfRangeException(VectorListBuffer::Reserve,Vector::Resize), which the C API does not catch, so the process aborts. Below it, a reservation the allocator cannot satisfy aborts the same way, so a capacity derived from input data should be bounded to what fits in memory.
Sourcepub unsafe fn set_entry(
vector: duckdb_vector,
row_idx: usize,
offset: u64,
length: u64,
)
pub unsafe fn set_entry( vector: duckdb_vector, row_idx: usize, offset: u64, length: u64, )
Writes the offset/length metadata entry for a parent row.
This tells DuckDB where in the flat child vector this row’s elements start
and how many elements it has.
§Safety
vectormust be a validDuckDBLIST vector.row_idxmust be a valid row index in the parent vector.offset + lengthmust not exceed the size of the child vector.
Sourcepub unsafe fn get_entry(
vector: duckdb_vector,
row_idx: usize,
) -> duckdb_list_entry
pub unsafe fn get_entry( vector: duckdb_vector, row_idx: usize, ) -> duckdb_list_entry
Returns the duckdb_list_entry for a given row (for reading).
§NULL rows
DuckDB writes no entry for a NULL row. The slot holds stale or
never-written bytes, so for a NULL row offset and length are
arbitrary: on DuckDB 2.0.0 a nullif(l, []) column gave NULL rows with
lengths around 7·10¹³, and a loop over such an entry reads far outside
the child vector (a segmentation fault in a minority of runs). Check
the row’s validity before using the entry, or call
get_entry_checked, which does that and also
refuses an entry that does not lie inside the child.
§Safety
vectormust be a validDuckDBLIST vector.row_idxmust be a valid row index.- For a NULL row the returned entry is meaningless and must not be used to index the child.
Sourcepub unsafe fn get_entry_checked(
vector: duckdb_vector,
row_idx: usize,
) -> Option<duckdb_list_entry>
pub unsafe fn get_entry_checked( vector: duckdb_vector, row_idx: usize, ) -> Option<duckdb_list_entry>
Returns the entry for a row that is not NULL, or None for a NULL row
or an entry that does not lie inside the child vector.
This is the read-side companion of get_entry: it
checks the row’s validity first (a vector with no validity mask has no
NULL rows), then that offset + length does not exceed
get_size. The elements of a returned entry can be
indexed in a child reader created with get_size elements.
§Safety
vectormust be a validDuckDBLIST vector.row_idxmust be a valid row index.
Sourcepub unsafe fn child_writer(vector: duckdb_vector) -> VectorWriter
pub unsafe fn child_writer(vector: duckdb_vector) -> VectorWriter
Creates a VectorWriter for the child vector (elements).
§Safety
vectormust be a validDuckDBLIST vector.- Every index written must be below the capacity most recently reserved
with
ListVector::reserve. - The writer must not be used after the child is grown again
(
ListVector::reservewith a larger capacity, or aListBuilderrow that grows it): growing reallocates the child’s data and validity buffers, and the writer caches pointers to both. Fetch a new writer after every reserve.
Sourcepub unsafe fn child_reader(
vector: duckdb_vector,
element_count: usize,
) -> VectorReader
pub unsafe fn child_reader( vector: duckdb_vector, element_count: usize, ) -> VectorReader
Creates a VectorReader for the child vector (reading list elements).
§Safety
vectormust be a validDuckDBLIST vector.element_countmust equal the total number of elements in the child.