Appenders 是从 C 接口中将数据加载到 DuckDB 的最有效方式，推荐用于快速数据加载。Appender 比使用预处理语句或单独的 INSERT INTO 语句要快得多。
追加操作以行格式进行。对于每一列，应调用duckdb_append_[type]，然后通过调用duckdb_appender_end_row来完成该行。在所有行都追加完毕后，应使用duckdb_appender_destroy来最终化追加器并清理生成的内存。
请注意，即使函数返回DuckDBError，也应始终在结果追加器上调用duckdb_appender_destroy。
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 参考概览
duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table, 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);
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_default(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_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_data_chunk(duckdb_appender appender, duckdb_data_chunk chunk);
duckdb_appender_create
创建一个附加器对象。
请注意，必须使用duckdb_appender_destroy销毁对象。
语法
duckdb_state duckdb_appender_create(
duckdb_connection connection,
const char *schema,
const char *table,
duckdb_appender *out_appender
);
参数
connection: 创建appender的连接上下文。schema: 要追加到的表的模式，或使用nullptr表示默认模式。table: 要追加到的表名。out_appender: 生成的附加器对象。
返回值
DuckDBSuccess 成功时或 DuckDBError 失败时。
duckdb_appender_column_count
返回属于追加器的表中的列数。
Syntax
idx_t duckdb_appender_column_count(
duckdb_appender appender
);
Parameters
appender: 获取列数的appender。
返回值
表中的列数。
duckdb_appender_column_type
返回指定索引处列的类型。
注意：结果类型应使用duckdb_destroy_logical_type销毁。
Syntax
duckdb_logical_type duckdb_appender_column_type(
duckdb_appender appender,
idx_t col_idx
);
Parameters
appender: 从中获取列类型的appender。col_idx: 要获取类型的列的索引。
Return Value
列的duckdb_logical_type。
duckdb_appender_error
返回与给定appender关联的错误消息。
如果appender没有错误消息，则返回nullptr。
错误信息不应被释放。当调用duckdb_appender_destroy时，它将被自动释放。
Syntax
const char *duckdb_appender_error(
duckdb_appender appender
);
Parameters
appender: 获取错误的appender。
Return Value
错误信息，如果没有则为 nullptr。
duckdb_appender_flush
将appender刷新到表中，强制清除appender的缓存。如果刷新数据时触发约束违规或任何其他错误，则所有数据都将失效，并且此函数返回DuckDBError。无法再追加更多值。调用duckdb_appender_error以获取错误消息，然后调用duckdb_appender_destroy以销毁失效的appender。
Syntax
duckdb_state duckdb_appender_flush(
duckdb_appender appender
);
Parameters
appender: 要刷新的appender。
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_close
通过刷新所有中间状态并关闭它以进行进一步的追加来关闭appender。如果刷新数据触发约束违规或任何其他错误，则所有数据都将失效，并且此函数返回DuckDBError。调用duckdb_appender_error以获取错误消息，然后调用duckdb_appender_destroy以销毁失效的appender。
Syntax
duckdb_state duckdb_appender_close(
duckdb_appender appender
);
Parameters
appender: 要刷新和关闭的appender。
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_destroy
通过将所有中间状态刷新到表并销毁它来关闭appender。通过销毁它，此函数释放与appender相关的所有内存。如果刷新数据触发约束违规，则所有数据都将失效，并且此函数返回DuckDBError。由于appender的销毁，不再可能通过duckdb_appender_error获取特定的错误消息。因此，如果您需要了解特定错误的详细信息，请在销毁appender之前调用duckdb_appender_close。
Syntax
duckdb_state duckdb_appender_destroy(
duckdb_appender *appender
);
Parameters
appender: 要刷新、关闭和销毁的appender。
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_appender_begin_row
一个nop函数，为了向后兼容性而提供。不执行任何操作。只有duckdb_appender_end_row是必需的。
Syntax
duckdb_state duckdb_appender_begin_row(
duckdb_appender appender
);
duckdb_appender_end_row
完成当前行的追加。调用end_row后，可以追加下一行。
Syntax
duckdb_state duckdb_appender_end_row(
duckdb_appender appender
);
Parameters
appender: 附加器。
Return Value
DuckDBSuccess on success or DuckDBError on failure.
duckdb_append_default
向appender追加一个DEFAULT值（如果列不可用DEFAULT，则为NULL）。
Syntax
duckdb_state duckdb_append_default(
duckdb_appender appender
);
duckdb_append_bool
向appender追加一个布尔值。
Syntax
duckdb_state duckdb_append_bool(
duckdb_appender appender,
bool value
);
duckdb_append_int8
将一个int8_t值附加到appender。
Syntax
duckdb_state duckdb_append_int8(
duckdb_appender appender,
int8_t value
);
duckdb_append_int16
向appender追加一个int16_t值。
Syntax
duckdb_state duckdb_append_int16(
duckdb_appender appender,
int16_t value
);
duckdb_append_int32
向appender追加一个int32_t值。
Syntax
duckdb_state duckdb_append_int32(
duckdb_appender appender,
int32_t value
);
duckdb_append_int64
将一个int64_t值附加到appender。
Syntax
duckdb_state duckdb_append_int64(
duckdb_appender appender,
int64_t value
);
duckdb_append_hugeint
向appender添加一个duckdb_hugeint值。
Syntax
duckdb_state duckdb_append_hugeint(
duckdb_appender appender,
duckdb_hugeint value
);
duckdb_append_uint8
将一个uint8_t值附加到appender。
Syntax
duckdb_state duckdb_append_uint8(
duckdb_appender appender,
uint8_t value
);
duckdb_append_uint16
将一个uint16_t值附加到appender。
Syntax
duckdb_state duckdb_append_uint16(
duckdb_appender appender,
uint16_t value
);
duckdb_append_uint32
向appender追加一个uint32_t值。
Syntax
duckdb_state duckdb_append_uint32(
duckdb_appender appender,
uint32_t value
);
duckdb_append_uint64
将一个uint64_t值附加到appender。
Syntax
duckdb_state duckdb_append_uint64(
duckdb_appender appender,
uint64_t value
);
duckdb_append_uhugeint
向appender追加一个duckdb_uhugeint值。
Syntax
duckdb_state duckdb_append_uhugeint(
duckdb_appender appender,
duckdb_uhugeint value
);
duckdb_append_float
向追加器追加一个浮点值。
Syntax
duckdb_state duckdb_append_float(
duckdb_appender appender,
float value
);
duckdb_append_double
向appender追加一个双精度值。
Syntax
duckdb_state duckdb_append_double(
duckdb_appender appender,
double value
);
duckdb_append_date
向appender追加一个duckdb_date值。
Syntax
duckdb_state duckdb_append_date(
duckdb_appender appender,
duckdb_date value
);
duckdb_append_time
向appender追加一个duckdb_time值。
Syntax
duckdb_state duckdb_append_time(
duckdb_appender appender,
duckdb_time value
);
duckdb_append_timestamp
向appender追加一个duckdb_timestamp值。
Syntax
duckdb_state duckdb_append_timestamp(
duckdb_appender appender,
duckdb_timestamp value
);
duckdb_append_interval
向appender添加一个duckdb_interval值。
Syntax
duckdb_state duckdb_append_interval(
duckdb_appender appender,
duckdb_interval value
);
duckdb_append_varchar
将一个varchar值附加到appender。
Syntax
duckdb_state duckdb_append_varchar(
duckdb_appender appender,
const char *val
);
duckdb_append_varchar_length
将一个varchar值附加到appender。
Syntax
duckdb_state duckdb_append_varchar_length(
duckdb_appender appender,
const char *val,
idx_t length
);
duckdb_append_blob
向追加器追加一个blob值。
Syntax
duckdb_state duckdb_append_blob(
duckdb_appender appender,
const void *data,
idx_t length
);
duckdb_append_null
向appender追加一个NULL值（任何类型）。
Syntax
duckdb_state duckdb_append_null(
duckdb_appender appender
);
duckdb_append_data_chunk
将预填充的数据块附加到指定的附加器。
数据块的类型必须与表的类型完全匹配，不执行类型转换。 如果类型不匹配或appender处于无效状态，则返回DuckDBError。 如果追加成功，则返回DuckDBSuccess。
Syntax
duckdb_state duckdb_append_data_chunk(
duckdb_appender appender,
duckdb_data_chunk chunk
);
Parameters
appender: 要附加到的附加器。chunk: 要追加的数据块。
Return Value
返回状态。