类型 – 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) 进行建模。对于大多数原始类型，例如整数或变长字符串，枚举就足够了。对于更复杂的类型，例如列表、结构体或 Decimal，必须使用逻辑类型。

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 函数会自动转换值类型。例如，在 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 函数不支持复合类型（列表或结构体）或更复杂类型（如枚举和 Decimal）的结构化读取。

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

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: 要获取的数据块索引。