C API - Complete API
Version current

API Reference

Open/Connect

duckdb_state duckdb_open(const char *path, duckdb_database *out_database);
duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config, char **out_error);
void duckdb_close(duckdb_database *database);
duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection);
void duckdb_disconnect(duckdb_connection *connection);

Configuration

duckdb_state duckdb_create_config(duckdb_config *out_config);
size_t duckdb_config_count();
duckdb_state duckdb_get_config_flag(size_t index, const char **out_name, const char **out_description);
duckdb_state duckdb_set_config(duckdb_config config, const char *name, const char *option);
void duckdb_destroy_config(duckdb_config *config);

Query Execution

duckdb_state duckdb_query(duckdb_connection connection, const char *query, duckdb_result *out_result);
void duckdb_destroy_result(duckdb_result *result);
const char *duckdb_column_name(duckdb_result *result, idx_t col);
duckdb_type duckdb_column_type(duckdb_result *result, idx_t col);
duckdb_logical_type duckdb_column_logical_type(duckdb_result *result, idx_t col);
idx_t duckdb_column_count(duckdb_result *result);
idx_t duckdb_row_count(duckdb_result *result);
idx_t duckdb_rows_changed(duckdb_result *result);
void *duckdb_column_data(duckdb_result *result, idx_t col);
bool *duckdb_nullmask_data(duckdb_result *result, idx_t col);
const char *duckdb_result_error(duckdb_result *result);

Result Functions

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

Helpers

void *duckdb_malloc(size_t size);
void duckdb_free(void *ptr);
idx_t duckdb_vector_size();

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

Decimal Helpers

double duckdb_decimal_to_double(duckdb_decimal val);

Prepared Statements

duckdb_state duckdb_prepare(duckdb_connection connection, const char *query, duckdb_prepared_statement *out_prepared_statement);
void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement);
const char *duckdb_prepare_error(duckdb_prepared_statement prepared_statement);
idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement);
duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx);
duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val);
duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val);
duckdb_state duckdb_bind_int16(duckdb_prepared_statement prepared_statement, idx_t param_idx, int16_t val);
duckdb_state duckdb_bind_int32(duckdb_prepared_statement prepared_statement, idx_t param_idx, int32_t val);
duckdb_state duckdb_bind_int64(duckdb_prepared_statement prepared_statement, idx_t param_idx, int64_t val);
duckdb_state duckdb_bind_hugeint(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_hugeint val);
duckdb_state duckdb_bind_uint8(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint8_t val);
duckdb_state duckdb_bind_uint16(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint16_t val);
duckdb_state duckdb_bind_uint32(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint32_t val);
duckdb_state duckdb_bind_uint64(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint64_t val);
duckdb_state duckdb_bind_float(duckdb_prepared_statement prepared_statement, idx_t param_idx, float val);
duckdb_state duckdb_bind_double(duckdb_prepared_statement prepared_statement, idx_t param_idx, double val);
duckdb_state duckdb_bind_date(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_date val);
duckdb_state duckdb_bind_time(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_time val);
duckdb_state duckdb_bind_timestamp(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_timestamp val);
duckdb_state duckdb_bind_interval(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_interval val);
duckdb_state duckdb_bind_varchar(duckdb_prepared_statement prepared_statement, idx_t param_idx, const char *val);
duckdb_state duckdb_bind_varchar_length(duckdb_prepared_statement prepared_statement, idx_t param_idx, const char *val, idx_t length);
duckdb_state duckdb_bind_blob(duckdb_prepared_statement prepared_statement, idx_t param_idx, const void *data, idx_t length);
duckdb_state duckdb_bind_null(duckdb_prepared_statement prepared_statement, idx_t param_idx);
duckdb_state duckdb_execute_prepared(duckdb_prepared_statement prepared_statement, duckdb_result *out_result);
duckdb_state duckdb_execute_prepared_arrow(duckdb_prepared_statement prepared_statement, duckdb_arrow *out_result);

Value Interface

void duckdb_destroy_value(duckdb_value *value);
duckdb_value duckdb_create_varchar(const char *text);
duckdb_value duckdb_create_int64(int64_t val);
char *duckdb_get_varchar(duckdb_value value);
int64_t duckdb_get_int64(duckdb_value value);

Logical Type Interface

duckdb_logical_type duckdb_create_logical_type(duckdb_type type);
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);
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);

Data Chunk Interface

duckdb_data_chunk duckdb_create_data_chunk(duckdb_logical_type *types, idx_t column_count);
void duckdb_destroy_data_chunk(duckdb_data_chunk *chunk);
void duckdb_data_chunk_reset(duckdb_data_chunk chunk);
idx_t duckdb_data_chunk_get_column_count(duckdb_data_chunk chunk);
duckdb_vector duckdb_data_chunk_get_vector(duckdb_data_chunk chunk, idx_t col_idx);
idx_t duckdb_data_chunk_get_size(duckdb_data_chunk chunk);
void duckdb_data_chunk_set_size(duckdb_data_chunk chunk, idx_t size);

Vector Interface

duckdb_logical_type duckdb_vector_get_column_type(duckdb_vector vector);
void *duckdb_vector_get_data(duckdb_vector vector);
uint64_t *duckdb_vector_get_validity(duckdb_vector vector);
void duckdb_vector_ensure_validity_writable(duckdb_vector vector);
void duckdb_vector_assign_string_element(duckdb_vector vector, idx_t index, const char *str);
void duckdb_vector_assign_string_element_len(duckdb_vector vector, idx_t index, const char *str, idx_t str_len);
duckdb_vector duckdb_list_vector_get_child(duckdb_vector vector);
idx_t duckdb_list_vector_get_size(duckdb_vector vector);
duckdb_vector duckdb_struct_vector_get_child(duckdb_vector vector, idx_t index);

Validity Mask Functions

bool duckdb_validity_row_is_valid(uint64_t *validity, idx_t row);
void duckdb_validity_set_row_validity(uint64_t *validity, idx_t row, bool valid);
void duckdb_validity_set_row_invalid(uint64_t *validity, idx_t row);
void duckdb_validity_set_row_valid(uint64_t *validity, idx_t row);

Table Functions

duckdb_table_function duckdb_create_table_function();
void duckdb_destroy_table_function(duckdb_table_function *table_function);
void duckdb_table_function_set_name(duckdb_table_function table_function, const char *name);
void duckdb_table_function_add_parameter(duckdb_table_function table_function, duckdb_logical_type type);
void duckdb_table_function_set_extra_info(duckdb_table_function table_function, void *extra_info, duckdb_delete_callback_t destroy);
void duckdb_table_function_set_bind(duckdb_table_function table_function, duckdb_table_function_bind_t bind);
void duckdb_table_function_set_init(duckdb_table_function table_function, duckdb_table_function_init_t init);
void duckdb_table_function_set_function(duckdb_table_function table_function, duckdb_table_function_t function);
duckdb_state duckdb_register_table_function(duckdb_connection con, duckdb_table_function function);

Table Function Bind

void *duckdb_bind_get_extra_info(duckdb_bind_info info);
void duckdb_bind_add_result_column(duckdb_bind_info info, const char *name, duckdb_logical_type type);
idx_t duckdb_bind_get_parameter_count(duckdb_bind_info info);
duckdb_value duckdb_bind_get_parameter(duckdb_bind_info info, idx_t index);
void duckdb_bind_set_bind_data(duckdb_bind_info info, void *bind_data, duckdb_delete_callback_t destroy);
void duckdb_bind_set_error(duckdb_bind_info info, const char *error);

Table Function Init

void *duckdb_init_get_extra_info(duckdb_init_info info);
void *duckdb_init_get_bind_data(duckdb_init_info info);
void duckdb_init_set_init_data(duckdb_init_info info, void *init_data, duckdb_delete_callback_t destroy);
void duckdb_init_set_error(duckdb_init_info info, const char *error);

Table Function

void *duckdb_function_get_extra_info(duckdb_function_info info);
void *duckdb_function_get_bind_data(duckdb_function_info info);
void *duckdb_function_get_init_data(duckdb_function_info info);
void duckdb_function_set_error(duckdb_function_info info, const char *error);

Replacement Scans

void duckdb_add_replacement_scan(duckdb_database db, duckdb_replacement_callback_t replacement, void *extra_data, duckdb_delete_callback_t delete_callback);
void duckdb_replacement_scan_set_function_name(duckdb_replacement_scan_info info, const char *function_name);
void duckdb_replacement_scan_add_parameter(duckdb_replacement_scan_info info, duckdb_value parameter);

Appender

duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table, duckdb_appender *out_appender);
const char *duckdb_appender_error(duckdb_appender appender);
duckdb_state duckdb_appender_flush(duckdb_appender appender);
duckdb_state duckdb_appender_close(duckdb_appender appender);
duckdb_state duckdb_appender_destroy(duckdb_appender *appender);
duckdb_state duckdb_appender_begin_row(duckdb_appender appender);
duckdb_state duckdb_appender_end_row(duckdb_appender appender);
duckdb_state duckdb_append_bool(duckdb_appender appender, bool value);
duckdb_state duckdb_append_int8(duckdb_appender appender, int8_t value);
duckdb_state duckdb_append_int16(duckdb_appender appender, int16_t value);
duckdb_state duckdb_append_int32(duckdb_appender appender, int32_t value);
duckdb_state duckdb_append_int64(duckdb_appender appender, int64_t value);
duckdb_state duckdb_append_hugeint(duckdb_appender appender, duckdb_hugeint value);
duckdb_state duckdb_append_uint8(duckdb_appender appender, uint8_t value);
duckdb_state duckdb_append_uint16(duckdb_appender appender, uint16_t value);
duckdb_state duckdb_append_uint32(duckdb_appender appender, uint32_t value);
duckdb_state duckdb_append_uint64(duckdb_appender appender, uint64_t value);
duckdb_state duckdb_append_float(duckdb_appender appender, float value);
duckdb_state duckdb_append_double(duckdb_appender appender, double value);
duckdb_state duckdb_append_date(duckdb_appender appender, duckdb_date value);
duckdb_state duckdb_append_time(duckdb_appender appender, duckdb_time value);
duckdb_state duckdb_append_timestamp(duckdb_appender appender, duckdb_timestamp value);
duckdb_state duckdb_append_interval(duckdb_appender appender, duckdb_interval value);
duckdb_state duckdb_append_varchar(duckdb_appender appender, const char *val);
duckdb_state duckdb_append_varchar_length(duckdb_appender appender, const char *val, idx_t length);
duckdb_state duckdb_append_blob(duckdb_appender appender, const void *data, idx_t length);
duckdb_state duckdb_append_null(duckdb_appender appender);
duckdb_state duckdb_append_data_chunk(duckdb_appender appender, duckdb_data_chunk chunk);

Arrow Interface

duckdb_state duckdb_query_arrow(duckdb_connection connection, const char *query, duckdb_arrow *out_result);
duckdb_state duckdb_query_arrow_schema(duckdb_arrow result, duckdb_arrow_schema *out_schema);
duckdb_state duckdb_query_arrow_array(duckdb_arrow result, duckdb_arrow_array *out_array);
idx_t duckdb_arrow_column_count(duckdb_arrow result);
idx_t duckdb_arrow_row_count(duckdb_arrow result);
idx_t duckdb_arrow_rows_changed(duckdb_arrow result);
const char *duckdb_query_arrow_error(duckdb_arrow result);
void duckdb_destroy_arrow(duckdb_arrow *result);

duckdb_open


Creates a new database or opens an existing database file stored at the the given path. If no path is given a new in-memory database is created instead.

Syntax


duckdb_state duckdb_open(
  const char *path,
  duckdb_database *out_database
);

Parameters


  • path

Path to the database file on disk, or nullptr or :memory: to open an in-memory database.

  • out_database

The result database object.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_open_ext


Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the the given path.

Syntax


duckdb_state duckdb_open_ext(
  const char *path,
  duckdb_database *out_database,
  duckdb_config config,
  char **out_error
);

Parameters


  • path

Path to the database file on disk, or nullptr or :memory: to open an in-memory database.

  • out_database

The result database object.

  • config

(Optional) configuration used to start up the database system.

  • out_error

If set and the function returns DuckDBError, this will contain the reason why the start-up failed. Note that the error must be freed using duckdb_free.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_close


Closes the specified database and de-allocates all memory allocated for that database. This should be called after you are done with any database allocated through duckdb_open. Note that failing to call duckdb_close (in case of e.g. a program crash) will not cause data corruption. Still it is recommended to always correctly close a database object after you are done with it.

Syntax


void duckdb_close(
  duckdb_database *database
);

Parameters


  • database

The database object to shut down.


duckdb_connect


Opens a connection to a database. Connections are required to query the database, and store transactional state associated with the connection.

Syntax


duckdb_state duckdb_connect(
  duckdb_database database,
  duckdb_connection *out_connection
);

Parameters


  • database

The database file to connect to.

  • out_connection

The result connection object.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_disconnect


Closes the specified connection and de-allocates all memory allocated for that connection.

Syntax


void duckdb_disconnect(
  duckdb_connection *connection
);

Parameters


  • connection

The connection to close.


duckdb_create_config


Initializes an empty configuration object that can be used to provide start-up options for the DuckDB instance through duckdb_open_ext.

This will always succeed unless there is a malloc failure.

Syntax


duckdb_state duckdb_create_config(
  duckdb_config *out_config
);

Parameters


  • out_config

The result configuration object.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_config_count


This returns the total amount of configuration options available for usage with duckdb_get_config_flag.

This should not be called in a loop as it internally loops over all the options.

Syntax


size_t duckdb_config_count(
  
);

Parameters


  • returns

The amount of config options available.


duckdb_get_config_flag


Obtains a human-readable name and description of a specific configuration option. This can be used to e.g. display configuration options. This will succeed unless index is out of range (i.e. >= duckdb_config_count).

The result name or description MUST NOT be freed.

Syntax


duckdb_state duckdb_get_config_flag(
  size_t index,
  const char **out_name,
  const char **out_description
);

Parameters


  • index

The index of the configuration option (between 0 and duckdb_config_count)

  • out_name

A name of the configuration flag.

  • out_description

A description of the configuration flag.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_set_config


Sets the specified option for the specified configuration. The configuration option is indicated by name. To obtain a list of config options, see duckdb_get_config_flag.

In the source code, configuration options are defined in config.cpp.

This can fail if either the name is invalid, or if the value provided for the option is invalid.

Syntax


duckdb_state duckdb_set_config(
  duckdb_config config,
  const char *name,
  const char *option
);

Parameters


  • duckdb_config

The configuration object to set the option on.

  • name

The name of the configuration flag to set.

  • option

The value to set the configuration flag to.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_destroy_config


Destroys the specified configuration option and de-allocates all memory allocated for the object.

Syntax


void duckdb_destroy_config(
  duckdb_config *config
);

Parameters


  • config

The configuration object to destroy.


duckdb_query


Executes a SQL query within a connection and stores the full (materialized) result in the out_result pointer. If the query fails to execute, DuckDBError is returned and the error message can be retrieved by calling duckdb_result_error.

Note that after running duckdb_query, duckdb_destroy_result must be called on the result object even if the query fails, otherwise the error stored within the result will not be freed correctly.

Syntax


duckdb_state duckdb_query(
  duckdb_connection connection,
  const char *query,
  duckdb_result *out_result
);

Parameters


  • connection

The connection to perform the query in.

  • query

The SQL query to run.

  • out_result

The query result.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_destroy_result


Closes the result and de-allocates all memory allocated for that connection.

Syntax


void duckdb_destroy_result(
  duckdb_result *result
);

Parameters


  • result

The result to destroy.


duckdb_column_name


Returns the column name of the specified column. The result should not need be freed; the column names will automatically be destroyed when the result is destroyed.

Returns NULL if the column is out of range.

Syntax


const char *duckdb_column_name(
  duckdb_result *result,
  idx_t col
);

Parameters


  • result

The result object to fetch the column name from.

  • col

The column index.

  • returns

The column name of the specified column.


duckdb_column_type


Returns the column type of the specified column.

Returns DUCKDB_TYPE_INVALID if the column is out of range.

Syntax


duckdb_type duckdb_column_type(
  duckdb_result *result,
  idx_t col
);

Parameters


  • result

The result object to fetch the column type from.

  • col

The column index.

  • returns

The column type of the specified column.


duckdb_column_logical_type


Returns the logical column type of the specified column.

The return type of this call should be destroyed with duckdb_destroy_logical_type.

Returns NULL if the column is out of range.

Syntax


duckdb_logical_type duckdb_column_logical_type(
  duckdb_result *result,
  idx_t col
);

Parameters


  • result

The result object to fetch the column type from.

  • col

The column index.

  • returns

The logical column type of the specified column.


duckdb_column_count


Returns the number of columns present in a the result object.

Syntax


idx_t duckdb_column_count(
  duckdb_result *result
);

Parameters


  • result

The result object.

  • returns

The number of columns present in the result object.


duckdb_row_count


Returns the number of rows present in a the result object.

Syntax


idx_t duckdb_row_count(
  duckdb_result *result
);

Parameters


  • result

The result object.

  • returns

The number of rows present in the result object.


duckdb_rows_changed


Returns the number of rows changed by the query stored in the result. This is relevant only for INSERT/UPDATE/DELETE queries. For other queries the rows_changed will be 0.

Syntax


idx_t duckdb_rows_changed(
  duckdb_result *result
);

Parameters


  • result

The result object.

  • returns

The number of rows changed.


duckdb_column_data


DEPRECATED: Prefer using duckdb_result_get_chunk instead.

Returns the data of a specific column of a result in columnar format.

The function returns a dense array which contains the result data. The exact type stored in the array depends on the corresponding duckdb_type (as provided by duckdb_column_type). For the exact type by which the data should be accessed, see the comments in the types section or the DUCKDB_TYPE enum.

For example, for a column of type DUCKDB_TYPE_INTEGER, rows can be accessed in the following manner:

int32_t *data = (int32_t *) duckdb_column_data(&result, 0);
printf("Data for row %d: %d\n", row, data[row]);

Syntax


void *duckdb_column_data(
  duckdb_result *result,
  idx_t col
);

Parameters


  • result

The result object to fetch the column data from.

  • col

The column index.

  • returns

The column data of the specified column.


duckdb_nullmask_data


DEPRECATED: Prefer using duckdb_result_get_chunk instead.

Returns the nullmask of a specific column of a result in columnar format. The nullmask indicates for every row whether or not the corresponding row is NULL. If a row is NULL, the values present in the array provided by duckdb_column_data are undefined.

int32_t *data = (int32_t *) duckdb_column_data(&result, 0);
bool *nullmask = duckdb_nullmask_data(&result, 0);
if (nullmask[row]) {
printf("Data for row %d: NULL\n", row);
} else {
printf("Data for row %d: %d\n", row, data[row]);
}

Syntax


bool *duckdb_nullmask_data(
  duckdb_result *result,
  idx_t col
);

Parameters


  • result

The result object to fetch the nullmask from.

  • col

The column index.

  • returns

The nullmask of the specified column.


duckdb_result_error


Returns the error message contained within the result. The error is only set if duckdb_query returns DuckDBError.

The result of this function must not be freed. It will be cleaned up when duckdb_destroy_result is called.

Syntax


const char *duckdb_result_error(
  duckdb_result *result
);

Parameters


  • result

The result object to fetch the nullmask from.

  • returns

The error of the result.


duckdb_result_get_chunk


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

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


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


Allocate size bytes of memory using the duckdb internal malloc function. Any memory allocated in this manner should be freed using duckdb_free.

Syntax


void *duckdb_malloc(
  size_t size
);

Parameters


  • size

The number of bytes to allocate.

  • returns

A pointer to the allocated memory region.


duckdb_free


Free a value returned from duckdb_malloc, duckdb_value_varchar or duckdb_value_blob.

Syntax


void duckdb_free(
  void *ptr
);

Parameters


  • ptr

The memory region to de-allocate.


duckdb_vector_size


The internal vector size used by DuckDB. This is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk.

Syntax


idx_t duckdb_vector_size(
  
);

Parameters


  • returns

The vector size.


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_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_prepare


Create a prepared statement object from a query.

Note that after calling duckdb_prepare, the prepared statement should always be destroyed using duckdb_destroy_prepare, even if the prepare fails.

If the prepare fails, duckdb_prepare_error can be called to obtain the reason why the prepare failed.

Syntax


duckdb_state duckdb_prepare(
  duckdb_connection connection,
  const char *query,
  duckdb_prepared_statement *out_prepared_statement
);

Parameters


  • connection

The connection object

  • query

The SQL query to prepare

  • out_prepared_statement

The resulting prepared statement object

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_destroy_prepare


Closes the prepared statement and de-allocates all memory allocated for the statement.

Syntax


void duckdb_destroy_prepare(
  duckdb_prepared_statement *prepared_statement
);

Parameters


  • prepared_statement

The prepared statement to destroy.


duckdb_prepare_error


Returns the error message associated with the given prepared statement. If the prepared statement has no error message, this returns nullptr instead.

The error message should not be freed. It will be de-allocated when duckdb_destroy_prepare is called.

Syntax


const char *duckdb_prepare_error(
  duckdb_prepared_statement prepared_statement
);

Parameters


  • prepared_statement

The prepared statement to obtain the error from.

  • returns

The error message, or nullptr if there is none.


duckdb_nparams


Returns the number of parameters that can be provided to the given prepared statement.

Returns 0 if the query was not successfully prepared.

Syntax


idx_t duckdb_nparams(
  duckdb_prepared_statement prepared_statement
);

Parameters


  • prepared_statement

The prepared statement to obtain the number of parameters for.


duckdb_param_type


Returns the parameter type for the parameter at the given index.

Returns DUCKDB_TYPE_INVALID if the parameter index is out of range or the statement was not successfully prepared.

Syntax


duckdb_type duckdb_param_type(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx
);

Parameters


  • prepared_statement

The prepared statement.

  • param_idx

The parameter index.

  • returns

The parameter type


duckdb_bind_boolean


Binds a bool value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_boolean(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  bool val
);


duckdb_bind_int8


Binds an int8_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_int8(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  int8_t val
);


duckdb_bind_int16


Binds an int16_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_int16(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  int16_t val
);


duckdb_bind_int32


Binds an int32_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_int32(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  int32_t val
);


duckdb_bind_int64


Binds an int64_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_int64(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  int64_t val
);


duckdb_bind_hugeint


Binds an duckdb_hugeint value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_hugeint(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  duckdb_hugeint val
);


duckdb_bind_uint8


Binds an uint8_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_uint8(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  uint8_t val
);


duckdb_bind_uint16


Binds an uint16_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_uint16(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  uint16_t val
);


duckdb_bind_uint32


Binds an uint32_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_uint32(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  uint32_t val
);


duckdb_bind_uint64


Binds an uint64_t value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_uint64(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  uint64_t val
);


duckdb_bind_float


Binds an float value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_float(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  float val
);


duckdb_bind_double


Binds an double value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_double(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  double val
);


duckdb_bind_date


Binds a duckdb_date value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_date(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  duckdb_date val
);


duckdb_bind_time


Binds a duckdb_time value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_time(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  duckdb_time val
);


duckdb_bind_timestamp


Binds a duckdb_timestamp value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_timestamp(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  duckdb_timestamp val
);


duckdb_bind_interval


Binds a duckdb_interval value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_interval(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  duckdb_interval val
);


duckdb_bind_varchar


Binds a null-terminated varchar value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_varchar(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  const char *val
);


duckdb_bind_varchar_length


Binds a varchar value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_varchar_length(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  const char *val,
  idx_t length
);


duckdb_bind_blob


Binds a blob value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_blob(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx,
  const void *data,
  idx_t length
);


duckdb_bind_null


Binds a NULL value to the prepared statement at the specified index.

Syntax


duckdb_state duckdb_bind_null(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx
);


duckdb_execute_prepared


Executes the prepared statement with the given bound parameters, and returns a materialized query result.

This method can be called multiple times for each prepared statement, and the parameters can be modified between calls to this function.

Syntax


duckdb_state duckdb_execute_prepared(
  duckdb_prepared_statement prepared_statement,
  duckdb_result *out_result
);

Parameters


  • prepared_statement

The prepared statement to execute.

  • out_result

The query result.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_execute_prepared_arrow


Executes the prepared statement with the given bound parameters, and returns an arrow query result.

Syntax


duckdb_state duckdb_execute_prepared_arrow(
  duckdb_prepared_statement prepared_statement,
  duckdb_arrow *out_result
);

Parameters


  • prepared_statement

The prepared statement to execute.

  • out_result

The query result.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


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 varchar

Syntax


duckdb_value duckdb_create_varchar(
  const char *text
);

Parameters


  • value

The varchar value

  • returns

The value. This must be destroyed with duckdb_destroy_value.


duckdb_create_int64


Creates a value from an int64

Syntax


duckdb_value duckdb_create_int64(
  int64_t val
);

Parameters


  • value

The bigint value

  • returns

The value. This must be destroyed with duckdb_destroy_value.


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

  • returns

The string value. This must be destroyed with duckdb_free.


duckdb_get_int64


Obtains an int64 of the given value.

Syntax


int64_t duckdb_get_int64(
  duckdb_value value
);

Parameters


  • value

The value

  • returns

The int64 value, or 0 if no conversion is possible


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


duckdb_create_data_chunk


Creates an empty DataChunk with the specified set of types.

Syntax


duckdb_data_chunk duckdb_create_data_chunk(
  duckdb_logical_type *types,
  idx_t column_count
);

Parameters


  • types

An array of types of the data chunk.

  • column_count

The number of columns.

  • returns

The data chunk.


duckdb_destroy_data_chunk


Destroys the data chunk and de-allocates all memory allocated for that chunk.

Syntax


void duckdb_destroy_data_chunk(
  duckdb_data_chunk *chunk
);

Parameters


  • chunk

The data chunk to destroy.


duckdb_data_chunk_reset


Resets a data chunk, clearing the validity masks and setting the cardinality of the data chunk to 0.

Syntax


void duckdb_data_chunk_reset(
  duckdb_data_chunk chunk
);

Parameters


  • chunk

The data chunk to reset.


duckdb_data_chunk_get_column_count


Retrieves the number of columns in a data chunk.

Syntax


idx_t duckdb_data_chunk_get_column_count(
  duckdb_data_chunk chunk
);

Parameters


  • chunk

The data chunk to get the data from

  • returns

The number of columns in the data chunk


duckdb_data_chunk_get_vector


Retrieves the vector at the specified column index in the data chunk.

The pointer to the vector is valid for as long as the chunk is alive. It does NOT need to be destroyed.

Syntax


duckdb_vector duckdb_data_chunk_get_vector(
  duckdb_data_chunk chunk,
  idx_t col_idx
);

Parameters


  • chunk

The data chunk to get the data from

  • returns

The vector


duckdb_data_chunk_get_size


Retrieves the current number of tuples in a data chunk.

Syntax


idx_t duckdb_data_chunk_get_size(
  duckdb_data_chunk chunk
);

Parameters


  • chunk

The data chunk to get the data from

  • returns

The number of tuples in the data chunk


duckdb_data_chunk_set_size


Sets the current number of tuples in a data chunk.

Syntax


void duckdb_data_chunk_set_size(
  duckdb_data_chunk chunk,
  idx_t size
);

Parameters


  • chunk

The data chunk to set the size in

  • size

The number of tuples in the data chunk


duckdb_vector_get_column_type


Retrieves the column type of the specified vector.

The result must be destroyed with duckdb_destroy_logical_type.

Syntax


duckdb_logical_type duckdb_vector_get_column_type(
  duckdb_vector vector
);

Parameters


  • vector

The vector get the data from

  • returns

The type of the vector


duckdb_vector_get_data


Retrieves the data pointer of the vector.

The data pointer can be used to read or write values from the vector. How to read or write values depends on the type of the vector.

Syntax


void *duckdb_vector_get_data(
  duckdb_vector vector
);

Parameters


  • vector

The vector to get the data from

  • returns

The data pointer


duckdb_vector_get_validity


Retrieves the validity mask pointer of the specified vector.

If all values are valid, this function MIGHT return NULL!

The validity mask is a bitset that signifies null-ness within the data chunk. It is a series of uint64_t values, where each uint64_t value contains validity for 64 tuples. The bit is set to 1 if the value is valid (i.e. not NULL) or 0 if the value is invalid (i.e. NULL).

Validity of a specific value can be obtained like this:

idx_t entry_idx = row_idx / 64; idx_t idx_in_entry = row_idx % 64; bool is_valid = validity_mask[entry_idx] & (1 « idx_in_entry);

Alternatively, the (slower) duckdb_validity_row_is_valid function can be used.

Syntax


uint64_t *duckdb_vector_get_validity(
  duckdb_vector vector
);

Parameters


  • vector

The vector to get the data from

  • returns

The pointer to the validity mask, or NULL if no validity mask is present


duckdb_vector_ensure_validity_writable


Ensures the validity mask is writable by allocating it.

After this function is called, duckdb_vector_get_validity will ALWAYS return non-NULL. This allows null values to be written to the vector, regardless of whether a validity mask was present before.

Syntax


void duckdb_vector_ensure_validity_writable(
  duckdb_vector vector
);

Parameters


  • vector

The vector to alter


duckdb_vector_assign_string_element


Assigns a string element in the vector at the specified location.

Syntax


void duckdb_vector_assign_string_element(
  duckdb_vector vector,
  idx_t index,
  const char *str
);

Parameters


  • vector

The vector to alter

  • index

The row position in the vector to assign the string to

  • str

The null-terminated string


duckdb_vector_assign_string_element_len


Assigns a string element in the vector at the specified location.

Syntax


void duckdb_vector_assign_string_element_len(
  duckdb_vector vector,
  idx_t index,
  const char *str,
  idx_t str_len
);

Parameters


  • vector

The vector to alter

  • index

The row position in the vector to assign the string to

  • str

The string

  • str_len

The length of the string (in bytes)


duckdb_list_vector_get_child


Retrieves the child vector of a list vector.

The resulting vector is valid as long as the parent vector is valid.

Syntax


duckdb_vector duckdb_list_vector_get_child(
  duckdb_vector vector
);

Parameters


  • vector

The vector

  • returns

The child vector


duckdb_list_vector_get_size


Returns the size of the child vector of the list

Syntax


idx_t duckdb_list_vector_get_size(
  duckdb_vector vector
);

Parameters


  • vector

The vector

  • returns

The size of the child list


duckdb_struct_vector_get_child


Retrieves the child vector of a struct vector.

The resulting vector is valid as long as the parent vector is valid.

Syntax


duckdb_vector duckdb_struct_vector_get_child(
  duckdb_vector vector,
  idx_t index
);

Parameters


  • vector

The vector

  • index

The child index

  • returns

The child vector


duckdb_validity_row_is_valid


Returns whether or not a row is valid (i.e. not NULL) in the given validity mask.

Syntax


bool duckdb_validity_row_is_valid(
  uint64_t *validity,
  idx_t row
);

Parameters


  • validity

The validity mask, as obtained through duckdb_data_chunk_get_validity

  • row

The row index

  • returns

true if the row is valid, false otherwise


duckdb_validity_set_row_validity


In a validity mask, sets a specific row to either valid or invalid.

Note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity, to ensure that there is a validity mask to write to.

Syntax


void duckdb_validity_set_row_validity(
  uint64_t *validity,
  idx_t row,
  bool valid
);

Parameters


  • validity

The validity mask, as obtained through duckdb_data_chunk_get_validity.

  • row

The row index

  • valid

Whether or not to set the row to valid, or invalid


duckdb_validity_set_row_invalid


In a validity mask, sets a specific row to invalid.

Equivalent to duckdb_validity_set_row_validity with valid set to false.

Syntax


void duckdb_validity_set_row_invalid(
  uint64_t *validity,
  idx_t row
);

Parameters


  • validity

The validity mask

  • row

The row index


duckdb_validity_set_row_valid


In a validity mask, sets a specific row to valid.

Equivalent to duckdb_validity_set_row_validity with valid set to true.

Syntax


void duckdb_validity_set_row_valid(
  uint64_t *validity,
  idx_t row
);

Parameters


  • validity

The validity mask

  • row

The row index


duckdb_create_table_function


Creates a new empty table function.

The return value should be destroyed with duckdb_destroy_table_function.

Syntax


duckdb_table_function duckdb_create_table_function(
  
);

Parameters


  • returns

The table function object.


duckdb_destroy_table_function


Destroys the given table function object.

Syntax


void duckdb_destroy_table_function(
  duckdb_table_function *table_function
);

Parameters


  • table_function

The table function to destroy


duckdb_table_function_set_name


Sets the name of the given table function.

Syntax


void duckdb_table_function_set_name(
  duckdb_table_function table_function,
  const char *name
);

Parameters


  • table_function

The table function

  • name

The name of the table function


duckdb_table_function_add_parameter


Adds a parameter to the table function.

Syntax


void duckdb_table_function_add_parameter(
  duckdb_table_function table_function,
  duckdb_logical_type type
);

Parameters


  • table_function

The table function

  • type

The type of the parameter to add.


duckdb_table_function_set_extra_info


Assigns extra information to the table function that can be fetched during binding, etc.

Syntax


void duckdb_table_function_set_extra_info(
  duckdb_table_function table_function,
  void *extra_info,
  duckdb_delete_callback_t destroy
);

Parameters


  • table_function

The table function

  • extra_info

The extra information

  • destroy

The callback that will be called to destroy the bind data (if any)


duckdb_table_function_set_bind


Sets the bind function of the table function

Syntax


void duckdb_table_function_set_bind(
  duckdb_table_function table_function,
  duckdb_table_function_bind_t bind
);

Parameters


  • table_function

The table function

  • bind

The bind function


duckdb_table_function_set_init


Sets the init function of the table function

Syntax


void duckdb_table_function_set_init(
  duckdb_table_function table_function,
  duckdb_table_function_init_t init
);

Parameters


  • table_function

The table function

  • init

The init function


duckdb_table_function_set_function


Sets the main function of the table function

Syntax


void duckdb_table_function_set_function(
  duckdb_table_function table_function,
  duckdb_table_function_t function
);

Parameters


  • table_function

The table function

  • function

The function


duckdb_register_table_function


Register the table function object within the given connection.

The function requires at least a name, a bind function, an init function and a main function.

If the function is incomplete or a function with this name already exists DuckDBError is returned.

Syntax


duckdb_state duckdb_register_table_function(
  duckdb_connection con,
  duckdb_table_function function
);

Parameters


  • con

The connection to register it in.

  • function

The function pointer

  • returns

Whether or not the registration was successful.


duckdb_bind_get_extra_info


Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

Syntax


void *duckdb_bind_get_extra_info(
  duckdb_bind_info info
);

Parameters


  • info

The info object

  • returns

The extra info


duckdb_bind_add_result_column


Adds a result column to the output of the table function.

Syntax


void duckdb_bind_add_result_column(
  duckdb_bind_info info,
  const char *name,
  duckdb_logical_type type
);

Parameters


  • info

The info object

  • name

The name of the column

  • type

The logical type of the column


duckdb_bind_get_parameter_count


Retrieves the number of regular (non-named) parameters to the function.

Syntax


idx_t duckdb_bind_get_parameter_count(
  duckdb_bind_info info
);

Parameters


  • info

The info object

  • returns

The number of parameters


duckdb_bind_get_parameter


Retrieves the parameter at the given index.

The result must be destroyed with duckdb_destroy_value.

Syntax


duckdb_value duckdb_bind_get_parameter(
  duckdb_bind_info info,
  idx_t index
);

Parameters


  • info

The info object

  • index

The index of the parameter to get

  • returns

The value of the parameter. Must be destroyed with duckdb_destroy_value.


duckdb_bind_set_bind_data


Sets the user-provided bind data in the bind object. This object can be retrieved again during execution.

Syntax


void duckdb_bind_set_bind_data(
  duckdb_bind_info info,
  void *bind_data,
  duckdb_delete_callback_t destroy
);

Parameters


  • info

The info object

  • extra_data

The bind data object.

  • destroy

The callback that will be called to destroy the bind data (if any)


duckdb_bind_set_error


Report that an error has occurred while calling bind.

Syntax


void duckdb_bind_set_error(
  duckdb_bind_info info,
  const char *error
);

Parameters


  • info

The info object

  • error

The error message


duckdb_init_get_extra_info


Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

Syntax


void *duckdb_init_get_extra_info(
  duckdb_init_info info
);

Parameters


  • info

The info object

  • returns

The extra info


duckdb_init_get_bind_data


Gets the bind data set by duckdb_bind_set_bind_data during the bind.

Note that the bind data should be considered as read-only. For tracking state, use the init data instead.

Syntax


void *duckdb_init_get_bind_data(
  duckdb_init_info info
);

Parameters


  • info

The info object

  • returns

The bind data object


duckdb_init_set_init_data


Sets the user-provided init data in the init object. This object can be retrieved again during execution.

Syntax


void duckdb_init_set_init_data(
  duckdb_init_info info,
  void *init_data,
  duckdb_delete_callback_t destroy
);

Parameters


  • info

The info object

  • extra_data

The init data object.

  • destroy

The callback that will be called to destroy the init data (if any)


duckdb_init_set_error


Report that an error has occurred while calling init.

Syntax


void duckdb_init_set_error(
  duckdb_init_info info,
  const char *error
);

Parameters


  • info

The info object

  • error

The error message


duckdb_function_get_extra_info


Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

Syntax


void *duckdb_function_get_extra_info(
  duckdb_function_info info
);

Parameters


  • info

The info object

  • returns

The extra info


duckdb_function_get_bind_data


Gets the bind data set by duckdb_bind_set_bind_data during the bind.

Note that the bind data should be considered as read-only. For tracking state, use the init data instead.

Syntax


void *duckdb_function_get_bind_data(
  duckdb_function_info info
);

Parameters


  • info

The info object

  • returns

The bind data object


duckdb_function_get_init_data


Gets the init data set by duckdb_bind_set_init_data during the bind.

Syntax


void *duckdb_function_get_init_data(
  duckdb_function_info info
);

Parameters


  • info

The info object

  • returns

The init data object


duckdb_function_set_error


Report that an error has occurred while executing the function.

Syntax


void duckdb_function_set_error(
  duckdb_function_info info,
  const char *error
);

Parameters


  • info

The info object

  • error

The error message


duckdb_add_replacement_scan


Add a replacement scan definition to the specified database

Syntax


void duckdb_add_replacement_scan(
  duckdb_database db,
  duckdb_replacement_callback_t replacement,
  void *extra_data,
  duckdb_delete_callback_t delete_callback
);

Parameters


  • db

The database object to add the replacement scan to

  • replacement

The replacement scan callback

  • extra_data

Extra data that is passed back into the specified callback

  • delete_callback

The delete callback to call on the extra data, if any


duckdb_replacement_scan_set_function_name


Sets the replacement function name to use. If this function is called in the replacement callback, the replacement scan is performed. If it is not called, the replacement callback is not performed.

Syntax


void duckdb_replacement_scan_set_function_name(
  duckdb_replacement_scan_info info,
  const char *function_name
);

Parameters


  • info

The info object

  • function_name

The function name to substitute.


duckdb_replacement_scan_add_parameter


Adds a parameter to the replacement scan function.

Syntax


void duckdb_replacement_scan_add_parameter(
  duckdb_replacement_scan_info info,
  duckdb_value parameter
);

Parameters


  • info

The info object

  • parameter

The parameter to add.


duckdb_appender_create


Creates an appender object.

Syntax


duckdb_state duckdb_appender_create(
  duckdb_connection connection,
  const char *schema,
  const char *table,
  duckdb_appender *out_appender
);

Parameters


  • connection

The connection context to create the appender in.

  • schema

The schema of the table to append to, or nullptr for the default schema.

  • table

The table name to append to.

  • out_appender

The resulting appender object.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_error


Returns the error message associated with the given appender. If the appender has no error message, this returns nullptr instead.

The error message should not be freed. It will be de-allocated when duckdb_appender_destroy is called.

Syntax


const char *duckdb_appender_error(
  duckdb_appender appender
);

Parameters


  • appender

The appender to get the error from.

  • returns

The error message, or nullptr if there is none.


duckdb_appender_flush


Flush the appender to the table, forcing the cache of the appender to be cleared and the data to be appended to the base table.

This should generally not be used unless you know what you are doing. Instead, call duckdb_appender_destroy when you are done with the appender.

Syntax


duckdb_state duckdb_appender_flush(
  duckdb_appender appender
);

Parameters


  • appender

The appender to flush.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_close


Close the appender, flushing all intermediate state in the appender to the table and closing it for further appends.

This is generally not necessary. Call duckdb_appender_destroy instead.

Syntax


duckdb_state duckdb_appender_close(
  duckdb_appender appender
);

Parameters


  • appender

The appender to flush and close.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_destroy


Close the appender and destroy it. Flushing all intermediate state in the appender to the table, and de-allocating all memory associated with the appender.

Syntax


duckdb_state duckdb_appender_destroy(
  duckdb_appender *appender
);

Parameters


  • appender

The appender to flush, close and destroy.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_appender_begin_row


A nop function, provided for backwards compatibility reasons. Does nothing. Only duckdb_appender_end_row is required.

Syntax


duckdb_state duckdb_appender_begin_row(
  duckdb_appender appender
);


duckdb_appender_end_row


Finish the current row of appends. After end_row is called, the next row can be appended.

Syntax


duckdb_state duckdb_appender_end_row(
  duckdb_appender appender
);

Parameters


  • appender

The appender.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_append_bool


Append a bool value to the appender.

Syntax


duckdb_state duckdb_append_bool(
  duckdb_appender appender,
  bool value
);


duckdb_append_int8


Append an int8_t value to the appender.

Syntax


duckdb_state duckdb_append_int8(
  duckdb_appender appender,
  int8_t value
);


duckdb_append_int16


Append an int16_t value to the appender.

Syntax


duckdb_state duckdb_append_int16(
  duckdb_appender appender,
  int16_t value
);


duckdb_append_int32


Append an int32_t value to the appender.

Syntax


duckdb_state duckdb_append_int32(
  duckdb_appender appender,
  int32_t value
);


duckdb_append_int64


Append an int64_t value to the appender.

Syntax


duckdb_state duckdb_append_int64(
  duckdb_appender appender,
  int64_t value
);


duckdb_append_hugeint


Append a duckdb_hugeint value to the appender.

Syntax


duckdb_state duckdb_append_hugeint(
  duckdb_appender appender,
  duckdb_hugeint value
);


duckdb_append_uint8


Append a uint8_t value to the appender.

Syntax


duckdb_state duckdb_append_uint8(
  duckdb_appender appender,
  uint8_t value
);


duckdb_append_uint16


Append a uint16_t value to the appender.

Syntax


duckdb_state duckdb_append_uint16(
  duckdb_appender appender,
  uint16_t value
);


duckdb_append_uint32


Append a uint32_t value to the appender.

Syntax


duckdb_state duckdb_append_uint32(
  duckdb_appender appender,
  uint32_t value
);


duckdb_append_uint64


Append a uint64_t value to the appender.

Syntax


duckdb_state duckdb_append_uint64(
  duckdb_appender appender,
  uint64_t value
);


duckdb_append_float


Append a float value to the appender.

Syntax


duckdb_state duckdb_append_float(
  duckdb_appender appender,
  float value
);


duckdb_append_double


Append a double value to the appender.

Syntax


duckdb_state duckdb_append_double(
  duckdb_appender appender,
  double value
);


duckdb_append_date


Append a duckdb_date value to the appender.

Syntax


duckdb_state duckdb_append_date(
  duckdb_appender appender,
  duckdb_date value
);


duckdb_append_time


Append a duckdb_time value to the appender.

Syntax


duckdb_state duckdb_append_time(
  duckdb_appender appender,
  duckdb_time value
);


duckdb_append_timestamp


Append a duckdb_timestamp value to the appender.

Syntax


duckdb_state duckdb_append_timestamp(
  duckdb_appender appender,
  duckdb_timestamp value
);


duckdb_append_interval


Append a duckdb_interval value to the appender.

Syntax


duckdb_state duckdb_append_interval(
  duckdb_appender appender,
  duckdb_interval value
);


duckdb_append_varchar


Append a varchar value to the appender.

Syntax


duckdb_state duckdb_append_varchar(
  duckdb_appender appender,
  const char *val
);


duckdb_append_varchar_length


Append a varchar value to the appender.

Syntax


duckdb_state duckdb_append_varchar_length(
  duckdb_appender appender,
  const char *val,
  idx_t length
);


duckdb_append_blob


Append a blob value to the appender.

Syntax


duckdb_state duckdb_append_blob(
  duckdb_appender appender,
  const void *data,
  idx_t length
);


duckdb_append_null


Append a NULL value to the appender (of any type).

Syntax


duckdb_state duckdb_append_null(
  duckdb_appender appender
);


duckdb_append_data_chunk


Appends a pre-filled data chunk to the specified appender.

The types of the data chunk must exactly match the types of the table, no casting is performed. If the types do not match or the appender is in an invalid state, DuckDBError is returned. If the append is successful, DuckDBSuccess is returned.

Syntax


duckdb_state duckdb_append_data_chunk(
  duckdb_appender appender,
  duckdb_data_chunk chunk
);

Parameters


  • appender

The appender to append to.

  • chunk

The data chunk to append.

  • returns

The return state.


duckdb_query_arrow


Executes a SQL query within a connection and stores the full (materialized) result in an arrow structure. If the query fails to execute, DuckDBError is returned and the error message can be retrieved by calling duckdb_query_arrow_error.

Note that after running duckdb_query_arrow, duckdb_destroy_arrow must be called on the result object even if the query fails, otherwise the error stored within the result will not be freed correctly.

Syntax


duckdb_state duckdb_query_arrow(
  duckdb_connection connection,
  const char *query,
  duckdb_arrow *out_result
);

Parameters


  • connection

The connection to perform the query in.

  • query

The SQL query to run.

  • out_result

The query result.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_query_arrow_schema


Fetch the internal arrow schema from the arrow result.

Syntax


duckdb_state duckdb_query_arrow_schema(
  duckdb_arrow result,
  duckdb_arrow_schema *out_schema
);

Parameters


  • result

The result to fetch the schema from.

  • out_schema

The output schema.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_query_arrow_array


Fetch an internal arrow array from the arrow result.

This function can be called multiple time to get next chunks, which will free the previous out_array. So consume the out_array before calling this function again.

Syntax


duckdb_state duckdb_query_arrow_array(
  duckdb_arrow result,
  duckdb_arrow_array *out_array
);

Parameters


  • result

The result to fetch the array from.

  • out_array

The output array.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


duckdb_arrow_column_count


Returns the number of columns present in a the arrow result object.

Syntax


idx_t duckdb_arrow_column_count(
  duckdb_arrow result
);

Parameters


  • result

The result object.

  • returns

The number of columns present in the result object.


duckdb_arrow_row_count


Returns the number of rows present in a the arrow result object.

Syntax


idx_t duckdb_arrow_row_count(
  duckdb_arrow result
);

Parameters


  • result

The result object.

  • returns

The number of rows present in the result object.


duckdb_arrow_rows_changed


Returns the number of rows changed by the query stored in the arrow result. This is relevant only for INSERT/UPDATE/DELETE queries. For other queries the rows_changed will be 0.

Syntax


idx_t duckdb_arrow_rows_changed(
  duckdb_arrow result
);

Parameters


  • result

The result object.

  • returns

The number of rows changed.


duckdb_query_arrow_error


Returns the error message contained within the result. The error is only set if duckdb_query_arrow returns DuckDBError.

The error message should not be freed. It will be de-allocated when duckdb_destroy_arrow is called.

Syntax


const char *duckdb_query_arrow_error(
  duckdb_arrow result
);

Parameters


  • result

The result object to fetch the nullmask from.

  • returns

The error of the result.


duckdb_destroy_arrow


Closes the result and de-allocates all memory allocated for the arrow result.

Syntax


void duckdb_destroy_arrow(
  duckdb_arrow *result
);

Parameters


  • result

The result to destroy.