Data Chunks

DataChunkHandle: allocate a columnar batch, read and write its column vectors, set and reset the row count, and respect DuckDB’s build-time vector capacity.

Requires feature = "columnar" (or udf). better_duck_core::DataChunkHandle.

A DataChunkHandle is a batch of rows laid out column-wise — one vector per column. You get one from DuckResult::fetch_chunk (DuckDB-owned, read-only in practice) or allocate one with new to build and append.

Allocating and building

use better_duck_core::{types::LogicalType, DataChunkHandle};

conn.execute_batch("CREATE TABLE dst (a INTEGER, b DOUBLE)")?;
let types = [LogicalType::of::<i32>()?, LogicalType::of::<f64>()?];
let mut chunk = DataChunkHandle::new(&types)?;       // owned; destroyed on drop

for row in 0..3usize {
    chunk.vector_mut(0)?.set(row, row as i32)?;
    chunk.vector_mut(1)?.set(row, row as f64 * 1.5)?;
}
chunk.set_len(3)?;                                   // mark 3 valid rows (<= capacity())

let mut app = conn.appender("dst", "main")?;
app.append_chunk_handle(&chunk)?;                    // strict shape check vs the table
app.save()?;

chunk.reset();                                       // zero rows, reuse the allocation

API

new(types: &[LogicalType]) -> Result<Self>

Allocate a chunk with one LogicalType per column. Owned — destroyed on drop.

vector(idx) -> Result<VectorRef>

A read-only view of column idx. Many VectorRefs may coexist. InvalidColumnIndex out of range.

vector_mut(idx) -> Result<VectorMut>

An exclusive, writable view of column idx.

vectors_mut() -> Result<Vec<VectorMut>>

A writable view of every column at once — disjoint by construction, so they may be held together.

len() -> usize / is_empty() -> bool

Current valid row count.

set_len(n) -> Result<()>

Mark n valid rows. Errors if n > capacity().

capacity() -> usize

DuckDB’s build-time vector size — the max rows per chunk. Read it, never hardcode a limit.

num_columns() -> usize

Column count.

column_type_id(idx) -> Result<DUCKDB_TYPE>

The DuckDB type id of column idx. InvalidColumnIndex out of range.

reset()

Clear to zero rows, keeping the allocation to refill and append again.

reset() panics on a borrowed chunk — one obtained from a DuckDB callback frame rather than allocated with new. Only reset chunks you own. (A chunk from fetch_chunk is owned and may be reset.)

Capacity, not a constant

let chunk = DataChunkHandle::new(&[LogicalType::of::<i32>()?])?;
let cap = chunk.capacity();              // e.g. 2048 — the vector size this DuckDB build was compiled with

The vector size is a DuckDB build-time constant that can differ across builds. Loop until cap rather than assuming any particular value, and split large writes into multiple chunks of at most cap rows each.

See also

• Vectors — reading and writing individual columns.
• Columnar overview — fetch_chunk and the row-vs-chunk rule.
• Appender advanced — append_chunk_handle.