C API - Types
Version current

DuckDB is a strongly typed database system. As such, every column has a single type specified. This type is constant over the entire column. That is to say, a column that is labeled as an INTEGER column will only contain INTEGER values.

DuckDB also supports columns of composite types. For example, it is possible to define an array of integers (INT[]). It is also possible to define types as arbitrary structs (ROW(i INTEGER, j VARCHAR)). For that reason, native DuckDB type objects are not mere enums, but a class that can potentially be nested.

Types in the C API are modeled using an enum (duckdb_type) and a complex class (duckdb_logical_type). For most primitive types, e.g. integers or varchars, the enum is sufficient. For more complex types, such as lists, structs or decimals, the logical type must be used.

typedef enum DUCKDB_TYPE {
  DUCKDB_TYPE_INVALID,
  DUCKDB_TYPE_BOOLEAN,
  DUCKDB_TYPE_TINYINT,
  DUCKDB_TYPE_SMALLINT,
  DUCKDB_TYPE_INTEGER,
  DUCKDB_TYPE_BIGINT,
  DUCKDB_TYPE_UTINYINT,
  DUCKDB_TYPE_USMALLINT,
  DUCKDB_TYPE_UINTEGER,
  DUCKDB_TYPE_UBIGINT,
  DUCKDB_TYPE_FLOAT,
  DUCKDB_TYPE_DOUBLE,
  DUCKDB_TYPE_TIMESTAMP,
  DUCKDB_TYPE_DATE,
  DUCKDB_TYPE_TIME,
  DUCKDB_TYPE_INTERVAL,
  DUCKDB_TYPE_HUGEINT,
  DUCKDB_TYPE_VARCHAR,
  DUCKDB_TYPE_BLOB,
  DUCKDB_TYPE_DECIMAL,
  DUCKDB_TYPE_TIMESTAMP_S,
  DUCKDB_TYPE_TIMESTAMP_MS,
  DUCKDB_TYPE_TIMESTAMP_NS,
  DUCKDB_TYPE_ENUM,
  DUCKDB_TYPE_LIST,
  DUCKDB_TYPE_STRUCT,
  DUCKDB_TYPE_MAP,
  DUCKDB_TYPE_UUID,
  DUCKDB_TYPE_JSON
} duckdb_type;

The enum type of a column in the result can be obtained using the duckdb_column_type function. The logical type of a column can be obtained using the duckdb_column_logical_type function.

duckdb_value

The duckdb_value functions will auto-cast values as required. For example, it is no problem to use duckdb_value_double on a column of type duckdb_value_int32. The value will be auto-cast and returned as a double. Note that in certain cases the cast may fail. For example, this can happen if we request a duckdb_value_int8 and the value does not fit within an int8 value. In this case, a default value will be returned (usually 0 or nullptr). The same default value will also be returned if the corresponding value is NULL.

The duckdb_value_is_null function can be used to check if a specific value is NULL or not.

The exception to the auto-cast rule is the duckdb_value_varchar_internal function. This function does not auto-cast and only works for VARCHAR columns. The reason this function exists is that the result does not need to be freed.

Note that duckdb_value_varchar and duckdb_value_blob require the result to be de-allocated using duckdb_free.

duckdb_result_get_chunk

The duckdb_result_get_chunk function can be used to read data chunks from a DuckDB result set, and is the most efficient way of reading data from a DuckDB result using the C API. It is also the only way of reading data of certain types from a DuckDB result. For example, the duckdb_value functions do not support structural reading of composite types (lists or structs) or more complex types like enums and decimals.

For more information about data chunks, see the documentation on data chunks.

API Reference

duckdb_data_chunk duckdb_result_get_chunk(duckdb_result result, idx_t chunk_index);
idx_t duckdb_result_chunk_count(duckdb_result result);
bool duckdb_value_boolean(duckdb_result *result, idx_t col, idx_t row);
int8_t duckdb_value_int8(duckdb_result *result, idx_t col, idx_t row);
int16_t duckdb_value_int16(duckdb_result *result, idx_t col, idx_t row);
int32_t duckdb_value_int32(duckdb_result *result, idx_t col, idx_t row);
int64_t duckdb_value_int64(duckdb_result *result, idx_t col, idx_t row);
duckdb_hugeint duckdb_value_hugeint(duckdb_result *result, idx_t col, idx_t row);
duckdb_decimal duckdb_value_decimal(duckdb_result *result, idx_t col, idx_t row);
uint8_t duckdb_value_uint8(duckdb_result *result, idx_t col, idx_t row);
uint16_t duckdb_value_uint16(duckdb_result *result, idx_t col, idx_t row);
uint32_t duckdb_value_uint32(duckdb_result *result, idx_t col, idx_t row);
uint64_t duckdb_value_uint64(duckdb_result *result, idx_t col, idx_t row);
float duckdb_value_float(duckdb_result *result, idx_t col, idx_t row);
double duckdb_value_double(duckdb_result *result, idx_t col, idx_t row);
duckdb_date duckdb_value_date(duckdb_result *result, idx_t col, idx_t row);
duckdb_time duckdb_value_time(duckdb_result *result, idx_t col, idx_t row);
duckdb_timestamp duckdb_value_timestamp(duckdb_result *result, idx_t col, idx_t row);
duckdb_interval duckdb_value_interval(duckdb_result *result, idx_t col, idx_t row);
char *duckdb_value_varchar(duckdb_result *result, idx_t col, idx_t row);
char *duckdb_value_varchar_internal(duckdb_result *result, idx_t col, idx_t row);
duckdb_string duckdb_value_string_internal(duckdb_result *result, idx_t col, idx_t row);
duckdb_blob duckdb_value_blob(duckdb_result *result, idx_t col, idx_t row);
bool duckdb_value_is_null(duckdb_result *result, idx_t col, idx_t row);

Date/Time/Timestamp Helpers

duckdb_date_struct duckdb_from_date(duckdb_date date);
duckdb_date duckdb_to_date(duckdb_date_struct date);
duckdb_time_struct duckdb_from_time(duckdb_time time);
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);

Hugeint Helpers

double duckdb_hugeint_to_double(duckdb_hugeint val);
duckdb_hugeint duckdb_double_to_hugeint(double val);
duckdb_decimal duckdb_double_to_decimal(double val, uint8_t width, uint8_t scale);

Decimal Helpers

double duckdb_decimal_to_double(duckdb_decimal val);

Logical Type Interface

duckdb_logical_type duckdb_create_logical_type(duckdb_type type);
duckdb_logical_type duckdb_create_list_type(duckdb_logical_type type);
duckdb_logical_type duckdb_create_map_type(duckdb_logical_type key_type, duckdb_logical_type value_type);
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_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);
void duckdb_destroy_logical_type(duckdb_logical_type *type);

duckdb_result_get_chunk


Fetches a data chunk from the duckdb_result. This function should be called repeatedly until the result is exhausted.

The result must be destroyed with duckdb_destroy_data_chunk.

This function supersedes all duckdb_value functions, as well as the duckdb_column_data and duckdb_nullmask_data functions. It results in significantly better performance, and should be preferred in newer code-bases.

If this function is used, none of the other result functions can be used and vice versa (i.e. this function cannot be mixed with the legacy result functions).

Use duckdb_result_chunk_count to figure out how many chunks there are in the result.

Syntax


duckdb_data_chunk duckdb_result_get_chunk(
  duckdb_result result,
  idx_t chunk_index
);

Parameters


  • result

The result object to fetch the data chunk from.

  • chunk_index

The chunk index to fetch from.

  • returns

The resulting data chunk. Returns NULL if the chunk index is out of bounds.


duckdb_result_chunk_count


Returns the number of data chunks present in the result.

Syntax


idx_t duckdb_result_chunk_count(
  duckdb_result result
);

Parameters


  • result

The result object

  • returns

The resulting data chunk. Returns NULL if the chunk index is out of bounds.


duckdb_value_boolean


Syntax


bool duckdb_value_boolean(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The boolean value at the specified location, or false if the value cannot be converted.


duckdb_value_int8


Syntax


int8_t duckdb_value_int8(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The int8_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_int16


Syntax


int16_t duckdb_value_int16(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The int16_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_int32


Syntax


int32_t duckdb_value_int32(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The int32_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_int64


Syntax


int64_t duckdb_value_int64(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The int64_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_hugeint


Syntax


duckdb_hugeint duckdb_value_hugeint(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The duckdb_hugeint value at the specified location, or 0 if the value cannot be converted.


duckdb_value_decimal


Syntax


duckdb_decimal duckdb_value_decimal(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The duckdb_decimal value at the specified location, or 0 if the value cannot be converted.


duckdb_value_uint8


Syntax


uint8_t duckdb_value_uint8(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The uint8_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_uint16


Syntax


uint16_t duckdb_value_uint16(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The uint16_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_uint32


Syntax


uint32_t duckdb_value_uint32(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The uint32_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_uint64


Syntax


uint64_t duckdb_value_uint64(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The uint64_t value at the specified location, or 0 if the value cannot be converted.


duckdb_value_float


Syntax


float duckdb_value_float(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The float value at the specified location, or 0 if the value cannot be converted.


duckdb_value_double


Syntax


double duckdb_value_double(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The double value at the specified location, or 0 if the value cannot be converted.


duckdb_value_date


Syntax


duckdb_date duckdb_value_date(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The duckdb_date value at the specified location, or 0 if the value cannot be converted.


duckdb_value_time


Syntax


duckdb_time duckdb_value_time(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The duckdb_time value at the specified location, or 0 if the value cannot be converted.


duckdb_value_timestamp


Syntax


duckdb_timestamp duckdb_value_timestamp(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The duckdb_timestamp value at the specified location, or 0 if the value cannot be converted.


duckdb_value_interval


Syntax


duckdb_interval duckdb_value_interval(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The duckdb_interval value at the specified location, or 0 if the value cannot be converted.


duckdb_value_varchar


Syntax


char *duckdb_value_varchar(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • DEPRECATED

use duckdb_value_string instead. This function does not work correctly if the string contains null bytes.

  • returns

The text value at the specified location as a null-terminated string, or nullptr if the value cannot be converted. The result must be freed with duckdb_free.


duckdb_value_varchar_internal


Syntax


char *duckdb_value_varchar_internal(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • DEPRECATED

use duckdb_value_string_internal instead. This function does not work correctly if the string contains null bytes.

  • returns

The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast. If the column is NOT a VARCHAR column this function will return NULL.

The result must NOT be freed.


duckdb_value_string_internal


Syntax


duckdb_string duckdb_value_string_internal(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • DEPRECATED

use duckdb_value_string_internal instead. This function does not work correctly if the string contains null bytes.

  • returns

The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast. If the column is NOT a VARCHAR column this function will return NULL.

The result must NOT be freed.


duckdb_value_blob


Syntax


duckdb_blob duckdb_value_blob(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

The duckdb_blob value at the specified location. Returns a blob with blob.data set to nullptr if the value cannot be converted. The resulting “blob.data” must be freed with duckdb_free.


duckdb_value_is_null


Syntax


bool duckdb_value_is_null(
  duckdb_result *result,
  idx_t col,
  idx_t row
);

Parameters


  • returns

Returns true if the value at the specified index is NULL, and false otherwise.


duckdb_from_date


Decompose a duckdb_date object into year, month and date (stored as duckdb_date_struct).

Syntax


duckdb_date_struct duckdb_from_date(
  duckdb_date date
);

Parameters


  • date

The date object, as obtained from a DUCKDB_TYPE_DATE column.

  • returns

The duckdb_date_struct with the decomposed elements.


duckdb_to_date


Re-compose a duckdb_date from year, month and date (duckdb_date_struct).

Syntax


duckdb_date duckdb_to_date(
  duckdb_date_struct date
);

Parameters


  • date

The year, month and date stored in a duckdb_date_struct.

  • returns

The duckdb_date element.


duckdb_from_time


Decompose a duckdb_time object into hour, minute, second and microsecond (stored as duckdb_time_struct).

Syntax


duckdb_time_struct duckdb_from_time(
  duckdb_time time
);

Parameters


  • time

The time object, as obtained from a DUCKDB_TYPE_TIME column.

  • returns

The duckdb_time_struct with the decomposed elements.


duckdb_to_time


Re-compose a duckdb_time from hour, minute, second and microsecond (duckdb_time_struct).

Syntax


duckdb_time duckdb_to_time(
  duckdb_time_struct time
);

Parameters


  • time

The hour, minute, second and microsecond in a duckdb_time_struct.

  • returns

The duckdb_time element.


duckdb_from_timestamp


Decompose a duckdb_timestamp object into a duckdb_timestamp_struct.

Syntax


duckdb_timestamp_struct duckdb_from_timestamp(
  duckdb_timestamp ts
);

Parameters


  • ts

The ts object, as obtained from a DUCKDB_TYPE_TIMESTAMP column.

  • returns

The duckdb_timestamp_struct with the decomposed elements.


duckdb_to_timestamp


Re-compose a duckdb_timestamp from a duckdb_timestamp_struct.

Syntax


duckdb_timestamp duckdb_to_timestamp(
  duckdb_timestamp_struct ts
);

Parameters


  • ts

The de-composed elements in a duckdb_timestamp_struct.

  • returns

The duckdb_timestamp element.


duckdb_hugeint_to_double


Converts a duckdb_hugeint object (as obtained from a DUCKDB_TYPE_HUGEINT column) into a double.

Syntax


double duckdb_hugeint_to_double(
  duckdb_hugeint val
);

Parameters


  • val

The hugeint value.

  • returns

The converted double element.


duckdb_double_to_hugeint


Converts a double value to a duckdb_hugeint object.

If the conversion fails because the double value is too big the result will be 0.

Syntax


duckdb_hugeint duckdb_double_to_hugeint(
  double val
);

Parameters


  • val

The double value.

  • returns

The converted duckdb_hugeint element.


duckdb_double_to_decimal


Converts a double value to a duckdb_decimal object.

If the conversion fails because the double value is too big, or the width/scale are invalid the result will be 0.

Syntax


duckdb_decimal duckdb_double_to_decimal(
  double val,
  uint8_t width,
  uint8_t scale
);

Parameters


  • val

The double value.

  • returns

The converted duckdb_decimal element.


duckdb_decimal_to_double


Converts a duckdb_decimal object (as obtained from a DUCKDB_TYPE_DECIMAL column) into a double.

Syntax


double duckdb_decimal_to_double(
  duckdb_decimal val
);

Parameters


  • val

The decimal value.

  • returns

The converted double element.


duckdb_create_logical_type


Creates a duckdb_logical_type from a standard primitive type. The resulting type should be destroyed with duckdb_destroy_logical_type.

This should not be used with DUCKDB_TYPE_DECIMAL.

Syntax


duckdb_logical_type duckdb_create_logical_type(
  duckdb_type type
);

Parameters


  • type

The primitive type to create.

  • returns

The logical type.


duckdb_create_list_type


Creates a list type from its child type. The resulting type should be destroyed with duckdb_destroy_logical_type.

Syntax


duckdb_logical_type duckdb_create_list_type(
  duckdb_logical_type type
);

Parameters


  • type

The child type of list type to create.

  • returns

The logical type.


duckdb_create_map_type


Creates a map type from its key type and value type. The resulting type should be destroyed with duckdb_destroy_logical_type.

Syntax


duckdb_logical_type duckdb_create_map_type(
  duckdb_logical_type key_type,
  duckdb_logical_type value_type
);

Parameters


  • type

The key type and value type of map type to create.

  • returns

The logical type.


duckdb_create_decimal_type


Creates a duckdb_logical_type of type decimal with the specified width and scale The resulting type should be destroyed with duckdb_destroy_logical_type.

Syntax


duckdb_logical_type duckdb_create_decimal_type(
  uint8_t width,
  uint8_t scale
);

Parameters


  • width

The width of the decimal type

  • scale

The scale of the decimal type

  • returns

The logical type.


duckdb_get_type_id


Retrieves the type class of a duckdb_logical_type.

Syntax


duckdb_type duckdb_get_type_id(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The type id


duckdb_decimal_width


Retrieves the width of a decimal type.

Syntax


uint8_t duckdb_decimal_width(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The width of the decimal type


duckdb_decimal_scale


Retrieves the scale of a decimal type.

Syntax


uint8_t duckdb_decimal_scale(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The scale of the decimal type


duckdb_decimal_internal_type


Retrieves the internal storage type of a decimal type.

Syntax


duckdb_type duckdb_decimal_internal_type(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The internal type of the decimal type


duckdb_enum_internal_type


Retrieves the internal storage type of an enum type.

Syntax


duckdb_type duckdb_enum_internal_type(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The internal type of the enum type


duckdb_enum_dictionary_size


Retrieves the dictionary size of the enum type

Syntax


uint32_t duckdb_enum_dictionary_size(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The dictionary size of the enum type


duckdb_enum_dictionary_value


Retrieves the dictionary value at the specified position from the enum.

The result must be freed with duckdb_free

Syntax


char *duckdb_enum_dictionary_value(
  duckdb_logical_type type,
  idx_t index
);

Parameters


  • type

The logical type object

  • index

The index in the dictionary

  • returns

The string value of the enum type. Must be freed with duckdb_free.


duckdb_list_type_child_type


Retrieves the child type of the given list type.

The result must be freed with duckdb_destroy_logical_type

Syntax


duckdb_logical_type duckdb_list_type_child_type(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The child type of the list type. Must be destroyed with duckdb_destroy_logical_type.


duckdb_map_type_key_type


Retrieves the key type of the given map type.

The result must be freed with duckdb_destroy_logical_type

Syntax


duckdb_logical_type duckdb_map_type_key_type(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The key type of the map type. Must be destroyed with duckdb_destroy_logical_type.


duckdb_map_type_value_type


Retrieves the value type of the given map 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

  • returns

The value type of the map type. Must be destroyed with duckdb_destroy_logical_type.


duckdb_struct_type_child_count


Returns the number of children of a struct type.

Syntax


idx_t duckdb_struct_type_child_count(
  duckdb_logical_type type
);

Parameters


  • type

The logical type object

  • returns

The number of children of a struct type.


duckdb_struct_type_child_name


Retrieves the name of the struct child.

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 object

  • index

The child index

  • returns

The name of the struct type. Must be freed with duckdb_free.


duckdb_struct_type_child_type


Retrieves the child type of the given struct type at the specified index.

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 object

  • index

The child index

  • returns

The child type of the struct type. Must be destroyed with duckdb_destroy_logical_type.


duckdb_destroy_logical_type


Destroys the logical type and de-allocates all memory allocated for that type.

Syntax


void duckdb_destroy_logical_type(
  duckdb_logical_type *type
);

Parameters


  • type

The logical type to destroy.


Search Shortcut cmd + k | ctrl + k