The value class represents a single value of any type.
API Reference Overview
void duckdb_destroy_value(duckdb_value *value);
duckdb_value duckdb_create_varchar(const char *text);
duckdb_value duckdb_create_varchar_length(const char *text, idx_t length);
duckdb_value duckdb_create_bool(bool input);
duckdb_value duckdb_create_int8(int8_t input);
duckdb_value duckdb_create_uint8(uint8_t input);
duckdb_value duckdb_create_int16(int16_t input);
duckdb_value duckdb_create_uint16(uint16_t input);
duckdb_value duckdb_create_int32(int32_t input);
duckdb_value duckdb_create_uint32(uint32_t input);
duckdb_value duckdb_create_uint64(uint64_t input);
duckdb_value duckdb_create_int64(int64_t val);
duckdb_value duckdb_create_hugeint(duckdb_hugeint input);
duckdb_value duckdb_create_uhugeint(duckdb_uhugeint input);
duckdb_value duckdb_create_float(float input);
duckdb_value duckdb_create_double(double input);
duckdb_value duckdb_create_date(duckdb_date input);
duckdb_value duckdb_create_time(duckdb_time input);
duckdb_value duckdb_create_time_tz_value(duckdb_time_tz value);
duckdb_value duckdb_create_timestamp(duckdb_timestamp input);
duckdb_value duckdb_create_interval(duckdb_interval input);
duckdb_value duckdb_create_blob(const uint8_t *data, idx_t length);
bool duckdb_get_bool(duckdb_value val);
int8_t duckdb_get_int8(duckdb_value val);
uint8_t duckdb_get_uint8(duckdb_value val);
int16_t duckdb_get_int16(duckdb_value val);
uint16_t duckdb_get_uint16(duckdb_value val);
int32_t duckdb_get_int32(duckdb_value val);
uint32_t duckdb_get_uint32(duckdb_value val);
int64_t duckdb_get_int64(duckdb_value val);
uint64_t duckdb_get_uint64(duckdb_value val);
duckdb_hugeint duckdb_get_hugeint(duckdb_value val);
duckdb_uhugeint duckdb_get_uhugeint(duckdb_value val);
float duckdb_get_float(duckdb_value val);
double duckdb_get_double(duckdb_value val);
duckdb_date duckdb_get_date(duckdb_value val);
duckdb_time duckdb_get_time(duckdb_value val);
duckdb_time_tz duckdb_get_time_tz(duckdb_value val);
duckdb_timestamp duckdb_get_timestamp(duckdb_value val);
duckdb_interval duckdb_get_interval(duckdb_value val);
duckdb_logical_type duckdb_get_value_type(duckdb_value val);
duckdb_blob duckdb_get_blob(duckdb_value val);
char *duckdb_get_varchar(duckdb_value value);
duckdb_value duckdb_create_struct_value(duckdb_logical_type type, duckdb_value *values);
duckdb_value duckdb_create_list_value(duckdb_logical_type type, duckdb_value *values, idx_t value_count);
duckdb_value duckdb_create_array_value(duckdb_logical_type type, duckdb_value *values, idx_t value_count);
idx_t duckdb_get_map_size(duckdb_value value);
duckdb_value duckdb_get_map_key(duckdb_value value, idx_t index);
duckdb_value duckdb_get_map_value(duckdb_value value, idx_t index);
duckdb_destroy_value
Destroys the value and de-allocates all memory allocated for that type.
Syntax
void duckdb_destroy_value(
duckdb_value *value
);
Parameters
value: The value to destroy.
duckdb_create_varchar
Creates a value from a null-terminated string
Syntax
duckdb_value duckdb_create_varchar(
const char *text
);
Parameters
text: The null-terminated string
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_varchar_length
Creates a value from a string
Syntax
duckdb_value duckdb_create_varchar_length(
const char *text,
idx_t length
);
Parameters
text: The textlength: The length of the text
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_bool
Creates a value from a boolean
Syntax
duckdb_value duckdb_create_bool(
bool input
);
Parameters
input: The boolean value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_int8
Creates a value from a int8_t (a tinyint)
Syntax
duckdb_value duckdb_create_int8(
int8_t input
);
Parameters
input: The tinyint value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_uint8
Creates a value from a uint8_t (a utinyint)
Syntax
duckdb_value duckdb_create_uint8(
uint8_t input
);
Parameters
input: The utinyint value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_int16
Creates a value from a int16_t (a smallint)
Syntax
duckdb_value duckdb_create_int16(
int16_t input
);
Parameters
input: The smallint value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_uint16
Creates a value from a uint16_t (a usmallint)
Syntax
duckdb_value duckdb_create_uint16(
uint16_t input
);
Parameters
input: The usmallint value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_int32
Creates a value from a int32_t (an integer)
Syntax
duckdb_value duckdb_create_int32(
int32_t input
);
Parameters
input: The integer value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_uint32
Creates a value from a uint32_t (a uinteger)
Syntax
duckdb_value duckdb_create_uint32(
uint32_t input
);
Parameters
input: The uinteger value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_uint64
Creates a value from a uint64_t (a ubigint)
Syntax
duckdb_value duckdb_create_uint64(
uint64_t input
);
Parameters
input: The ubigint value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_int64
Creates a value from an int64
Return Value
The value. This must be destroyed with duckdb_destroy_value.
Syntax
duckdb_value duckdb_create_int64(
int64_t val
);
duckdb_create_hugeint
Creates a value from a hugeint
Syntax
duckdb_value duckdb_create_hugeint(
duckdb_hugeint input
);
Parameters
input: The hugeint value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_uhugeint
Creates a value from a uhugeint
Syntax
duckdb_value duckdb_create_uhugeint(
duckdb_uhugeint input
);
Parameters
input: The uhugeint value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_float
Creates a value from a float
Syntax
duckdb_value duckdb_create_float(
float input
);
Parameters
input: The float value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_double
Creates a value from a double
Syntax
duckdb_value duckdb_create_double(
double input
);
Parameters
input: The double value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_date
Creates a value from a date
Syntax
duckdb_value duckdb_create_date(
duckdb_date input
);
Parameters
input: The date value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_time
Creates a value from a time
Syntax
duckdb_value duckdb_create_time(
duckdb_time input
);
Parameters
input: The time value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_time_tz_value
Creates a value from a time_tz.
Not to be confused with duckdb_create_time_tz, which creates a duckdb_time_tz_t.
Syntax
duckdb_value duckdb_create_time_tz_value(
duckdb_time_tz value
);
Parameters
value: The time_tz value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_timestamp
Creates a value from a timestamp
Syntax
duckdb_value duckdb_create_timestamp(
duckdb_timestamp input
);
Parameters
input: The timestamp value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_interval
Creates a value from an interval
Syntax
duckdb_value duckdb_create_interval(
duckdb_interval input
);
Parameters
input: The interval value
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_create_blob
Creates a value from a blob
Syntax
duckdb_value duckdb_create_blob(
const uint8_t *data,
idx_t length
);
Parameters
data: The blob datalength: The length of the blob data
Return Value
The value. This must be destroyed with duckdb_destroy_value.
duckdb_get_bool
Returns the boolean value of the given value.
Syntax
bool duckdb_get_bool(
duckdb_value val
);
Parameters
val: A duckdb_value containing a boolean
Return Value
A boolean, or false if the value cannot be converted
duckdb_get_int8
Returns the int8_t value of the given value.
Syntax
int8_t duckdb_get_int8(
duckdb_value val
);
Parameters
val: A duckdb_value containing a tinyint
Return Value
A int8_t, or MinValue
duckdb_get_uint8
Returns the uint8_t value of the given value.
Syntax
uint8_t duckdb_get_uint8(
duckdb_value val
);
Parameters
val: A duckdb_value containing a utinyint
Return Value
A uint8_t, or MinValue
duckdb_get_int16
Returns the int16_t value of the given value.
Syntax
int16_t duckdb_get_int16(
duckdb_value val
);
Parameters
val: A duckdb_value containing a smallint
Return Value
A int16_t, or MinValue
duckdb_get_uint16
Returns the uint16_t value of the given value.
Syntax
uint16_t duckdb_get_uint16(
duckdb_value val
);
Parameters
val: A duckdb_value containing a usmallint
Return Value
A uint16_t, or MinValue
duckdb_get_int32
Returns the int32_t value of the given value.
Syntax
int32_t duckdb_get_int32(
duckdb_value val
);
Parameters
val: A duckdb_value containing a integer
Return Value
A int32_t, or MinValue
duckdb_get_uint32
Returns the uint32_t value of the given value.
Syntax
uint32_t duckdb_get_uint32(
duckdb_value val
);
Parameters
val: A duckdb_value containing a uinteger
Return Value
A uint32_t, or MinValue
duckdb_get_int64
Returns the int64_t value of the given value.
Syntax
int64_t duckdb_get_int64(
duckdb_value val
);
Parameters
val: A duckdb_value containing a bigint
Return Value
A int64_t, or MinValue
duckdb_get_uint64
Returns the uint64_t value of the given value.
Syntax
uint64_t duckdb_get_uint64(
duckdb_value val
);
Parameters
val: A duckdb_value containing a ubigint
Return Value
A uint64_t, or MinValue
duckdb_get_hugeint
Returns the hugeint value of the given value.
Syntax
duckdb_hugeint duckdb_get_hugeint(
duckdb_value val
);
Parameters
val: A duckdb_value containing a hugeint
Return Value
A duckdb_hugeint, or MinValue
duckdb_get_uhugeint
Returns the uhugeint value of the given value.
Syntax
duckdb_uhugeint duckdb_get_uhugeint(
duckdb_value val
);
Parameters
val: A duckdb_value containing a uhugeint
Return Value
A duckdb_uhugeint, or MinValue
duckdb_get_float
Returns the float value of the given value.
Syntax
float duckdb_get_float(
duckdb_value val
);
Parameters
val: A duckdb_value containing a float
Return Value
A float, or NAN if the value cannot be converted
duckdb_get_double
Returns the double value of the given value.
Syntax
double duckdb_get_double(
duckdb_value val
);
Parameters
val: A duckdb_value containing a double
Return Value
A double, or NAN if the value cannot be converted
duckdb_get_date
Returns the date value of the given value.
Syntax
duckdb_date duckdb_get_date(
duckdb_value val
);
Parameters
val: A duckdb_value containing a date
Return Value
A duckdb_date, or MinValue
duckdb_get_time
Returns the time value of the given value.
Syntax
duckdb_time duckdb_get_time(
duckdb_value val
);
Parameters
val: A duckdb_value containing a time
Return Value
A duckdb_time, or MinValue
duckdb_get_time_tz
Returns the time_tz value of the given value.
Syntax
duckdb_time_tz duckdb_get_time_tz(
duckdb_value val
);
Parameters
val: A duckdb_value containing a time_tz
Return Value
A duckdb_time_tz, or MinValue
duckdb_get_timestamp
Returns the timestamp value of the given value.
Syntax
duckdb_timestamp duckdb_get_timestamp(
duckdb_value val
);
Parameters
val: A duckdb_value containing a timestamp
Return Value
A duckdb_timestamp, or MinValue
duckdb_get_interval
Returns the interval value of the given value.
Syntax
duckdb_interval duckdb_get_interval(
duckdb_value val
);
Parameters
val: A duckdb_value containing a interval
Return Value
A duckdb_interval, or MinValue
duckdb_get_value_type
Returns the type of the given value. The type is valid as long as the value is not destroyed. The type itself must not be destroyed.
Syntax
duckdb_logical_type duckdb_get_value_type(
duckdb_value val
);
Parameters
val: A duckdb_value
Return Value
A duckdb_logical_type.
duckdb_get_blob
Returns the blob value of the given value.
Syntax
duckdb_blob duckdb_get_blob(
duckdb_value val
);
Parameters
val: A duckdb_value containing a blob
Return Value
A duckdb_blob
duckdb_get_varchar
Obtains a string representation of the given value.
The result must be destroyed with duckdb_free.
Syntax
char *duckdb_get_varchar(
duckdb_value value
);
Parameters
value: The value
Return Value
The string value. This must be destroyed with duckdb_free.
duckdb_create_struct_value
Creates a struct value from a type and an array of values. Must be destroyed with duckdb_destroy_value.
Syntax
duckdb_value duckdb_create_struct_value(
duckdb_logical_type type,
duckdb_value *values
);
Parameters
type: The type of the structvalues: The values for the struct fields
Return Value
The struct value, or nullptr, if any child type is DUCKDB_TYPE_ANY or DUCKDB_TYPE_INVALID.
duckdb_create_list_value
Creates a list value from a child (element) type and an array of values of length value_count.
Must be destroyed with duckdb_destroy_value.
Syntax
duckdb_value duckdb_create_list_value(
duckdb_logical_type type,
duckdb_value *values,
idx_t value_count
);
Parameters
type: The type of the listvalues: The values for the listvalue_count: The number of values in the list
Return Value
The list value, or nullptr, if the child type is DUCKDB_TYPE_ANY or DUCKDB_TYPE_INVALID.
duckdb_create_array_value
Creates an array value from a child (element) type and an array of values of length value_count.
Must be destroyed with duckdb_destroy_value.
Syntax
duckdb_value duckdb_create_array_value(
duckdb_logical_type type,
duckdb_value *values,
idx_t value_count
);
Parameters
type: The type of the arrayvalues: The values for the arrayvalue_count: The number of values in the array
Return Value
The array value, or nullptr, if the child type is DUCKDB_TYPE_ANY or DUCKDB_TYPE_INVALID.
duckdb_get_map_size
Returns the number of elements in a MAP value.
Syntax
idx_t duckdb_get_map_size(
duckdb_value value
);
Parameters
value: The MAP value.
Return Value
The number of elements in the map.
duckdb_get_map_key
Returns the MAP key at index as a duckdb_value.
Syntax
duckdb_value duckdb_get_map_key(
duckdb_value value,
idx_t index
);
Parameters
value: The MAP value.index: The index of the key.
Return Value
The key as a duckdb_value.
duckdb_get_map_value
Returns the MAP value at index as a duckdb_value.
Syntax
duckdb_value duckdb_get_map_value(
duckdb_value value,
idx_t index
);
Parameters
value: The MAP value.index: The index of the value.
Return Value
The value as a duckdb_value.