DuckDB 是一个强类型的数据库系统。因此,每一列都有一个指定的单一类型。这个类型在整个列中是恒定的。也就是说,标记为 INTEGER
的列将只包含 INTEGER
值。
DuckDB 还支持复合类型的列。例如,可以定义一个整数数组(INTEGER[]
)。也可以将类型定义为任意结构体(ROW(i INTEGER, j VARCHAR)
)。因此,原生的 DuckDB 类型对象不仅仅是枚举,而是一个可以嵌套的类。
C API 中的类型使用枚举(duckdb_type
)和一个复杂类(duckdb_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;
Functions
可以使用duckdb_column_type
函数获取结果中列的枚举类型。可以使用duckdb_column_logical_type
函数获取列的逻辑类型。
duckdb_value
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
函数不支持复合类型(列表或结构体)或更复杂类型(如枚举和十进制)的结构化读取。
有关数据块的更多信息,请参阅数据块文档。
API Reference Overview
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);
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
来找出结果中有多少个块。
Syntax
duckdb_data_chunk duckdb_result_get_chunk(
duckdb_result result,
idx_t chunk_index
);
Parameters
result
: 从中获取数据块的结果对象。chunk_index
: 要从中获取的块索引。
Return Value
生成的数据块。如果块索引超出范围,则返回NULL
。
duckdb_result_is_streaming
警告 弃用通知。此方法计划在未来的版本中移除。
检查内部结果的类型是否为StreamQueryResult。
Syntax
bool duckdb_result_is_streaming(
duckdb_result result
);
Parameters
result
: 要检查的结果对象。
Return Value
结果对象是否为StreamQueryResult类型
duckdb_result_chunk_count
警告 弃用通知。此方法计划在未来的版本中移除。
返回结果中存在的数据块数量。
Syntax
idx_t duckdb_result_chunk_count(
duckdb_result result
);
Parameters
result
: 结果对象
Return Value
结果中存在的数据块数量。
duckdb_result_return_type
返回给定结果的return_type,或在错误时返回DUCKDB_RETURN_TYPE_INVALID
Syntax
duckdb_result_type duckdb_result_return_type(
duckdb_result result
);
Parameters
result
: 结果对象
Return Value
返回类型
duckdb_from_date
将一个duckdb_date
对象分解为年、月和日(存储为duckdb_date_struct
)。
Syntax
duckdb_date_struct duckdb_from_date(
duckdb_date date
);
Parameters
date
: 日期对象,从DUCKDB_TYPE_DATE
列中获取。
Return Value
带有分解元素的duckdb_date_struct
。
duckdb_to_date
从年、月和日期重新组合一个duckdb_date
(duckdb_date_struct
)。
Syntax
duckdb_date duckdb_to_date(
duckdb_date_struct date
);
Parameters
date
: 存储在duckdb_date_struct
中的年、月和日期。
Return Value
duckdb_date
元素。
duckdb_is_finite_date
测试一个duckdb_date
,看看它是否是一个有限值。
Syntax
bool duckdb_is_finite_date(
duckdb_date date
);
Parameters
date
: 日期对象,从DUCKDB_TYPE_DATE
列中获取。
Return Value
如果日期是有限的则为True,如果它是±无穷大则为false。
duckdb_from_time
将一个duckdb_time
对象分解为小时、分钟、秒和微秒(存储为duckdb_time_struct
)。
Syntax
duckdb_time_struct duckdb_from_time(
duckdb_time time
);
Parameters
time
: 时间对象,从DUCKDB_TYPE_TIME
列中获取。
Return Value
带有分解元素的duckdb_time_struct
。
duckdb_create_time_tz
从微秒和时区偏移创建一个duckdb_time_tz
对象。
Syntax
duckdb_time_tz duckdb_create_time_tz(
int64_t micros,
int32_t offset
);
Parameters
micros
: 时间的微秒部分。offset
: 时间的时区偏移量部分。
Return Value
duckdb_time_tz
元素。
duckdb_from_time_tz
将TIME_TZ对象分解为微秒和时区偏移量。
使用 duckdb_from_time
进一步将微秒分解为小时、分钟、秒和微秒。
Syntax
duckdb_time_tz_struct duckdb_from_time_tz(
duckdb_time_tz micros
);
Parameters
micros
: 时间对象,从DUCKDB_TYPE_TIME_TZ
列中获取。
duckdb_to_time
从小时、分钟、秒和微秒重新组合一个duckdb_time
(duckdb_time_struct
)。
Syntax
duckdb_time duckdb_to_time(
duckdb_time_struct time
);
Parameters
time
: 在duckdb_time_struct
中的小时、分钟、秒和微秒。
Return Value
duckdb_time
元素。
duckdb_from_timestamp
将一个duckdb_timestamp
对象分解为一个duckdb_timestamp_struct
。
Syntax
duckdb_timestamp_struct duckdb_from_timestamp(
duckdb_timestamp ts
);
Parameters
ts
: ts对象,从DUCKDB_TYPE_TIMESTAMP
列中获取。
Return Value
带有分解元素的duckdb_timestamp_struct
。
duckdb_to_timestamp
从duckdb_timestamp_struct重新组合一个duckdb_timestamp
。
Syntax
duckdb_timestamp duckdb_to_timestamp(
duckdb_timestamp_struct ts
);
Parameters
ts
: 分解后的元素在duckdb_timestamp_struct
中。
Return Value
duckdb_timestamp
元素。
duckdb_is_finite_timestamp
测试一个duckdb_timestamp
,看看它是否是一个有限值。
Syntax
bool duckdb_is_finite_timestamp(
duckdb_timestamp ts
);
Parameters
ts
: 时间戳对象,从DUCKDB_TYPE_TIMESTAMP
列中获取。
Return Value
如果时间戳是有限的则为True,如果它是±无穷大则为false。
duckdb_hugeint_to_double
将duckdb_hugeint对象(从DUCKDB_TYPE_HUGEINT
列中获取)转换为double类型。
Syntax
double duckdb_hugeint_to_double(
duckdb_hugeint val
);
Parameters
val
: 巨大的整数值。
Return Value
转换后的 double
元素。
duckdb_double_to_hugeint
将双精度值转换为duckdb_hugeint对象。
如果转换失败是因为双精度值太大,结果将为0。
Syntax
duckdb_hugeint duckdb_double_to_hugeint(
double val
);
Parameters
val
: 双精度值。
Return Value
转换后的 duckdb_hugeint
元素。
duckdb_double_to_decimal
将双精度值转换为duckdb_decimal对象。
如果由于双精度值过大或宽度/比例无效而导致转换失败,结果将为0。
Syntax
duckdb_decimal duckdb_double_to_decimal(
double val,
uint8_t width,
uint8_t scale
);
Parameters
val
: 双精度值。
Return Value
转换后的 duckdb_decimal
元素。
duckdb_decimal_to_double
将duckdb_decimal对象(从DUCKDB_TYPE_DECIMAL
列获取)转换为double。
Syntax
double duckdb_decimal_to_double(
duckdb_decimal val
);
Parameters
val
: 十进制值。
Return Value
The converted double
element.
duckdb_create_logical_type
从原始类型创建一个duckdb_logical_type
。
生成的逻辑类型必须使用duckdb_destroy_logical_type
销毁。
如果类型是:DUCKDB_TYPE_INVALID
、DUCKDB_TYPE_DECIMAL
、DUCKDB_TYPE_ENUM
、
DUCKDB_TYPE_LIST
、DUCKDB_TYPE_STRUCT
、DUCKDB_TYPE_MAP
、DUCKDB_TYPE_ARRAY
或 DUCKDB_TYPE_UNION
,则返回一个无效的逻辑类型。
Syntax
duckdb_logical_type duckdb_create_logical_type(
duckdb_type type
);
Parameters
type
: 要创建的原始类型。
Return Value
逻辑类型。
duckdb_logical_type_get_alias
返回duckdb_logical_type的别名,如果已设置,否则返回nullptr
。
结果必须使用duckdb_free
销毁。
Syntax
char *duckdb_logical_type_get_alias(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型
Return Value
别名或 nullptr
duckdb_logical_type_set_alias
设置duckdb_logical_type的别名。
Syntax
void duckdb_logical_type_set_alias(
duckdb_logical_type type,
const char *alias
);
Parameters
type
: 逻辑类型alias
: 要设置的别名
duckdb_create_list_type
从其子类型创建一个LIST类型。
返回类型必须使用duckdb_destroy_logical_type
销毁。
Syntax
duckdb_logical_type duckdb_create_list_type(
duckdb_logical_type type
);
Parameters
type
: 列表的子类型
Return Value
逻辑类型。
duckdb_create_array_type
从其子类型创建一个ARRAY类型。
返回类型必须使用duckdb_destroy_logical_type
销毁。
Syntax
duckdb_logical_type duckdb_create_array_type(
duckdb_logical_type type,
idx_t array_size
);
Parameters
type
: 数组的子类型。array_size
: 数组中的元素数量。
Return Value
逻辑类型。
duckdb_create_map_type
从其键类型和值类型创建一个MAP类型。
返回类型必须使用duckdb_destroy_logical_type
销毁。
Syntax
duckdb_logical_type duckdb_create_map_type(
duckdb_logical_type key_type,
duckdb_logical_type value_type
);
Parameters
key_type
: 映射的键类型。value_type
: 映射的值类型。
Return Value
逻辑类型。
duckdb_create_union_type
从传递的数组中创建一个UNION类型。
返回类型必须使用duckdb_destroy_logical_type
销毁。
Syntax
duckdb_logical_type duckdb_create_union_type(
duckdb_logical_type *member_types,
const char **member_names,
idx_t member_count
);
Parameters
member_types
: 联合成员类型的数组。member_names
: 联合成员的名称。member_count
: 工会成员的数量。
Return Value
逻辑类型。
duckdb_create_struct_type
根据成员类型和名称创建一个STRUCT类型。
结果类型必须使用duckdb_destroy_logical_type
销毁。
Syntax
duckdb_logical_type duckdb_create_struct_type(
duckdb_logical_type *member_types,
const char **member_names,
idx_t member_count
);
Parameters
member_types
: 结构体成员类型的数组。member_names
: 结构体成员的名称数组。member_count
: 结构体的成员数量。
Return Value
逻辑类型。
duckdb_create_enum_type
从传递的成员名称数组创建一个ENUM类型。
生成的类型应使用duckdb_destroy_logical_type
销毁。
Syntax
duckdb_logical_type duckdb_create_enum_type(
const char **member_names,
idx_t member_count
);
Parameters
member_names
: 枚举应包含的名称数组。member_count
: 数组中指定的元素数量。
Return Value
逻辑类型。
duckdb_create_decimal_type
创建一个具有指定宽度和小数位数的DECIMAL类型。
生成的类型应使用duckdb_destroy_logical_type
销毁。
Syntax
duckdb_logical_type duckdb_create_decimal_type(
uint8_t width,
uint8_t scale
);
Parameters
width
: 十进制类型的宽度scale
: 小数类型的比例
Return Value
逻辑类型。
duckdb_get_type_id
检索duckdb_logical_type
的枚举duckdb_type
。
Syntax
duckdb_type duckdb_get_type_id(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型。
Return Value
duckdb_type
的 id。
duckdb_decimal_width
获取十进制类型的宽度。
Syntax
uint8_t duckdb_decimal_width(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型对象
Return Value
十进制类型的宽度
duckdb_decimal_scale
获取小数类型的比例。
Syntax
uint8_t duckdb_decimal_scale(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型对象
Return Value
十进制类型的规模
duckdb_decimal_internal_type
检索十进制类型的内部存储类型。
Syntax
duckdb_type duckdb_decimal_internal_type(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型对象
Return Value
十进制类型的内部类型
duckdb_enum_internal_type
检索枚举类型的内部存储类型。
Syntax
duckdb_type duckdb_enum_internal_type(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型对象
Return Value
枚举类型的内部类型
duckdb_enum_dictionary_size
获取枚举类型的字典大小。
Syntax
uint32_t duckdb_enum_dictionary_size(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型对象
Return Value
枚举类型的字典大小
duckdb_enum_dictionary_value
从枚举中检索指定位置的字典值。
结果必须使用duckdb_free
释放。
Syntax
char *duckdb_enum_dictionary_value(
duckdb_logical_type type,
idx_t index
);
Parameters
type
: 逻辑类型对象index
: 字典中的索引
Return Value
枚举类型的字符串值。必须使用duckdb_free
释放。
duckdb_list_type_child_type
检索给定LIST类型的子类型。也接受MAP类型。
结果必须使用duckdb_destroy_logical_type
释放。
Syntax
duckdb_logical_type duckdb_list_type_child_type(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型,可以是 LIST 或 MAP。
Return Value
LIST 或 MAP 类型的子类型。
duckdb_array_type_child_type
检索给定ARRAY类型的子类型。
结果必须使用duckdb_destroy_logical_type
释放。
Syntax
duckdb_logical_type duckdb_array_type_child_type(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型。必须是 ARRAY。
Return Value
ARRAY 类型的子类型。
duckdb_array_type_array_size
检索给定数组类型的数组大小。
Syntax
idx_t duckdb_array_type_array_size(
duckdb_logical_type type
);
Parameters
type
: The logical type object
Return Value
此数组类型的值可以存储的固定元素数量。
duckdb_map_type_key_type
检索给定映射类型的键类型。
结果必须使用duckdb_destroy_logical_type
释放。
Syntax
duckdb_logical_type duckdb_map_type_key_type(
duckdb_logical_type type
);
Parameters
type
: The logical type object
Return Value
映射类型的关键类型。必须使用duckdb_destroy_logical_type
销毁。
duckdb_map_type_value_type
检索给定映射类型的值类型。
The result must be freed with duckdb_destroy_logical_type
.
Syntax
duckdb_logical_type duckdb_map_type_value_type(
duckdb_logical_type type
);
Parameters
type
: The logical type object
Return Value
映射类型的值类型。必须使用duckdb_destroy_logical_type
销毁。
duckdb_struct_type_child_count
返回结构体类型的子元素数量。
Syntax
idx_t duckdb_struct_type_child_count(
duckdb_logical_type type
);
Parameters
type
: The logical type object
Return Value
结构体类型的子元素数量。
duckdb_struct_type_child_name
检索结构体子项的名称。
The result must be freed with duckdb_free
.
Syntax
char *duckdb_struct_type_child_name(
duckdb_logical_type type,
idx_t index
);
Parameters
type
: The logical type objectindex
: The child index
Return Value
结构体类型的名称。必须使用duckdb_free
释放。
duckdb_struct_type_child_type
检索给定结构类型在指定索引处的子类型。
The result must be freed with duckdb_destroy_logical_type
.
Syntax
duckdb_logical_type duckdb_struct_type_child_type(
duckdb_logical_type type,
idx_t index
);
Parameters
type
: The logical type objectindex
: The child index
Return Value
结构类型的子类型。必须使用duckdb_destroy_logical_type
销毁。
duckdb_union_type_member_count
返回联合类型拥有的成员数量。
Syntax
idx_t duckdb_union_type_member_count(
duckdb_logical_type type
);
Parameters
type
: 逻辑类型(联合)对象
Return Value
联合类型的成员数量。
duckdb_union_type_member_name
检索联合成员的名称。
The result must be freed with duckdb_free
.
Syntax
char *duckdb_union_type_member_name(
duckdb_logical_type type,
idx_t index
);
Parameters
type
: The logical type objectindex
: The child index
Return Value
联合成员的名称。必须使用duckdb_free
释放。
duckdb_union_type_member_type
检索指定索引处给定联合成员的子类型。
The result must be freed with duckdb_destroy_logical_type
.
Syntax
duckdb_logical_type duckdb_union_type_member_type(
duckdb_logical_type type,
idx_t index
);
Parameters
type
: The logical type objectindex
: The child index
Return Value
联合成员的子类型。必须使用duckdb_destroy_logical_type
销毁。
duckdb_destroy_logical_type
销毁逻辑类型并释放为该类型分配的所有内存。
Syntax
void duckdb_destroy_logical_type(
duckdb_logical_type *type
);
Parameters
type
: 要销毁的逻辑类型。
duckdb_register_logical_type
在给定的连接中注册一个自定义类型。 该类型必须有一个别名
Syntax
duckdb_state duckdb_register_logical_type(
duckdb_connection con,
duckdb_logical_type type,
duckdb_create_type_info info
);
Parameters
con
: 使用的连接type
: 要注册的自定义类型
Return Value
注册是否成功。