Appender – DuckDB - DuckDB 数据库

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

文档 / 客户端API / C

Appender

Appender（追加器）是在 C 接口中向 DuckDB 加载数据的最高效方式，也是推荐用于快速数据加载的方法。Appender 比使用预编译语句（prepared statements）或单独的 INSERT INTO 语句要快得多。

追加操作以行（row-wise）格式进行。对于每一列，都应调用一次 duckdb_append_[type]，之后应通过调用 duckdb_appender_end_row 来结束该行。在所有行都追加完成后，应使用 duckdb_appender_destroy 来终结 Appender 并清理相关内存。

请注意，即使函数返回 DuckDBError，也始终应对生成的 Appender 调用 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);
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);
const char *duckdb_appender_error(duckdb_appender appender);
duckdb_error_data duckdb_appender_error_data(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`

创建一个 Appender 对象。

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

语法

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

参数

connection：用于创建 Appender 的连接上下文。
schema：要追加数据的表所在的模式（schema），若使用默认模式则传入 nullptr。
table：要追加数据的表名。
out_appender：生成的 Appender 对象。

返回值

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

`duckdb_appender_create_ext`

创建一个 Appender 对象。

请注意，该对象必须使用 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：用于创建 Appender 的连接上下文。
catalog：要追加数据的表所在的目录（catalog），若使用默认目录则传入 nullptr。
schema：要追加数据的表所在的模式（schema），若使用默认模式则传入 nullptr。
table：要追加数据的表名。
out_appender：生成的 Appender 对象。

返回值

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

`duckdb_appender_create_query`

创建一个 Appender 对象，该对象执行给定的查询并将任何追加的数据应用于其中。

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

语法

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

参数

connection：用于创建 Appender 的连接上下文。
query：要执行的查询，可以是 INSERT、DELETE、UPDATE 或 MERGE INTO 语句。
column_count：要追加的列数。
types：要追加的列的类型。
table_name：（可选）用于引用追加数据的表名，默认为 "appended_data"。
column_names：（可选）列名列表，默认为 "col1", "col2", …
out_appender：生成的 Appender 对象。

返回值

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

`duckdb_appender_column_count`

返回属于 Appender 的列数。如果没有活跃的列列表，则该值等于表的物理列数。

语法

idx_t duckdb_appender_column_count(
  duckdb_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：获取列类型的 Appender。
col_idx：要获取其类型的列索引。

`duckdb_appender_error`

警告：弃用通知。此方法计划在未来的版本中移除。请改用 duckdb_appender_error_data。

返回与 Appender 关联的错误消息。如果 Appender 没有错误消息，则返回 nullptr。

错误消息不应被释放。它将在调用 duckdb_appender_destroy 时被销毁。

语法

const char *duckdb_appender_error(
  duckdb_appender appender
);

`duckdb_appender_flush`

将 Appender 数据刷入表中，强制清除 Appender 的缓存。如果刷新数据触发了约束冲突或任何其他错误，则所有数据将失效，函数返回 DuckDBError。此时无法再追加更多值。请调用 duckdb_appender_error_data 获取错误数据，然后调用 duckdb_appender_destroy 销毁已失效的 Appender。

语法

duckdb_state duckdb_appender_flush(
  duckdb_appender appender
);

返回值

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

`duckdb_appender_close`

通过刷新所有中间状态并关闭后续追加功能来关闭 Appender。如果刷新数据触发了约束冲突或任何其他错误，则所有数据将失效，函数返回 DuckDBError。请调用 duckdb_appender_error_data 获取错误数据，然后调用 duckdb_appender_destroy 销毁已失效的 Appender。

语法

duckdb_state duckdb_appender_close(
  duckdb_appender appender
);

返回值

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

通过将所有中间状态刷入表并销毁 Appender 来关闭它。此函数会释放与 Appender 相关的所有内存。如果刷新数据触发了约束冲突，则所有数据将失效，函数返回 DuckDBError。由于 Appender 已被销毁，无法再通过 duckdb_appender_error 获取具体的错误消息。因此，如果您需要了解具体错误信息，请在销毁 Appender 前调用 duckdb_appender_close。

语法

duckdb_state duckdb_appender_destroy(
  duckdb_appender *appender
);

参数

appender：要刷新、关闭并销毁的 Appender。

返回值

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

`duckdb_appender_add_column`

将一列添加到 Appender 的活跃列列表中。此操作会立即刷新之前的所有数据。

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

语法

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

参数

appender：要添加列的 Appender。

返回值

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

`duckdb_appender_clear_columns`

从 Appender 的活跃列列表中移除所有列，重置 Appender 以将所有列视为活跃状态。此操作会立即刷新之前的所有数据。

语法

duckdb_state duckdb_appender_clear_columns(
  duckdb_appender 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：Appender 对象。

返回值

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

`duckdb_append_default`

向 Appender 追加一个 DEFAULT 值（如果列没有 DEFAULT 值，则为 NULL）。

语法

duckdb_state duckdb_append_default(
  duckdb_appender appender
);

`duckdb_append_default_to_chunk`

向由指定 Appender 创建的块的特定行和列中追加一个 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：获取默认值的 Appender。
chunk：要追加默认值的数据块。
col：要追加默认值的块列索引。
row：要追加默认值的块行索引。

duckdb_state duckdb_append_bool(
  duckdb_appender appender,
  bool value
);

`duckdb_append_int8`

向 Appender 追加一个 int8_t 值。

语法

duckdb_state duckdb_append_int8(
  duckdb_appender appender,
  int8_t value
);

`duckdb_append_int16`

向 Appender 追加一个 int16_t 值。

语法

duckdb_state duckdb_append_int16(
  duckdb_appender appender,
  int16_t value
);

`duckdb_append_int32`

向 Appender 追加一个 int32_t 值。

语法

duckdb_state duckdb_append_int32(
  duckdb_appender appender,
  int32_t value
);

`duckdb_append_int64`

向 Appender 追加一个 int64_t 值。

语法

duckdb_state duckdb_append_int64(
  duckdb_appender appender,
  int64_t value
);

`duckdb_append_hugeint`

向 Appender 追加一个 duckdb_hugeint 值。

语法

duckdb_state duckdb_append_hugeint(
  duckdb_appender appender,
  duckdb_hugeint value
);

`duckdb_append_uint8`

向 Appender 追加一个 uint8_t 值。

语法

duckdb_state duckdb_append_uint8(
  duckdb_appender appender,
  uint8_t value
);

`duckdb_append_uint16`

向 Appender 追加一个 uint16_t 值。

语法

duckdb_state duckdb_append_uint16(
  duckdb_appender appender,
  uint16_t value
);

`duckdb_append_uint32`

向 Appender 追加一个 uint32_t 值。

语法

duckdb_state duckdb_append_uint32(
  duckdb_appender appender,
  uint32_t value
);

`duckdb_append_uint64`

向 Appender 追加一个 uint64_t 值。

语法

duckdb_state duckdb_append_uint64(
  duckdb_appender appender,
  uint64_t value
);

`duckdb_append_uhugeint`

向 Appender 追加一个 duckdb_uhugeint 值。

语法

duckdb_state duckdb_append_uhugeint(
  duckdb_appender appender,
  duckdb_uhugeint value
);

`duckdb_append_float`

向 Appender 追加一个 float 值。

语法

duckdb_state duckdb_append_float(
  duckdb_appender appender,
  float value
);

`duckdb_append_double`

向 Appender 追加一个 double 值。

语法

duckdb_state duckdb_append_double(
  duckdb_appender appender,
  double value
);

`duckdb_append_date`

向 Appender 追加一个 duckdb_date 值。

语法

duckdb_state duckdb_append_date(
  duckdb_appender appender,
  duckdb_date value
);

`duckdb_append_time`

向 Appender 追加一个 duckdb_time 值。

语法

duckdb_state duckdb_append_time(
  duckdb_appender appender,
  duckdb_time value
);

`duckdb_append_timestamp`

向 Appender 追加一个 duckdb_timestamp 值。

语法

duckdb_state duckdb_append_timestamp(
  duckdb_appender appender,
  duckdb_timestamp value
);

`duckdb_append_interval`

向 Appender 追加一个 duckdb_interval 值。

语法

duckdb_state duckdb_append_interval(
  duckdb_appender appender,
  duckdb_interval value
);

`duckdb_append_varchar`

向 Appender 追加一个 varchar 值。

语法

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

`duckdb_append_varchar_length`

向 Appender 追加一个 varchar 值。

语法

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

`duckdb_append_blob`

向 Appender 追加一个 blob 值。

语法

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

`duckdb_append_null`

向 Appender 追加一个 NULL 值（适用于任何类型）。

语法

duckdb_state duckdb_append_null(
  duckdb_appender appender
);

`duckdb_append_value`

向 Appender 追加一个 duckdb_value。

语法

duckdb_state duckdb_append_value(
  duckdb_appender appender,
  duckdb_value value
);

`duckdb_append_data_chunk`

向指定的 Appender 追加预填充的数据块。如果数据块类型与活跃 Appender 类型不匹配，则会尝试进行类型转换。

语法

duckdb_state duckdb_append_data_chunk(
  duckdb_appender appender,
  duckdb_data_chunk chunk
);

参数

appender：要追加数据的 Appender。
chunk：要追加的数据块。

返回值

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

关于此页面

行为准则商标使用指南

关于此页面

本文中