Data Chunks

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

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

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

An exclusive, writable view of column idx.

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

Current valid row count.

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

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

Column count.

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

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.

Connecting

Querying

Values & Types

Parameters & Statements

Writing Data

Columnar

Concurrency

Interop

Errors & Extensions

User-Defined Functions

Derives & Helpers

Allocating and building

API

Capacity, not a constant

See also

​Allocating and building

​API

​Capacity, not a constant

​See also

Allocating and building

API

Capacity, not a constant

See also