追加器 – DuckDB 数据库

搜索快捷键 cmd + k | ctrl + k

文档 / 客户端API / C

追加器

追加器是从 C 接口将数据加载到 DuckDB 中最高效的方式，建议用于快速数据加载。追加器比使用预处理语句或单独的 INSERT INTO 语句快得多。

数据追加以行式格式进行。对于每个列，应调用一次 duckdb_append_[type]，然后通过调用 duckdb_appender_end_row 来完成该行。所有行追加完成后，应使用 duckdb_appender_destroy 来完成追加器并清理生成的内存。

请注意，即使函数返回 DuckDBError，也应始终在生成的追加器上调用 duckdb_appender_destroy。

示例

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);
duckdb_state duckdb_appender_create_ext(duckdb_connection connection, const char *catalog, 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_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);

`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: 创建追加器所用的连接上下文。
schema: 要追加到的表的模式，或者对于默认模式使用 nullptr。
table: 要追加到的表名。
out_appender: 生成的追加器对象。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_appender_create_ext`

创建一个追加器对象。

请注意，必须使用 duckdb_appender_destroy 销毁该对象。

语法

duckdb_state duckdb_appender_create_ext(
  duckdb_connection connection,
  const char *catalog,
  const char *schema,
  const char *table,
  duckdb_appender *out_appender
);

参数

connection: 创建追加器所用的连接上下文。
catalog: 要追加到的表的目录，或者对于默认目录使用 nullptr。
schema: 要追加到的表的模式，或者对于默认模式使用 nullptr。
table: 要追加到的表名。
out_appender: 生成的追加器对象。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_appender_column_count`

返回属于追加器的列数。如果不存在活动列列表，则此值等于表的物理列数。

语法

idx_t duckdb_appender_column_count(
  duckdb_appender appender
);

参数

appender: 获取列数的追加器。

返回值

数据块中的列数。

`duckdb_appender_column_type`

返回指定索引处列的类型。这可以是活动列列表中的类型，也可以是接收表中列的相同类型。

注意：生成的类型必须使用 duckdb_destroy_logical_type 销毁。

语法

duckdb_logical_type duckdb_appender_column_type(
  duckdb_appender appender,
  idx_t col_idx
);

参数

appender: 获取列类型的追加器。
col_idx: 要获取其类型的列索引。

返回值

列的 duckdb_logical_type。

`duckdb_appender_error`

返回与给定追加器关联的错误消息。如果追加器没有错误消息，则返回 nullptr。

错误消息不应被释放。当调用 duckdb_appender_destroy 时，它将被解除分配。

语法

const char *duckdb_appender_error(
  duckdb_appender appender
);

参数

appender: 获取错误的追加器。

返回值

错误消息，如果没有则为 nullptr。

`duckdb_appender_flush`

将追加器刷新到表，强制清除追加器的缓存。如果刷新数据触发了约束违规或任何其他错误，则所有数据都将失效，并且此函数返回 DuckDBError。无法再追加更多值。调用 duckdb_appender_error 获取错误消息，然后调用 duckdb_appender_destroy 销毁已失效的追加器。

语法

duckdb_state duckdb_appender_flush(
  duckdb_appender appender
);

参数

appender: 要刷新的追加器。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_appender_close`

通过刷新所有中间状态并关闭追加器以阻止进一步追加操作。如果刷新数据触发了约束违规或任何其他错误，则所有数据都将失效，并且此函数返回 DuckDBError。调用 duckdb_appender_error 获取错误消息，然后调用 duckdb_appender_destroy 销毁已失效的追加器。

语法

duckdb_state duckdb_appender_close(
  duckdb_appender appender
);

参数

appender: 要刷新并关闭的追加器。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_appender_destroy`

通过将所有中间状态刷新到表并销毁追加器来关闭它。通过销毁，此函数会解除分配与追加器关联的所有内存。如果刷新数据触发了约束违规，则所有数据都将失效，并且此函数返回 DuckDBError。由于追加器被销毁，将无法再通过 duckdb_appender_error 获取特定错误消息。因此，如果您需要了解特定错误，请在销毁追加器之前调用 duckdb_appender_close。

语法

duckdb_state duckdb_appender_destroy(
  duckdb_appender *appender
);

参数

appender: 要刷新、关闭并销毁的追加器。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_appender_add_column`

将列追加到追加器的活动列列表。立即刷新所有先前数据。

活动列列表指定了刷新数据时预期包含的所有列。任何非活动列将填充其默认值或 NULL。

语法

duckdb_state duckdb_appender_add_column(
  duckdb_appender appender,
  const char *name
);

参数

appender: 要添加列的追加器。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_appender_clear_columns`

从追加器的活动列列表中移除所有列，将追加器重置为将所有列视为活动状态。立即刷新所有先前数据。

语法

duckdb_state duckdb_appender_clear_columns(
  duckdb_appender appender
);

参数

appender: 要清除列的追加器。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_appender_begin_row`

一个无操作函数，为向后兼容性提供。不执行任何操作。只需 duckdb_appender_end_row 即可。

语法

duckdb_state duckdb_appender_begin_row(
  duckdb_appender appender
);

`duckdb_appender_end_row`

完成当前行的追加。调用 end_row 后，可以追加下一行。

语法

duckdb_state duckdb_appender_end_row(
  duckdb_appender appender
);

参数

appender: 追加器。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_append_default`

将 DEFAULT 值（如果列没有 DEFAULT 则为 NULL）追加到追加器。

语法

duckdb_state duckdb_append_default(
  duckdb_appender appender
);

`duckdb_append_default_to_chunk`

将 DEFAULT 值（如果列没有 DEFAULT 则为 NULL）在指定行和列追加到从指定追加器创建的数据块。列的默认值必须是常量。不支持 nextval('seq') 或 random() 等非确定性表达式。

语法

duckdb_state duckdb_append_default_to_chunk(
  duckdb_appender appender,
  duckdb_data_chunk chunk,
  idx_t col,
  idx_t row
);

参数

appender: 获取默认值的追加器。
chunk: 要追加默认值的数据块。
col: 要追加默认值的数据块列索引。
row: 要追加默认值的数据块行索引。

duckdb_state duckdb_append_bool(
  duckdb_appender appender,
  bool value
);

`duckdb_append_int8`

将 int8_t 值追加到追加器。

语法

duckdb_state duckdb_append_int8(
  duckdb_appender appender,
  int8_t value
);

`duckdb_append_int16`

将 int16_t 值追加到追加器。

语法

duckdb_state duckdb_append_int16(
  duckdb_appender appender,
  int16_t value
);

`duckdb_append_int32`

将 int32_t 值追加到追加器。

语法

duckdb_state duckdb_append_int32(
  duckdb_appender appender,
  int32_t value
);

`duckdb_append_int64`

将 int64_t 值追加到追加器。

语法

duckdb_state duckdb_append_int64(
  duckdb_appender appender,
  int64_t value
);

`duckdb_append_hugeint`

将 duckdb_hugeint 值追加到追加器。

语法

duckdb_state duckdb_append_hugeint(
  duckdb_appender appender,
  duckdb_hugeint value
);

`duckdb_append_uint8`

将 uint8_t 值追加到追加器。

语法

duckdb_state duckdb_append_uint8(
  duckdb_appender appender,
  uint8_t value
);

`duckdb_append_uint16`

将 uint16_t 值追加到追加器。

语法

duckdb_state duckdb_append_uint16(
  duckdb_appender appender,
  uint16_t value
);

`duckdb_append_uint32`

将 uint32_t 值追加到追加器。

语法

duckdb_state duckdb_append_uint32(
  duckdb_appender appender,
  uint32_t value
);

`duckdb_append_uint64`

将 uint64_t 值追加到追加器。

语法

duckdb_state duckdb_append_uint64(
  duckdb_appender appender,
  uint64_t value
);

`duckdb_append_uhugeint`

将 duckdb_uhugeint 值追加到追加器。

语法

duckdb_state duckdb_append_uhugeint(
  duckdb_appender appender,
  duckdb_uhugeint value
);

`duckdb_append_float`

将浮点值追加到追加器。

语法

duckdb_state duckdb_append_float(
  duckdb_appender appender,
  float value
);

`duckdb_append_double`

将双精度浮点值追加到追加器。

语法

duckdb_state duckdb_append_double(
  duckdb_appender appender,
  double value
);

`duckdb_append_date`

将 duckdb_date 值追加到追加器。

语法

duckdb_state duckdb_append_date(
  duckdb_appender appender,
  duckdb_date value
);

`duckdb_append_time`

将 duckdb_time 值追加到追加器。

语法

duckdb_state duckdb_append_time(
  duckdb_appender appender,
  duckdb_time value
);

`duckdb_append_timestamp`

将 duckdb_timestamp 值追加到追加器。

语法

duckdb_state duckdb_append_timestamp(
  duckdb_appender appender,
  duckdb_timestamp value
);

`duckdb_append_interval`

将 duckdb_interval 值追加到追加器。

语法

duckdb_state duckdb_append_interval(
  duckdb_appender appender,
  duckdb_interval value
);

`duckdb_append_varchar`

将 varchar 值追加到追加器。

语法

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

`duckdb_append_varchar_length`

将 varchar 值追加到追加器。

语法

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

`duckdb_append_blob`

将 blob 值追加到追加器。

语法

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

`duckdb_append_null`

将 NULL 值（任何类型）追加到追加器。

语法

duckdb_state duckdb_append_null(
  duckdb_appender appender
);

`duckdb_append_value`

将 duckdb_value 追加到追加器。

语法

duckdb_state duckdb_append_value(
  duckdb_appender appender,
  duckdb_value value
);

`duckdb_append_data_chunk`

将预填充的数据块追加到指定的追加器。如果数据块类型与活动追加器类型不匹配，则尝试进行类型转换。

语法

duckdb_state duckdb_append_data_chunk(
  duckdb_appender appender,
  duckdb_data_chunk chunk
);

参数

appender: 要追加到的追加器。
chunk: 要追加的数据块。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

关于此页面

本文中