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
impl Appender
Sourcepub fn append_chunk(&self, chunk: &DataChunk) -> Result<(), AppendError>
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.
Sourcepub fn append_default_to_chunk(
&self,
chunk: &DataChunk,
col: u64,
row: u64,
) -> Result<(), AppendError>
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
impl Appender
Sourcepub unsafe fn new(
con: duckdb_connection,
schema: Option<&CStr>,
table: &CStr,
) -> Result<Self, AppendError>
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.
Sourcepub unsafe fn with_catalog(
con: duckdb_connection,
catalog: Option<&CStr>,
schema: Option<&CStr>,
table: &CStr,
) -> Result<Self, AppendError>
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.
Sourcepub unsafe fn for_query(
con: duckdb_connection,
sql: &str,
types: &[LogicalType],
table: Option<&str>,
columns: Option<&[&str]>,
) -> Result<Self, AppendError>
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()?;Sourcepub const unsafe fn from_raw(handle: duckdb_appender) -> Self
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.
Sourcepub const fn into_raw(self) -> duckdb_appender
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.
Sourcepub fn column_count(&self) -> u64
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.
Sourcepub fn column_type(&self, index: u64) -> Option<LogicalType>
pub fn column_type(&self, index: u64) -> Option<LogicalType>
Type of active column index, or None if the index is out of range.
Sourcepub fn add_column(&self, name: &CStr) -> Result<(), AppendError>
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.
Sourcepub fn clear_columns(&self) -> Result<(), AppendError>
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
impl Appender
Sourcepub fn flush(&self) -> Result<(), AppendError>
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).
Sourcepub fn close(&self) -> Result<(), AppendError>
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.
Sourcepub fn clear(&self) -> Result<(), AppendError>
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
impl Appender
Sourcepub fn row<F>(&self, append: F) -> Result<(), AppendError>
pub fn row<F>(&self, append: F) -> 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.
Sourcepub fn end_row(&self) -> Result<(), AppendError>
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.
Sourcepub fn append_null(&self) -> Result<(), AppendError>
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.
Sourcepub fn append_default(&self) -> Result<(), AppendError>
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.
Sourcepub fn append_str(&self, value: &str) -> Result<(), AppendError>
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.
Sourcepub fn append_bytes(&self, value: &[u8]) -> Result<(), AppendError>
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.
Sourcepub fn append_date(&self, days: i32) -> Result<(), AppendError>
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.
Sourcepub fn append_time(&self, micros: i64) -> Result<(), AppendError>
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.
Sourcepub fn append_timestamp(&self, micros: i64) -> Result<(), AppendError>
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”.
Sourcepub fn append_interval(&self, value: DuckInterval) -> Result<(), AppendError>
pub fn append_interval(&self, value: DuckInterval) -> Result<(), AppendError>
Sourcepub fn append_value(&self, value: &Value) -> Result<(), AppendError>
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
impl Appender
Sourcepub fn append_bool(&self, value: bool) -> Result<(), AppendError>
pub fn append_bool(&self, value: bool) -> Result<(), AppendError>
Sourcepub fn append_i16(&self, value: i16) -> Result<(), AppendError>
pub fn append_i16(&self, value: i16) -> Result<(), AppendError>
Sourcepub fn append_i32(&self, value: i32) -> Result<(), AppendError>
pub fn append_i32(&self, value: i32) -> Result<(), AppendError>
Sourcepub fn append_i64(&self, value: i64) -> Result<(), AppendError>
pub fn append_i64(&self, value: i64) -> Result<(), AppendError>
Sourcepub fn append_u16(&self, value: u16) -> Result<(), AppendError>
pub fn append_u16(&self, value: u16) -> Result<(), AppendError>
Sourcepub fn append_u32(&self, value: u32) -> Result<(), AppendError>
pub fn append_u32(&self, value: u32) -> Result<(), AppendError>
Sourcepub fn append_u64(&self, value: u64) -> Result<(), AppendError>
pub fn append_u64(&self, value: u64) -> Result<(), AppendError>
Sourcepub fn append_f32(&self, value: f32) -> Result<(), AppendError>
pub fn append_f32(&self, value: f32) -> Result<(), AppendError>
Sourcepub fn append_f64(&self, value: f64) -> Result<(), AppendError>
pub fn append_f64(&self, value: f64) -> Result<(), AppendError>
Source§impl Appender
impl Appender
Sourcepub fn append_i128(&self, value: i128) -> Result<(), AppendError>
pub fn append_i128(&self, value: i128) -> Result<(), AppendError>
Sourcepub fn append_u128(&self, value: u128) -> Result<(), AppendError>
pub fn append_u128(&self, value: u128) -> Result<(), AppendError>
Source§impl Appender
impl Appender
Sourcepub fn error_data(&self) -> ErrorData
pub fn error_data(&self) -> ErrorData
Returns the structured error from the most recent failed operation.
Sourcepub fn error_message(&self) -> Option<String>
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.