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.

The supported types are listed below:

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;

The type of a column in the result can be obtained using the duckdb_column_type function. The internal type of the columns is especially relevant for correct usage of the duckdb_column_data function.

The mapping from column type to internal type is provided in the table below.

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_column_data

The duckdb_column_data returns a pointer to an internal array within the result. The type of the elements of the array depends on the internal type of the column, as obtained using duckdb_column_type. The corresponding null values can be obtained using the duckdb_nullmask_data function.

The exact data types can be seen in the table above. For numeric types, the internal types of the columns are standard built-in types. For example, for a column of type DUCKDB_TYPE_INTEGER the internal type is a int32_t. For text (varchar) columns, the internal type is a pointer to a null-terminated string.

For dates, times, timestamps, blobs, intervals and hugeints, the internal types are DuckDB-specific structs as defined below:

//! Days are stored as days since 1970-01-01
//! Use the duckdb_from_date/duckdb_to_date function to extract individual information
typedef struct {
	int32_t days;
} duckdb_date;

//! Time is stored as microseconds since 00:00:00
//! Use the duckdb_from_time/duckdb_to_time function to extract individual information
typedef struct {
	int64_t micros;
} duckdb_time;

//! Timestamps are stored as microseconds since 1970-01-01
//! Use the duckdb_from_timestamp/duckdb_to_timestamp function to extract individual information
typedef struct {
	int64_t micros;
} duckdb_timestamp;

typedef struct {
	int32_t months;
	int32_t days;
	int64_t micros;
} duckdb_interval;

//! Hugeints are composed in a (lower, upper) component
//! The value of the hugeint is upper * 2^64 + lower
//! For easy usage, the functions duckdb_hugeint_to_double/duckdb_double_to_hugeint are recommended
typedef struct {
	uint64_t lower;
	int64_t upper;
} duckdb_hugeint;

typedef struct {
	void *data;
	idx_t size;
} duckdb_blob;

For hugeints, dates, times and timestamps there are also several helper functions available in order to facilitate easier usage of these types. See the API reference below for the available functions.

// helper structs, as used by the Date/Time/Timestamp Helpers
typedef struct {
	int32_t year;
	int8_t month;
	int8_t day;
} duckdb_date_struct;

typedef struct {
	int8_t hour;
	int8_t min;
	int8_t sec;
	int32_t micros;
} duckdb_time_struct;

typedef struct {
	duckdb_date_struct date;
	duckdb_time_struct time;
} duckdb_timestamp_struct;

API Reference

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);
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_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_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_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

• returns

The char* value at the specified location, 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

• 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.