Skip to main content

ChunkWriter

Struct ChunkWriter 

Source
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

Source

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
  • chunk must be a valid, writable duckdb_data_chunk obtained from a DuckDB table function scan callback.
  • The DuckDB C API dispatch table must be initialised (it always is inside a callback).
Source

pub const unsafe fn with_capacity( chunk: duckdb_data_chunk, capacity: usize, ) -> Self

Creates a new ChunkWriter with a custom capacity.

§Safety

Same as new. capacity must not exceed the chunk’s actual capacity.

Source

pub const fn is_full(&self) -> bool

Returns true if the chunk has reached its capacity.

Source

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

Source

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.

Source

pub const fn row_count(&self) -> usize

Returns the number of rows claimed and not given back: the size the drop publishes.

Source

pub const fn capacity(&self) -> usize

Returns the chunk’s capacity (maximum rows).

Source

pub fn column_count(&self) -> usize

Returns the number of columns in this data chunk.

Source

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.

Source

pub unsafe fn writer(&self, col_idx: usize) -> VectorWriter

Creates a VectorWriter for the given column index.

§Safety
  • col_idx must 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).

Source

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_idx must be less than the chunk’s column count.
  • The column at col_idx must have a STRUCT type with field_count fields.
  • The returned writer borrows nothing and caches pointers into the chunk’s buffers: it must not be used after the scan callback returns.
Source

pub const fn as_raw(&self) -> duckdb_data_chunk

Returns the raw duckdb_data_chunk handle.

Source

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
  • size must not exceed the chunk’s capacity (typically 2048).
  • size must match the actual number of rows written.

Trait Implementations§

Source§

impl Debug for ChunkWriter

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Drop for ChunkWriter

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.