pub struct ChunkWriter { /* private fields */ }Expand description
A row-counting writer for a DuckDB output data chunk.
Counts the rows claimed with next_row and not given
back with release_row, and calls
duckdb_data_chunk_set_size with that count on drop. Every claimed row
must be written or released: one that is neither is published with stale
contents (see the module docs).
The drop does not check that, because it cannot: the writes go through
VectorWriters, which do not report back to this writer, so nothing here
knows whether the last claimed row was written.
Implementations§
Source§impl ChunkWriter
impl ChunkWriter
Sourcepub unsafe fn new(chunk: duckdb_data_chunk) -> Self
pub unsafe fn new(chunk: duckdb_data_chunk) -> Self
Creates a new ChunkWriter for the given output data chunk.
The capacity is read from duckdb_vector_size(), so it tracks the
running engine even when DuckDB was built with a non-default
STANDARD_VECTOR_SIZE. Do not assume 2048.
§Safety
chunkmust be a valid, writableduckdb_data_chunkobtained from aDuckDBtable function scan callback.- The
DuckDBC API dispatch table must be initialised (it always is inside a callback).
Sourcepub const unsafe fn with_capacity(
chunk: duckdb_data_chunk,
capacity: usize,
) -> Self
pub const unsafe fn with_capacity( chunk: duckdb_data_chunk, capacity: usize, ) -> Self
Sourcepub const fn next_row(&mut self) -> Option<usize>
pub const fn next_row(&mut self) -> Option<usize>
Claims the next row and returns its index, or None if the chunk is
full.
The row counts towards the size the drop publishes from this call on,
whether or not it is then written. Write it, or give it back with
release_row: a claimed row that is neither is
published holding whatever the reused output vector last held (see the
module docs).
Sourcepub fn release_row(&mut self, row: usize)
pub fn release_row(&mut self, row: usize)
Gives back row, the row the last next_row claimed,
so that the drop does not publish it.
For a scan that claims a row before it knows it has data for it: the
while let Some(row) = cw.next_row() loop whose source runs out (see
the module docs). The next next_row returns the same index
again. Rows are given back one at a time, most recent first; whatever
was written to a row given back stays in the vector but is not
published.
The row is named, rather than implied, so that giving back the wrong one is caught instead of silently dropping a written row.
§Panics
If row is not the most recently claimed row still counted: below it,
the rows claimed after it would have to move down; above it, the row
was never claimed. Either is a bug in the scan. The callback macros
(table_scan_callback! and the others)
report the panic as the query’s error.
Sourcepub const fn row_count(&self) -> usize
pub const fn row_count(&self) -> usize
Returns the number of rows claimed and not given back: the size the drop publishes.
Sourcepub fn column_count(&self) -> usize
pub fn column_count(&self) -> usize
Returns the number of columns in this data chunk.
Sourcepub unsafe fn vector(&self, col_idx: usize) -> duckdb_vector
pub unsafe fn vector(&self, col_idx: usize) -> duckdb_vector
Returns the raw duckdb_vector handle for the given column index.
Use this when a column has a complex type (LIST, MAP, ARRAY) that requires
operations beyond simple scalar writes — for example, calling
ListVector::set_entry.
§Safety
col_idx must be less than the chunk’s column count.
Sourcepub unsafe fn writer(&self, col_idx: usize) -> VectorWriter
pub unsafe fn writer(&self, col_idx: usize) -> VectorWriter
Creates a VectorWriter for the given column index.
§Safety
col_idxmust be less than the chunk’s column count.- The returned writer borrows nothing and caches pointers into the chunk’s buffers: it must not be used after the scan callback returns.
Fetch each column’s writer once per callback and keep it: building one
costs several C API calls, which a per-row cw.writer(i) pays on every
row (about 5× the cost of the write itself).
Sourcepub unsafe fn struct_writer(
&self,
col_idx: usize,
field_count: usize,
) -> StructWriter
pub unsafe fn struct_writer( &self, col_idx: usize, field_count: usize, ) -> StructWriter
Creates a StructWriter for a STRUCT column at the given index.
§Safety
col_idxmust be less than the chunk’s column count.- The column at
col_idxmust have a STRUCT type withfield_countfields. - The returned writer borrows nothing and caches pointers into the chunk’s buffers: it must not be used after the scan callback returns.
Sourcepub unsafe fn finish_with_size(self, size: usize)
pub unsafe fn finish_with_size(self, size: usize)
Manually sets the chunk size and consumes the writer without auto-setting size on drop. Use this if you need to override the auto-calculated size.
§Safety
sizemust not exceed the chunk’s capacity (typically 2048).sizemust match the actual number of rows written.