数据块代表表的水平切片。它们包含多个向量,每个向量最多可以容纳VECTOR_SIZE
行。向量大小可以通过duckdb_vector_size
函数获取,并且是可配置的,但通常设置为2048
。
数据块和向量是DuckDB原生用于存储和表示数据的方式。因此,数据块接口是与DuckDB交互的最有效方式。然而,需要注意的是,使用数据块API正确与DuckDB交互确实需要了解DuckDB的内部向量格式。
数据块可以以两种方式使用:
- 读取数据:可以使用
duckdb_fetch_chunk
方法从查询结果中获取数据块,或作为用户定义函数的输入。在这种情况下,可以使用向量方法来读取单个值。 - 写入数据: 可以使用
duckdb_create_data_chunk
创建数据块。然后可以将数据块填充值,并在duckdb_append_data_chunk
中使用,将数据写入数据库。
与数据块交互的主要方式是通过使用duckdb_data_chunk_get_vector
方法获取数据块的内部向量。之后,可以使用向量方法来读取或写入各个向量。
API Reference Overview
duckdb_data_chunk duckdb_create_data_chunk(duckdb_logical_type *types, idx_t column_count);
void duckdb_destroy_data_chunk(duckdb_data_chunk *chunk);
void duckdb_data_chunk_reset(duckdb_data_chunk chunk);
idx_t duckdb_data_chunk_get_column_count(duckdb_data_chunk chunk);
duckdb_vector duckdb_data_chunk_get_vector(duckdb_data_chunk chunk, idx_t col_idx);
idx_t duckdb_data_chunk_get_size(duckdb_data_chunk chunk);
void duckdb_data_chunk_set_size(duckdb_data_chunk chunk, idx_t size);
duckdb_create_data_chunk
创建一个具有指定列类型的空数据块。
结果必须使用duckdb_destroy_data_chunk
销毁。
Syntax
duckdb_data_chunk duckdb_create_data_chunk(
duckdb_logical_type *types,
idx_t column_count
);
Parameters
types
: 一个列类型的数组。列类型不能包含 ANY 和 INVALID 类型。column_count
: 列的数量。
Return Value
数据块。
duckdb_destroy_data_chunk
销毁数据块并释放为该块分配的所有内存。
Syntax
void duckdb_destroy_data_chunk(
duckdb_data_chunk *chunk
);
Parameters
chunk
: 要销毁的数据块。
duckdb_data_chunk_reset
重置数据块,清除有效性掩码并将数据块的基数设置为0。
调用此方法后,您必须调用duckdb_vector_get_validity
和duckdb_vector_get_data
以获取当前
数据和有效性指针
Syntax
void duckdb_data_chunk_reset(
duckdb_data_chunk chunk
);
Parameters
chunk
: 要重置的数据块。
duckdb_data_chunk_get_column_count
检索数据块中的列数。
Syntax
idx_t duckdb_data_chunk_get_column_count(
duckdb_data_chunk chunk
);
Parameters
chunk
: 从中获取数据的数据块
Return Value
数据块中的列数
duckdb_data_chunk_get_vector
检索数据块中指定列索引处的向量。
指向向量的指针在块存活期间有效。 它不需要被销毁。
Syntax
duckdb_vector duckdb_data_chunk_get_vector(
duckdb_data_chunk chunk,
idx_t col_idx
);
Parameters
chunk
: 从中获取数据的数据块
Return Value
向量
duckdb_data_chunk_get_size
检索数据块中当前的元组数量。
Syntax
idx_t duckdb_data_chunk_get_size(
duckdb_data_chunk chunk
);
Parameters
chunk
: 从中获取数据的数据块
Return Value
数据块中的元组数量
duckdb_data_chunk_set_size
设置数据块中当前元组的数量。
Syntax
void duckdb_data_chunk_set_size(
duckdb_data_chunk chunk,
idx_t size
);
Parameters
chunk
: 设置大小的数据块size
: 数据块中的元组数量