C API - Appender

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

duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table, duckdb_appender *out_appender);
const char *duckdb_appender_error(duckdb_appender appender);
duckdb_state duckdb_appender_flush(duckdb_appender appender);
duckdb_state duckdb_appender_close(duckdb_appender appender);
duckdb_state duckdb_appender_destroy(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_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_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_appender_create


Creates an appender object.

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, or nullptr for the default schema.

  • table

The table name to append to.

  • out_appender

The resulting appender object.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_error


Returns the error message associated with the given appender. If the appender has no error message, this returns nullptr instead.

The error message should be freed using duckdb_free.

Syntax


const char *duckdb_appender_error(
  duckdb_appender appender
);

Parameters


  • appender

The appender to get the error from.

  • returns

The error message, or nullptr if there is none.


duckdb_appender_flush


Flush the appender to the table, forcing the cache of the appender to be cleared and the data to be appended to the base table.

This should generally not be used unless you know what you are doing. Instead, call duckdb_appender_destroy when you are done with the appender.

Syntax


duckdb_state duckdb_appender_flush(
  duckdb_appender appender
);

Parameters


  • appender

The appender to flush.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_close


Close the appender, flushing all intermediate state in the appender to the table and closing it for further appends.

This is generally not necessary. Call duckdb_appender_destroy instead.

Syntax


duckdb_state duckdb_appender_close(
  duckdb_appender appender
);

Parameters


  • appender

The appender to flush and close.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_destroy


Close the appender and destroy it. Flushing all intermediate state in the appender to the table, and de-allocating all memory associated with the appender.

Syntax


duckdb_state duckdb_appender_destroy(
  duckdb_appender *appender
);

Parameters


  • appender

The appender to flush, close and destroy.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_begin_row


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
);


duckdb_appender_end_row


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.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_append_bool


Append a bool value to the appender.

Syntax


duckdb_state duckdb_append_bool(
  duckdb_appender appender,
  bool value
);


duckdb_append_int8


Append an int8_t value to the appender.

Syntax


duckdb_state duckdb_append_int8(
  duckdb_appender appender,
  int8_t value
);


duckdb_append_int16


Append an int16_t value to the appender.

Syntax


duckdb_state duckdb_append_int16(
  duckdb_appender appender,
  int16_t value
);


duckdb_append_int32


Append an int32_t value to the appender.

Syntax


duckdb_state duckdb_append_int32(
  duckdb_appender appender,
  int32_t value
);


duckdb_append_int64


Append an int64_t value to the appender.

Syntax


duckdb_state duckdb_append_int64(
  duckdb_appender appender,
  int64_t value
);


duckdb_append_hugeint


Append a duckdb_hugeint value to the appender.

Syntax


duckdb_state duckdb_append_hugeint(
  duckdb_appender appender,
  duckdb_hugeint value
);


duckdb_append_uint8


Append a uint8_t value to the appender.

Syntax


duckdb_state duckdb_append_uint8(
  duckdb_appender appender,
  uint8_t value
);


duckdb_append_uint16


Append a uint16_t value to the appender.

Syntax


duckdb_state duckdb_append_uint16(
  duckdb_appender appender,
  uint16_t value
);


duckdb_append_uint32


Append a uint32_t value to the appender.

Syntax


duckdb_state duckdb_append_uint32(
  duckdb_appender appender,
  uint32_t value
);


duckdb_append_uint64


Append a uint64_t value to the appender.

Syntax


duckdb_state duckdb_append_uint64(
  duckdb_appender appender,
  uint64_t value
);


duckdb_append_float


Append a float value to the appender.

Syntax


duckdb_state duckdb_append_float(
  duckdb_appender appender,
  float value
);


duckdb_append_double


Append a double value to the appender.

Syntax


duckdb_state duckdb_append_double(
  duckdb_appender appender,
  double value
);


duckdb_append_date


Append a duckdb_date value to the appender.

Syntax


duckdb_state duckdb_append_date(
  duckdb_appender appender,
  duckdb_date value
);


duckdb_append_time


Append a duckdb_time value to the appender.

Syntax


duckdb_state duckdb_append_time(
  duckdb_appender appender,
  duckdb_time value
);


duckdb_append_timestamp


Append a duckdb_timestamp value to the appender.

Syntax


duckdb_state duckdb_append_timestamp(
  duckdb_appender appender,
  duckdb_timestamp value
);


duckdb_append_interval


Append a duckdb_interval value to the appender.

Syntax


duckdb_state duckdb_append_interval(
  duckdb_appender appender,
  duckdb_interval value
);


duckdb_append_varchar


Append a varchar value to the appender.

Syntax


duckdb_state duckdb_append_varchar(
  duckdb_appender appender,
  const char *val
);


duckdb_append_varchar_length


Append a varchar value to the appender.

Syntax


duckdb_state duckdb_append_varchar_length(
  duckdb_appender appender,
  const char *val,
  idx_t length
);


duckdb_append_blob


Append a blob value to the appender.

Syntax


duckdb_state duckdb_append_blob(
  duckdb_appender appender,
  const void *data,
  idx_t length
);


duckdb_append_null


Append a NULL value to the appender (of any type).

Syntax


duckdb_state duckdb_append_null(
  duckdb_appender appender
);