Skip to main content

Appender

Struct Appender 

Source
pub struct Appender { /* private fields */ }
Expand description

RAII wrapper for a duckdb_appender.

The appender is closed and destroyed automatically on drop. To surface any error from the final flush, call close explicitly beforehand.

See the module docs for the two append styles and the buffering rules that decide when an error appears.

Implementations§

Source§

impl Appender

Source

pub fn append_chunk(&self, chunk: &DataChunk) -> Result<(), AppendError>

Appends an entire DataChunk.

The chunk’s column types must match the appender’s active columns; see column_type to discover them.

Order: DuckDB keeps row-at-a-time rows in a separate buffer until 2,048 of them accumulate, and adds a chunk to the table-bound buffer directly, so a chunk lands ahead of rows appended before it that are still buffered. flush first if insertion order matters.

§Errors

Returns an AppendError if the append fails, if the appender is closed or poisoned, or — without calling DuckDB — in the middle of a row appended by hand: when the chunk tips DuckDB’s buffer over its automatic-flush threshold, that flush fails on the open row after the chunk has been buffered, so an error would be reported for rows that were in fact kept.

Source

pub fn append_default_to_chunk( &self, chunk: &DataChunk, col: u64, row: u64, ) -> Result<(), AppendError>

Writes the table column col’s DEFAULT value into row row of chunk.

Useful when building a chunk to append: columns without an explicit value can be filled with their schema default.

§Errors

Returns an AppendError if the default cannot be written.

Source§

impl Appender

Source

pub unsafe fn new( con: duckdb_connection, schema: Option<&CStr>, table: &CStr, ) -> Result<Self, AppendError>

Creates an appender for table in the given schema (or the default schema when schema is None).

§Errors

Returns an AppendError if the appender cannot be created — most often because the table does not exist.

§Safety

con must be a valid, open duckdb_connection. It need not outlive the appender for memory safety (DuckDB’s appender holds only a weak reference to the client context and checks it before writing), but rows still buffered when it closes are lost: appends keep succeeding, and the next flush or close fails with “Attempting to flush data to a closed connection”. Close the appender first.

Source

pub unsafe fn with_catalog( con: duckdb_connection, catalog: Option<&CStr>, schema: Option<&CStr>, table: &CStr, ) -> Result<Self, AppendError>

Creates an appender for table, fully qualified by optional catalog and schema.

§Errors

Returns an AppendError if the appender cannot be created.

§Safety

con must be a valid, open duckdb_connection. It need not outlive the appender for memory safety (DuckDB’s appender holds only a weak reference to the client context and checks it before writing), but rows still buffered when it closes are lost: appends keep succeeding, and the next flush or close fails with “Attempting to flush data to a closed connection”. Close the appender first.

Source

pub unsafe fn for_query( con: duckdb_connection, sql: &str, types: &[LogicalType], table: Option<&str>, columns: Option<&[&str]>, ) -> Result<Self, AppendError>

Creates an appender whose rows feed sql instead of a table (DuckDB 1.5.0+): each flush runs sql with the buffered rows available as a table — an INSERT … SELECT, UPDATE … FROM, DELETE … USING, INSERT OR REPLACE or MERGE INTO over the batch.

types are the appended columns’ types. The rows are visible to sql as the table table (default appended_data) with the column names columns (default col1, col2, …, 1-based). Rows are appended exactly as for a table appender. DuckDB does not look at sql until a flush runs it (QueryAppender’s constructor only stores it), so a query that does not parse or bind, like a constraint it violates, fails at flush or close, and the rows buffered for it are lost as for any failed flush.

Requires duckdb-1-5: duckdb_appender_create_query sits in the unstable region of the C API struct.

§Errors

Before DuckDB is called: types is empty, columns does not have one name per type (duckdb_appender_create_query would read past the end of a short list), or sql, table or a column name contains an interior NUL byte. Otherwise DuckDB’s error, if it refuses to create the appender.

§Safety

con must be a valid, open duckdb_connection; see new for how long it must outlive the appender.

§Example
use quack_rs::appender::Appender;
use quack_rs::types::{LogicalType, TypeId};

let types = [LogicalType::new(TypeId::Integer), LogicalType::new(TypeId::Varchar)];
// SAFETY: `con` is open.
let upsert = unsafe {
    Appender::for_query(
        con,
        "INSERT OR REPLACE INTO users SELECT id, name FROM batch",
        &types,
        Some("batch"),
        Some(&["id", "name"]),
    )
}?;
upsert.row(|row| {
    row.append_i32(7)?;
    row.append_str("ada")
})?;
upsert.close()?;
Source

pub const unsafe fn from_raw(handle: duckdb_appender) -> Self

Takes ownership of a raw appender, which is then closed and destroyed (duckdb_appender_destroy) on drop: the way back into this crate’s RAII for an appender a raw call created.

§Safety

handle must come from a duckdb_appender_create* call, must not be destroyed by anyone else, and must be at a row boundary (no values appended since its last duckdb_appender_end_row): the row and poisoning checks described in the module docs start counting from here. See new for how long its connection must stay open.

Source

pub const fn into_raw(self) -> duckdb_appender

Gives up ownership and returns the raw appender without flushing or closing it. The caller must destroy it (duckdb_appender_destroy, which flushes) or hand it back to from_raw; this wrapper’s record of a half-written row or a poisoned state is lost.

Source

pub fn column_count(&self) -> u64

Number of columns the appender currently expects per row.

This is the active column list, so it reflects any add_column calls rather than always matching the table’s width.

Source

pub fn column_type(&self, index: u64) -> Option<LogicalType>

Type of active column index, or None if the index is out of range.

Source

pub fn add_column(&self, name: &CStr) -> Result<(), AppendError>

Restricts appends to a named subset of the table’s columns.

Columns left out are filled with their DEFAULT (or NULL). Calling this flushes everything appended so far.

§Errors

Returns an AppendError if the column does not exist, or if the implicit flush fails.

Source

pub fn clear_columns(&self) -> Result<(), AppendError>

Resets the active column list so every table column is expected again.

Also flushes everything appended so far.

§Errors

Returns an AppendError if the implicit flush fails.

Source§

impl Appender

Source

pub fn flush(&self) -> Result<(), AppendError>

Flushes buffered rows to the table without closing the appender.

§Errors

Returns an AppendError if the flush fails — a constraint violation, typically. On failure every buffered row is invalidated: up to DuckDB 1.5.x they stay buffered and, with duckdb-1-5, can be discarded with clear; from 2.0.0 DuckDB discards them itself. Also an error when the appender is closed or poisoned, or a row is in progress. On 2.0.0 the flush also fails, losing the buffered rows, while a streaming result is open on the appender’s connection (see the module docs).

Source

pub fn close(&self) -> Result<(), AppendError>

Flushes and closes the appender. Every later append, row, end_row, flush and append_chunk returns an error; closing again is a no-op.

§Errors

Returns an AppendError if the final flush fails (the appender then stays open; up to DuckDB 1.5.x the buffered rows can be discarded with clear under duckdb-1-5, and from 2.0.0 DuckDB has already discarded them, so closing again succeeds and writes nothing), and — instead of DuckDB’s silent success — when a row is unfinished or the appender is poisoned: DuckDB’s Close writes nothing in that state, so the error says how many buffered rows were not written. An unfinished row appended by hand can still be completed and the appender closed again.

Source

pub fn clear(&self) -> Result<(), AppendError>

Discards all buffered, unflushed rows, and any half-written row.

Useful for recovering after a flush error without re-appending the rows that were already committed, and the only way to make a poisoned appender (see the module docs) usable again. It does not reopen a closed one.

§Errors

Returns an AppendError if the appender state is invalid.

Source§

impl Appender

Source

pub fn row<F>(&self, append: F) -> Result<(), AppendError>
where F: FnOnce(&Self) -> Result<(), AppendError>,

Appends one row, calling end_row afterwards.

The closure appends one value per active column. end_row runs only if the closure succeeded.

If the closure (or end_row, for a missing column) fails after the row’s first value went in, DuckDB is left holding a half-written row it can neither finish nor drop, and every row buffered since the last flush is lost. The appender is then poisoned: see the module docs. A closure that panics after the row’s first value poisons it too. A failure of the automatic flush inside end_row does not poison it (see end_row).

§Errors

Returns whatever the closure returned, or the AppendError from end_row — most often “call to EndRow before all columns have been appended to”. Also an error, before the closure runs, when the appender is closed or poisoned, or when a row appended by hand is still open.

Source

pub fn end_row(&self) -> Result<(), AppendError>

Finishes the current row.

§Errors

Returns an AppendError if fewer values were appended than the appender has active columns (append the rest and call it again), or if the appender is closed or poisoned. Also when the automatic flush DuckDB runs every 204,800 rows fails — a constraint violation in any buffered row. The row has then ended and the appender stays usable. Up to DuckDB 1.5.x the rows that failed stay buffered: the next flush reports the same error until clear (duckdb-1-5) discards them. From 2.0.0 a failed flush discards every buffered row itself, so the next flush writes only the rows appended after it.

Source

pub fn append_null(&self) -> Result<(), AppendError>

Appends SQL NULL to the current row, whatever the column’s type.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_default(&self) -> Result<(), AppendError>

Appends the column’s DEFAULT value to the current row.

A column declared without a DEFAULT gets NULL, as it would from an INSERT that leaves it out.

§Errors

Returns an AppendError if the column’s DEFAULT is not a constant the appender can evaluate up front — nextval('seq'), random(), now(): DuckDB’s appender evaluates defaults once, when it is created, and keeps none for an expression that is not foldable (Appender::InitializeChunk, appender.cpp), so appending it fails with “AppendDefault is not supported”. Also if the append itself fails.

Source

pub fn append_str(&self, value: &str) -> Result<(), AppendError>

Appends a VARCHAR.

Uses duckdb_append_varchar_length, so interior NUL bytes are preserved — unlike the NUL-terminated duckdb_append_varchar, which would stop at the first one.

§Errors

Returns an AppendError if the append fails, or if value is longer than u32::MAX bytes — a length DuckDB narrows to 32 bits without checking in its release builds.

Source

pub fn append_bytes(&self, value: &[u8]) -> Result<(), AppendError>

Appends a BLOB.

§Errors

Returns an AppendError if the append fails, or if value is longer than u32::MAX bytes. duckdb_append_blob stores the length through a 32-bit narrowing with no check in release builds: a 4 GiB + 3 byte blob was stored as 3 bytes, with no error.

Source

pub fn append_date(&self, days: i32) -> Result<(), AppendError>

Appends a DATE as days since 1970-01-01.

Every i32 is accepted, as by Value::date; days outside the range DuckDB’s SQL produces render as text it cannot parse again.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_time(&self, micros: i64) -> Result<(), AppendError>

Appends a TIME as microseconds since midnight.

§Errors

Returns an AppendError if the append fails, or — before DuckDB is called — if micros is outside 0..=86_400_000_000 (00:00:00 to 24:00:00). duckdb_append_time checks nothing; appending i64::MIN crashed the process when the row was read, and i64::MAX invalidated the database.

Source

pub fn append_timestamp(&self, micros: i64) -> Result<(), AppendError>

Appends a TIMESTAMP as microseconds since the epoch.

§Errors

Returns an AppendError if the append fails, or — before DuckDB is called — if micros is below 290309-12-22 (BC) and not -infinity, the range of Value::timestamp. DuckDB stores such a value unchecked, and every later read of the row fails with “Date out of range”.

Source

pub fn append_interval(&self, value: DuckInterval) -> Result<(), AppendError>

Appends an INTERVAL.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_value(&self, value: &Value) -> Result<(), AppendError>

Appends an arbitrary Value, letting DuckDB cast it to the column’s type.

This is the escape hatch for types with no dedicated append_*: LIST, STRUCT, MAP, UUID, DECIMAL, ENUM.

§Errors

Returns an AppendError if value holds a null handle — which duckdb_append_value would dereference — or if the append fails.

Source§

impl Appender

Source

pub fn append_bool(&self, value: bool) -> Result<(), AppendError>

Appends a BOOLEAN.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_i8(&self, value: i8) -> Result<(), AppendError>

Appends a TINYINT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_i16(&self, value: i16) -> Result<(), AppendError>

Appends a SMALLINT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_i32(&self, value: i32) -> Result<(), AppendError>

Appends an INTEGER.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_i64(&self, value: i64) -> Result<(), AppendError>

Appends a BIGINT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_u8(&self, value: u8) -> Result<(), AppendError>

Appends a UTINYINT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_u16(&self, value: u16) -> Result<(), AppendError>

Appends a USMALLINT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_u32(&self, value: u32) -> Result<(), AppendError>

Appends a UINTEGER.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_u64(&self, value: u64) -> Result<(), AppendError>

Appends a UBIGINT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_f32(&self, value: f32) -> Result<(), AppendError>

Appends a FLOAT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_f64(&self, value: f64) -> Result<(), AppendError>

Appends a DOUBLE.

§Errors

Returns an AppendError if the append fails.

Source§

impl Appender

Source

pub fn append_i128(&self, value: i128) -> Result<(), AppendError>

Appends a HUGEINT.

§Errors

Returns an AppendError if the append fails.

Source

pub fn append_u128(&self, value: u128) -> Result<(), AppendError>

Appends a UHUGEINT.

§Errors

Returns an AppendError if the append fails.

Source§

impl Appender

Source

pub fn error_data(&self) -> ErrorData

Returns the structured error from the most recent failed operation.

Source

pub fn error_message(&self) -> Option<String>

Returns the message from the most recent failed operation, if any.

Always available; with duckdb-1-5 prefer error_data (duckdb-1-5), which also carries the error category.

Source

pub const fn as_raw(&self) -> duckdb_appender

Returns the raw handle.

Trait Implementations§

Source§

impl Debug for Appender

Source§

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

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

impl Drop for Appender

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.