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.
© 2025 DuckDB Foundation, Amsterdam NL