Appenders are the most efficient way of loading data into DuckDB from within the C interface, and are recommended for
fast data loading. The appender is much faster than using prepared statements or individual INSERT INTO statements.
Appends are made in row-wise format. For every column, a duckdb_append_[type] call should be made, after which
the row should be finished by calling duckdb_appender_end_row. After all rows have been appended,
duckdb_appender_destroy should be used to finalize the appender and clean up the resulting memory.
Note that duckdb_appender_destroy should always be called on the resulting appender, even if the function returns
DuckDBError.
Example
duckdb_query(con, "CREATE TABLE people (id INTEGER, name VARCHAR)", NULL);
duckdb_appender appender;
if (duckdb_appender_create(con, NULL, "people", &appender) == DuckDBError) {
// handle error
}
// append the first row (1, Mark)
duckdb_append_int32(appender, 1);
duckdb_append_varchar(appender, "Mark");
duckdb_appender_end_row(appender);
// append the second row (2, Hannes)
duckdb_append_int32(appender, 2);
duckdb_append_varchar(appender, "Hannes");
duckdb_appender_end_row(appender);
// finish appending and flush all the rows to the table
duckdb_appender_destroy(&appender);
API Reference Overview
duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table, duckdb_appender *out_appender);
duckdb_state duckdb_appender_create_ext(duckdb_connection connection, const char *catalog, const char *schema, const char *table, duckdb_appender *out_appender);
duckdb_state duckdb_appender_create_query(duckdb_connection connection, const char *query, idx_t column_count, duckdb_logical_type *types, const char *table_name, const char **column_names, duckdb_appender *out_appender);
idx_t duckdb_appender_column_count(duckdb_appender appender);
duckdb_logical_type duckdb_appender_column_type(duckdb_appender appender, idx_t col_idx);
duckdb_error_data duckdb_appender_error_data(duckdb_appender appender);
duckdb_state duckdb_appender_flush(duckdb_appender appender);
duckdb_state duckdb_appender_clear(duckdb_appender appender);
duckdb_state duckdb_appender_close(duckdb_appender appender);
duckdb_state duckdb_appender_destroy(duckdb_appender *appender);
duckdb_state duckdb_appender_add_column(duckdb_appender appender, const char *name);
duckdb_state duckdb_appender_clear_columns(duckdb_appender appender);
duckdb_state duckdb_appender_begin_row(duckdb_appender appender);
duckdb_state duckdb_appender_end_row(duckdb_appender appender);
duckdb_state duckdb_append_default(duckdb_appender appender);
duckdb_state duckdb_append_default_to_chunk(duckdb_appender appender, duckdb_data_chunk chunk, idx_t col, idx_t row);
duckdb_state duckdb_append_bool(duckdb_appender appender, bool value);
duckdb_state duckdb_append_int8(duckdb_appender appender, int8_t value);
duckdb_state duckdb_append_int16(duckdb_appender appender, int16_t value);
duckdb_state duckdb_append_int32(duckdb_appender appender, int32_t value);
duckdb_state duckdb_append_int64(duckdb_appender appender, int64_t value);
duckdb_state duckdb_append_hugeint(duckdb_appender appender, duckdb_hugeint value);
duckdb_state duckdb_append_uint8(duckdb_appender appender, uint8_t value);
duckdb_state duckdb_append_uint16(duckdb_appender appender, uint16_t value);
duckdb_state duckdb_append_uint32(duckdb_appender appender, uint32_t value);
duckdb_state duckdb_append_uint64(duckdb_appender appender, uint64_t value);
duckdb_state duckdb_append_uhugeint(duckdb_appender appender, duckdb_uhugeint value);
duckdb_state duckdb_append_float(duckdb_appender appender, float value);
duckdb_state duckdb_append_double(duckdb_appender appender, double value);
duckdb_state duckdb_append_date(duckdb_appender appender, duckdb_date value);
duckdb_state duckdb_append_time(duckdb_appender appender, duckdb_time value);
duckdb_state duckdb_append_timestamp(duckdb_appender appender, duckdb_timestamp value);
duckdb_state duckdb_append_interval(duckdb_appender appender, duckdb_interval value);
duckdb_state duckdb_append_varchar(duckdb_appender appender, const char *val);
duckdb_state duckdb_append_varchar_length(duckdb_appender appender, const char *val, idx_t length);
duckdb_state duckdb_append_blob(duckdb_appender appender, const void *data, idx_t length);
duckdb_state duckdb_append_null(duckdb_appender appender);
duckdb_state duckdb_append_value(duckdb_appender appender, duckdb_value value);
duckdb_state duckdb_append_data_chunk(duckdb_appender appender, duckdb_data_chunk chunk);
const char *duckdb_appender_error(duckdb_appender appender);
duckdb_appender_create
Stable since 0.2.5.
Creates an appender object.
Note that the object must be destroyed with duckdb_appender_destroy.
Syntax
duckdb_state duckdb_appender_create(
duckdb_connection connection,
const char *schema,
const char *table,
duckdb_appender *out_appender
);
Parameters
connection: The connection context to create the appender in.schema: The schema of the table to append to, ornullptrfor the default schema.table: The table name to append to.out_appender: The resulting appender object. (out)
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_create_ext
Stable since 1.2.0.
Creates an appender object.
Note that the object must be destroyed with duckdb_appender_destroy.
Syntax
duckdb_state duckdb_appender_create_ext(
duckdb_connection connection,
const char *catalog,
const char *schema,
const char *table,
duckdb_appender *out_appender
);
Parameters
connection: The connection context to create the appender in.catalog: The catalog of the table to append to, ornullptrfor the default catalog.schema: The schema of the table to append to, ornullptrfor the default schema.table: The table name to append to.out_appender: The resulting appender object. (out)
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_create_query
Stable since 1.5.6.
Creates an appender object that executes the given query with any data appended to it.
Note that the object must be destroyed with duckdb_appender_destroy.
Syntax
duckdb_state duckdb_appender_create_query(
duckdb_connection connection,
const char *query,
idx_t column_count,
duckdb_logical_type *types,
const char *table_name,
const char **column_names,
duckdb_appender *out_appender
);
Parameters
connection: The connection context to create the appender in.query: The query to execute, can be an INSERT, DELETE, UPDATE or MERGE INTO statement.column_count: The number of columns to append.types: The types of the columns to append.table_name: (optionally) the table name used to refer to the appended data, defaults toappended_data.column_names: (optionally) the list of column names, defaults tocol1,col2, …out_appender: The resulting appender object. (out)
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_column_count
Stable since 0.10.0.
Returns the number of columns that belong to the appender. If there is no active column list, then this equals the table's physical columns.
Syntax
idx_t duckdb_appender_column_count(
duckdb_appender appender
);
Parameters
appender: The appender to get the column count from.
Return Value
The number of columns in the data chunks.
duckdb_appender_column_type
Stable since 0.10.0.
Returns the type of the column at the specified index. This is either a type in the active column list, or the same type as a column in the receiving table.
Note: The resulting type must be destroyed with duckdb_destroy_logical_type.
Syntax
duckdb_logical_type duckdb_appender_column_type(
duckdb_appender appender,
idx_t col_idx
);
Parameters
appender: The appender to get the column type from.col_idx: The index of the column to get the type of.
Return Value
The duckdb_logical_type of the column.
duckdb_appender_error_data
Stable since 1.5.6.
Returns the error data associated with the appender. Must be destroyed with duckdb_destroy_error_data.
Syntax
duckdb_error_data duckdb_appender_error_data(
duckdb_appender appender
);
Parameters
appender: The appender to get the error data from.
Return Value
The error data.
duckdb_appender_flush
Stable since 0.2.5.
Flush the appender to the table, forcing the cache of the appender to be cleared. Requires a connection with no open result. If flushing the data triggers a constraint violation or any other error, then all data is invalidated, and this function returns DuckDBError. It is not possible to append more values. Call duckdb_appender_error_data to obtain the error data followed by duckdb_appender_destroy to destroy the invalidated appender.
Syntax
duckdb_state duckdb_appender_flush(
duckdb_appender appender
);
Parameters
appender: The appender to flush.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_clear
Stable since 1.5.6.
Clears all buffered data from the appender without flushing it to the table. This discards any data that has been appended but not yet written. The appender can continue to be used after clearing.
Syntax
duckdb_state duckdb_appender_clear(
duckdb_appender appender
);
Parameters
appender: The appender to clear.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_close
Stable since 0.2.5.
Closes the appender by flushing all intermediate states and closing it for further appends. If flushing the data triggers a constraint violation or any other error, then all data is invalidated, and this function returns DuckDBError. Call duckdb_appender_error_data to obtain the error data followed by duckdb_appender_destroy to destroy the invalidated appender.
Syntax
duckdb_state duckdb_appender_close(
duckdb_appender appender
);
Parameters
appender: The appender to flush and close.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_destroy
Stable since 0.2.5.
Closes the appender by flushing all intermediate states to the table and destroying it. By destroying it, this function de-allocates all memory associated with the appender. If flushing the data triggers a constraint violation, then all data is invalidated, and this function returns DuckDBError. Due to the destruction of the appender, it is no longer possible to obtain the specific error message with duckdb_appender_error. Therefore, call duckdb_appender_close before destroying the appender, if you need insights into the specific error.
Syntax
duckdb_state duckdb_appender_destroy(
duckdb_appender *appender
);
Parameters
appender: The appender to flush, close and destroy.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_add_column
Stable since 1.2.0.
Appends a column to the active column list of the appender. Immediately flushes all previous data.
The active column list specifies all columns that are expected when flushing the data. Any non-active columns are filled with their default values, or NULL.
Syntax
duckdb_state duckdb_appender_add_column(
duckdb_appender appender,
const char *name
);
Parameters
appender: The appender to add the column to.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_clear_columns
Stable since 1.2.0.
Removes all columns from the active column list of the appender, resetting the appender to treat all columns as active. Immediately flushes all previous data.
Syntax
duckdb_state duckdb_appender_clear_columns(
duckdb_appender appender
);
Parameters
appender: The appender to clear the columns from.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_begin_row
Stable since 0.2.5.
A nop function, provided for backwards compatibility reasons. Does nothing. Only duckdb_appender_end_row is required.
Syntax
duckdb_state duckdb_appender_begin_row(
duckdb_appender appender
);
Return Value
duckdb_state
duckdb_appender_end_row
Stable since 0.2.5.
Finish the current row of appends. After end_row is called, the next row can be appended.
Syntax
duckdb_state duckdb_appender_end_row(
duckdb_appender appender
);
Parameters
appender: The appender.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_append_default
Stable since 1.1.0.
Append a DEFAULT value (NULL if DEFAULT not available for column) to the appender.
Syntax
duckdb_state duckdb_append_default(
duckdb_appender appender
);
Return Value
duckdb_state
duckdb_append_default_to_chunk
Stable since 1.5.6.
Append a DEFAULT value, at the specified row and column, (NULL if DEFAULT not available for column) to the chunk created from the specified appender. The default value of the column must be a constant value. Non-deterministic expressions like nextval('seq') or random() are not supported.
Syntax
duckdb_state duckdb_append_default_to_chunk(
duckdb_appender appender,
duckdb_data_chunk chunk,
idx_t col,
idx_t row
);
Parameters
appender: The appender to get the default value from.chunk: The data chunk to append the default value to.col: The chunk column index to append the default value to.row: The chunk row index to append the default value to.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_append_bool
Stable since 0.2.5.
Append a bool value to the appender.
Syntax
duckdb_state duckdb_append_bool(
duckdb_appender appender,
bool value
);
Return Value
duckdb_state
duckdb_append_int8
Stable since 0.2.5.
Append an int8_t value to the appender.
Syntax
duckdb_state duckdb_append_int8(
duckdb_appender appender,
int8_t value
);
Return Value
duckdb_state
duckdb_append_int16
Stable since 0.2.5.
Append an int16_t value to the appender.
Syntax
duckdb_state duckdb_append_int16(
duckdb_appender appender,
int16_t value
);
Return Value
duckdb_state
duckdb_append_int32
Stable since 0.2.5.
Append an int32_t value to the appender.
Syntax
duckdb_state duckdb_append_int32(
duckdb_appender appender,
int32_t value
);
Return Value
duckdb_state
duckdb_append_int64
Stable since 0.2.5.
Append an int64_t value to the appender.
Syntax
duckdb_state duckdb_append_int64(
duckdb_appender appender,
int64_t value
);
Return Value
duckdb_state
duckdb_append_hugeint
Stable since 0.2.9.
Append a duckdb_hugeint value to the appender.
Syntax
duckdb_state duckdb_append_hugeint(
duckdb_appender appender,
duckdb_hugeint value
);
Return Value
duckdb_state
duckdb_append_uint8
Stable since 0.2.5.
Append a uint8_t value to the appender.
Syntax
duckdb_state duckdb_append_uint8(
duckdb_appender appender,
uint8_t value
);
Return Value
duckdb_state
duckdb_append_uint16
Stable since 0.2.5.
Append a uint16_t value to the appender.
Syntax
duckdb_state duckdb_append_uint16(
duckdb_appender appender,
uint16_t value
);
Return Value
duckdb_state
duckdb_append_uint32
Stable since 0.2.5.
Append a uint32_t value to the appender.
Syntax
duckdb_state duckdb_append_uint32(
duckdb_appender appender,
uint32_t value
);
Return Value
duckdb_state
duckdb_append_uint64
Stable since 0.2.5.
Append a uint64_t value to the appender.
Syntax
duckdb_state duckdb_append_uint64(
duckdb_appender appender,
uint64_t value
);
Return Value
duckdb_state
duckdb_append_uhugeint
Stable since 0.10.0.
Append a duckdb_uhugeint value to the appender.
Syntax
duckdb_state duckdb_append_uhugeint(
duckdb_appender appender,
duckdb_uhugeint value
);
Return Value
duckdb_state
duckdb_append_float
Stable since 0.2.5.
Append a float value to the appender.
Syntax
duckdb_state duckdb_append_float(
duckdb_appender appender,
float value
);
Return Value
duckdb_state
duckdb_append_double
Stable since 0.2.5.
Append a double value to the appender.
Syntax
duckdb_state duckdb_append_double(
duckdb_appender appender,
double value
);
Return Value
duckdb_state
duckdb_append_date
Stable since 0.2.9.
Append a duckdb_date value to the appender.
Syntax
duckdb_state duckdb_append_date(
duckdb_appender appender,
duckdb_date value
);
Return Value
duckdb_state
duckdb_append_time
Stable since 0.2.9.
Append a duckdb_time value to the appender.
Syntax
duckdb_state duckdb_append_time(
duckdb_appender appender,
duckdb_time value
);
Return Value
duckdb_state
duckdb_append_timestamp
Stable since 0.2.9.
Append a duckdb_timestamp value to the appender.
Syntax
duckdb_state duckdb_append_timestamp(
duckdb_appender appender,
duckdb_timestamp value
);
Return Value
duckdb_state
duckdb_append_interval
Stable since 0.2.9.
Append a duckdb_interval value to the appender.
Syntax
duckdb_state duckdb_append_interval(
duckdb_appender appender,
duckdb_interval value
);
Return Value
duckdb_state
duckdb_append_varchar
Stable since 0.2.5.
Append a varchar value to the appender.
Syntax
duckdb_state duckdb_append_varchar(
duckdb_appender appender,
const char *val
);
Return Value
duckdb_state
duckdb_append_varchar_length
Stable since 0.2.5.
Append a varchar value to the appender.
Syntax
duckdb_state duckdb_append_varchar_length(
duckdb_appender appender,
const char *val,
idx_t length
);
Return Value
duckdb_state
duckdb_append_blob
Stable since 0.2.5.
Append a blob value to the appender.
Syntax
duckdb_state duckdb_append_blob(
duckdb_appender appender,
const void *data,
idx_t length
);
Return Value
duckdb_state
duckdb_append_null
Stable since 0.2.5.
Append a NULL value to the appender (of any type).
Syntax
duckdb_state duckdb_append_null(
duckdb_appender appender
);
Return Value
duckdb_state
duckdb_append_value
Stable since 1.2.0.
Append a duckdb_value to the appender.
Syntax
duckdb_state duckdb_append_value(
duckdb_appender appender,
duckdb_value value
);
Return Value
duckdb_state
duckdb_append_data_chunk
Stable since 0.3.3.
Appends a pre-filled data chunk to the specified appender. Attempts casting, if the data chunk types do not match the active appender types.
Syntax
duckdb_state duckdb_append_data_chunk(
duckdb_appender appender,
duckdb_data_chunk chunk
);
Parameters
appender: The appender to append to.chunk: The data chunk to append.
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_error
Deprecated Deprecated since 1.4.0, stable since 0.2.9.
This method is scheduled for removal in a future release. Use duckdb_appender_error_data instead.
Returns the error message associated with the appender.
If the appender has no error message, this returns nullptr instead.
The error message should not be freed. It will be de-allocated when duckdb_appender_destroy is called.
Syntax
const char *duckdb_appender_error(
duckdb_appender appender
);
Parameters
appender: The appender to get the error from.
Return Value
The error message, or nullptr if there is none.
Table Description
duckdb_state duckdb_table_description_create(duckdb_connection connection, const char *schema, const char *table, duckdb_table_description *out);
duckdb_state duckdb_table_description_create_ext(duckdb_connection connection, const char *catalog, const char *schema, const char *table, duckdb_table_description *out);
void duckdb_table_description_destroy(duckdb_table_description *table_description);
const char *duckdb_table_description_error(duckdb_table_description table_description);
duckdb_state duckdb_column_has_default(duckdb_table_description table_description, idx_t index, bool *out);
idx_t duckdb_table_description_get_column_count(duckdb_table_description table_description);
char *duckdb_table_description_get_column_name(duckdb_table_description table_description, idx_t index);
duckdb_logical_type duckdb_table_description_get_column_type(duckdb_table_description table_description, idx_t index);
duckdb_table_description_create
Stable since 1.1.0.
Creates a table description object. Note that duckdb_table_description_destroy should always be called on the resulting table_description, even if the function returns DuckDBError.
Syntax
duckdb_state duckdb_table_description_create(
duckdb_connection connection,
const char *schema,
const char *table,
duckdb_table_description *out
);
Parameters
connection: The connection context.schema: The schema of the table, ornullptrfor the default schema.table: The table name.out: The resulting table description object. (out)
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_table_description_create_ext
Stable since 1.2.0.
Creates a table description object. Note that duckdb_table_description_destroy must be called on the resulting table_description, even if the function returns DuckDBError.
Syntax
duckdb_state duckdb_table_description_create_ext(
duckdb_connection connection,
const char *catalog,
const char *schema,
const char *table,
duckdb_table_description *out
);
Parameters
connection: The connection context.catalog: The catalog (database) name of the table, ornullptrfor the default catalog.schema: The schema of the table, ornullptrfor the default schema.table: The table name.out: The resulting table description object. (out)
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_table_description_destroy
Stable since 1.1.0.
Destroy the TableDescription object.
Syntax
void duckdb_table_description_destroy(
duckdb_table_description *table_description
);
Parameters
table_description: The table_description to destroy.
duckdb_table_description_error
Stable since 1.1.0.
Returns the error message associated with the given table_description.
If the table_description has no error message, this returns nullptr instead.
The error message should not be freed. It will be de-allocated when duckdb_table_description_destroy is called.
Syntax
const char *duckdb_table_description_error(
duckdb_table_description table_description
);
Parameters
table_description: The table_description to get the error from.
Return Value
The error message, or nullptr if there is none.
duckdb_column_has_default
Stable since 1.1.0.
Check if the column at 'index' index of the table has a DEFAULT expression.
Syntax
duckdb_state duckdb_column_has_default(
duckdb_table_description table_description,
idx_t index,
bool *out
);
Parameters
table_description: The table_description to query.index: The index of the column to query.out: The out-parameter used to store the result. (out)
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_table_description_get_column_count
Stable since 1.5.6.
Return the number of columns of the described table.
Syntax
idx_t duckdb_table_description_get_column_count(
duckdb_table_description table_description
);
Parameters
table_description: The table_description to query.
Return Value
The column count.
duckdb_table_description_get_column_name
Stable since 1.2.0.
Obtain the column name at 'index'.
The out result must be destroyed with duckdb_free.
Syntax
char *duckdb_table_description_get_column_name(
duckdb_table_description table_description,
idx_t index
);
Parameters
table_description: The table_description to query.index: The index of the column to query.
Return Value
The column name.
duckdb_table_description_get_column_type
Stable since 1.5.6.
Obtain the column type at 'index'.
The return value must be destroyed with duckdb_destroy_logical_type.
Syntax
duckdb_logical_type duckdb_table_description_get_column_type(
duckdb_table_description table_description,
idx_t index
);
Parameters
table_description: The table_description to query.index: The index of the column to query.
Return Value
The column type.