类型 – DuckDB - DuckDB 数据库

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

文档 / 客户端API / C

类型

DuckDB 是一个强类型的数据库系统。因此，每一列都指定了单一的类型。该类型在整个列中保持不变。也就是说，标记为 INTEGER 的列将仅包含 INTEGER 值。

DuckDB 还支持复合类型列。例如，可以定义整数数组（INTEGER[]）。也可以将类型定义为任意结构体（ROW(i INTEGER, j VARCHAR)）。因此，原生的 DuckDB 类型对象不仅仅是枚举，而是一个可以嵌套的类。

C API 中的类型使用枚举（duckdb_type）和一个复杂类（duckdb_logical_type）进行建模。对于大多数原始类型，例如整数或变长字符串，枚举已经足够。对于更复杂的类型，如列表、结构体或小数，则必须使用逻辑类型（logical type）。

typedef enum DUCKDB_TYPE {
  DUCKDB_TYPE_INVALID = 0,
  DUCKDB_TYPE_BOOLEAN = 1,
  DUCKDB_TYPE_TINYINT = 2,
  DUCKDB_TYPE_SMALLINT = 3,
  DUCKDB_TYPE_INTEGER = 4,
  DUCKDB_TYPE_BIGINT = 5,
  DUCKDB_TYPE_UTINYINT = 6,
  DUCKDB_TYPE_USMALLINT = 7,
  DUCKDB_TYPE_UINTEGER = 8,
  DUCKDB_TYPE_UBIGINT = 9,
  DUCKDB_TYPE_FLOAT = 10,
  DUCKDB_TYPE_DOUBLE = 11,
  DUCKDB_TYPE_TIMESTAMP = 12,
  DUCKDB_TYPE_DATE = 13,
  DUCKDB_TYPE_TIME = 14,
  DUCKDB_TYPE_INTERVAL = 15,
  DUCKDB_TYPE_HUGEINT = 16,
  DUCKDB_TYPE_UHUGEINT = 32,
  DUCKDB_TYPE_VARCHAR = 17,
  DUCKDB_TYPE_BLOB = 18,
  DUCKDB_TYPE_DECIMAL = 19,
  DUCKDB_TYPE_TIMESTAMP_S = 20,
  DUCKDB_TYPE_TIMESTAMP_MS = 21,
  DUCKDB_TYPE_TIMESTAMP_NS = 22,
  DUCKDB_TYPE_ENUM = 23,
  DUCKDB_TYPE_LIST = 24,
  DUCKDB_TYPE_STRUCT = 25,
  DUCKDB_TYPE_MAP = 26,
  DUCKDB_TYPE_ARRAY = 33,
  DUCKDB_TYPE_UUID = 27,
  DUCKDB_TYPE_UNION = 28,
  DUCKDB_TYPE_BIT = 29,
  DUCKDB_TYPE_TIME_TZ = 30,
  DUCKDB_TYPE_TIMESTAMP_TZ = 31,
} duckdb_type;

函数

结果集中某列的枚举类型可以使用 duckdb_column_type 函数获取。某列的逻辑类型可以使用 duckdb_column_logical_type 函数获取。

duckdb_value 系列函数会根据需要自动转换（auto-cast）值。例如，在类型为 duckdb_value_int32 的列上使用 duckdb_value_double 是完全没问题的。该值会被自动转换并作为 double 返回。请注意，在某些情况下转换可能会失败。例如，当我们请求 duckdb_value_int8 而该值无法容纳在 int8 中时就会发生这种情况。在这种情况下，将返回一个默认值（通常为 0 或 nullptr）。如果对应的值为 NULL，也会返回相同的默认值。

duckdb_value_is_null 函数可用于检查特定值是否为 NULL。

自动转换规则的一个例外是 duckdb_value_varchar_internal 函数。此函数不执行自动转换，且仅适用于 VARCHAR 列。该函数存在的原因是结果不需要释放内存。

duckdb_value_varchar 和 duckdb_value_blob 要求使用 duckdb_free 来释放结果内存。

`duckdb_fetch_chunk`

duckdb_fetch_chunk 函数可用于从 DuckDB 结果集中读取数据块，这是使用 C API 从 DuckDB 结果中读取数据的最高效方式。这也是从 DuckDB 结果中读取某些特定类型数据的唯一方式。例如，duckdb_value 函数不支持对复合类型（列表或结构体）或更复杂类型（如枚举或小数）进行结构化读取。

有关数据块的更多信息，请参阅关于数据块的文档。

API参考概览

duckdb_data_chunk duckdb_result_get_chunk(duckdb_result result, idx_t chunk_index);
bool duckdb_result_is_streaming(duckdb_result result);
idx_t duckdb_result_chunk_count(duckdb_result result);
duckdb_result_type duckdb_result_return_type(duckdb_result result);

日期时间戳辅助函数

duckdb_date_struct duckdb_from_date(duckdb_date date);
duckdb_date duckdb_to_date(duckdb_date_struct date);
bool duckdb_is_finite_date(duckdb_date date);
duckdb_time_struct duckdb_from_time(duckdb_time time);
duckdb_time_tz duckdb_create_time_tz(int64_t micros, int32_t offset);
duckdb_time_tz_struct duckdb_from_time_tz(duckdb_time_tz micros);
duckdb_time duckdb_to_time(duckdb_time_struct time);
duckdb_timestamp_struct duckdb_from_timestamp(duckdb_timestamp ts);
duckdb_timestamp duckdb_to_timestamp(duckdb_timestamp_struct ts);
bool duckdb_is_finite_timestamp(duckdb_timestamp ts);
bool duckdb_is_finite_timestamp_s(duckdb_timestamp_s ts);
bool duckdb_is_finite_timestamp_ms(duckdb_timestamp_ms ts);
bool duckdb_is_finite_timestamp_ns(duckdb_timestamp_ns ts);

Hugeint 辅助函数

double duckdb_hugeint_to_double(duckdb_hugeint val);
duckdb_hugeint duckdb_double_to_hugeint(double val);

Decimal 辅助函数

duckdb_decimal duckdb_double_to_decimal(double val, uint8_t width, uint8_t scale);
double duckdb_decimal_to_double(duckdb_decimal val);

逻辑类型接口

duckdb_logical_type duckdb_create_logical_type(duckdb_type type);
char *duckdb_logical_type_get_alias(duckdb_logical_type type);
void duckdb_logical_type_set_alias(duckdb_logical_type type, const char *alias);
duckdb_logical_type duckdb_create_list_type(duckdb_logical_type type);
duckdb_logical_type duckdb_create_array_type(duckdb_logical_type type, idx_t array_size);
duckdb_logical_type duckdb_create_map_type(duckdb_logical_type key_type, duckdb_logical_type value_type);
duckdb_logical_type duckdb_create_union_type(duckdb_logical_type *member_types, const char **member_names, idx_t member_count);
duckdb_logical_type duckdb_create_struct_type(duckdb_logical_type *member_types, const char **member_names, idx_t member_count);
duckdb_logical_type duckdb_create_enum_type(const char **member_names, idx_t member_count);
duckdb_logical_type duckdb_create_decimal_type(uint8_t width, uint8_t scale);
duckdb_type duckdb_get_type_id(duckdb_logical_type type);
uint8_t duckdb_decimal_width(duckdb_logical_type type);
uint8_t duckdb_decimal_scale(duckdb_logical_type type);
duckdb_type duckdb_decimal_internal_type(duckdb_logical_type type);
duckdb_type duckdb_enum_internal_type(duckdb_logical_type type);
uint32_t duckdb_enum_dictionary_size(duckdb_logical_type type);
char *duckdb_enum_dictionary_value(duckdb_logical_type type, idx_t index);
duckdb_logical_type duckdb_list_type_child_type(duckdb_logical_type type);
duckdb_logical_type duckdb_array_type_child_type(duckdb_logical_type type);
idx_t duckdb_array_type_array_size(duckdb_logical_type type);
duckdb_logical_type duckdb_map_type_key_type(duckdb_logical_type type);
duckdb_logical_type duckdb_map_type_value_type(duckdb_logical_type type);
idx_t duckdb_struct_type_child_count(duckdb_logical_type type);
char *duckdb_struct_type_child_name(duckdb_logical_type type, idx_t index);
duckdb_logical_type duckdb_struct_type_child_type(duckdb_logical_type type, idx_t index);
idx_t duckdb_union_type_member_count(duckdb_logical_type type);
char *duckdb_union_type_member_name(duckdb_logical_type type, idx_t index);
duckdb_logical_type duckdb_union_type_member_type(duckdb_logical_type type, idx_t index);
void duckdb_destroy_logical_type(duckdb_logical_type *type);
duckdb_state duckdb_register_logical_type(duckdb_connection con, duckdb_logical_type type, duckdb_create_type_info info);

`duckdb_result_get_chunk`

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

从 duckdb_result 中获取一个数据块。此函数应重复调用，直到结果耗尽。

结果必须使用 duckdb_destroy_data_chunk 进行销毁。

此函数取代了所有 duckdb_value 函数，以及 duckdb_column_data 和 duckdb_nullmask_data 函数。它能带来显著的性能提升，应在较新的代码库中优先使用。

如果使用了此函数，则不能使用其他任何结果函数，反之亦然（即此函数不能与遗留的结果函数混合使用）。

使用 duckdb_result_chunk_count 来确定结果中有多少个数据块。

语法

duckdb_data_chunk duckdb_result_get_chunk(
  duckdb_result result,
  idx_t chunk_index
);

参数

result: 要从中获取数据块的结果对象。
chunk_index: 要获取的数据块索引。