⌘+k ctrl+k
1.1.3 (stable)
Search Shortcut cmd + k | ctrl + k
Data Chunks

数据块代表表的水平切片。它们包含多个向量,每个向量最多可以容纳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_validityduckdb_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: 数据块中的元组数量