Search Shortcut cmd + k | ctrl + k
Search cmd+k ctrl+k
Dark Mode
1.1 (stable)
Values

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 text
  • length: 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 data
  • length: 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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 if the value cannot be converted


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 struct
  • values: 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 list
  • values: The values for the list
  • value_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 array
  • values: The values for the array
  • value_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.