An appender object that can be used to append rows to an existing table.

• DateTime objects in Julia are stored in milliseconds since the Unix epoch but are converted to microseconds when stored in duckdb.
• Time objects in Julia are stored in nanoseconds since midnight but are converted to microseconds when stored in duckdb.
• Missing and Nothing are stored as NULL in duckdb, but will be converted to Missing when the data is queried back.

Example

using DuckDB, DataFrames, Dates
db = DuckDB.DB()

# create a table
DBInterface.execute(db, "CREATE OR REPLACE TABLE data(id INT PRIMARY KEY, value FLOAT, timestamp TIMESTAMP, date DATE)")

# data to insert 
len = 100
df = DataFrames.DataFrame(id=collect(1:len),
    value=rand(len),
    timestamp=Dates.now() + Dates.Second.(1:len),
    date=Dates.today() + Dates.Day.(1:len))

# append data by row
appender = DuckDB.Appender(db, "data")
for i in eachrow(df)
    for j in i
        DuckDB.append(appender, j)
    end
    DuckDB.end_row(appender)
end
# flush the appender after all rows
DuckDB.flush(appender)
DuckDB.close(appender)

Configuration object

A connection object to a DuckDB database.

Transaction contexts are local to a single connection.

A connection can only run a single query concurrently. It is possible to open multiple connections to a single DuckDB database instance. Multiple connections can run multiple queries concurrently.

A DuckDB database object.

By default a DuckDB database object has an open connection object (db.mainconnection). When the database object is used directly in queries, it is actually the underlying mainconnection that is used.

It is possible to open new connections to a single database instance using DBInterface.connect(db).

DuckDB data chunk

Internal DuckDB database handle.

DuckDB type

DuckDB table function

DuckDB validity mask

DuckDB value

DuckDB vector

Days are stored as days since 1970-01-01

Use the duckdbfromdate/duckdbtodate function to extract individual information

Hugeints are composed in a (lower, upper) component

The value of the hugeint is upper * 2^64 + lower

For easy usage, the functions duckdbhugeinttodouble/duckdbdoubletohugeint are recommended

Time is stored as microseconds since 00:00:00

Use the duckdbfromtime/duckdbtotime function to extract individual information

Timestamps are stored as microseconds since 1970-01-01

Use the duckdbfromtimestamp/duckdbtotimestamp function to extract individual information

DBInterface.execute(db::DuckDB.DB, sql::String, [params])
DBInterface.execute(stmt::SQLite.Stmt, [params])

Bind any positional (params as Vector or Tuple) or named (params as NamedTuple or Dict) parameters to an SQL statement, given by db and sql or as an already prepared statement stmt, execute the query and return an iterator of result rows.

Note that the returned result row iterator only supports a single-pass, forward-only iteration of the result rows. Calling SQLite.reset!(result) will re-execute the query and reset the iterator back to the beginning.

The resultset iterator supports the Tables.jl interface, so results can be collected in any Tables.jl-compatible sink, like DataFrame(results), CSV.write("results.csv", results), etc.

Return the last row insert id from the executed statement

DBInterface.prepare(db::DuckDB.DB, sql::AbstractString)

Prepare an SQL statement given as a string in the DuckDB database; returns a DuckDB.Stmt object. See DBInterface.execute(@ref) for information on executing a prepared statement and passing parameters to bind. A DuckDB.Stmt object can be closed (resources freed) using DBInterface.close!(@ref).

DuckDB.begin(db)

begin a transaction

DuckDB.commit(db)

commit a transaction

Add a replacement scan definition to the specified database

• 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

Append a blob value to the appender. DUCKDBAPI duckdbstate duckdbappendblob(duckdbappender appender, const void *data, idxt length);

Append a bool value to the appender. DUCKDBAPI duckdbstate duckdbappendbool(duckdb_appender appender, bool value);

Append a duckdbdate value to the appender. DUCKDBAPI duckdbstate duckdbappenddate(duckdbappender appender, duckdb_date value);

Append a double value to the appender. DUCKDBAPI duckdbstate duckdbappenddouble(duckdb_appender appender, double value);

Append a float value to the appender. DUCKDBAPI duckdbstate duckdbappendfloat(duckdb_appender appender, float value);

Append a duckdbhugeint value to the appender. DUCKDBAPI duckdbstate duckdbappendhugeint(duckdbappender appender, duckdb_hugeint value);

Append an int16t value to the appender. DUCKDBAPI duckdbstate duckdbappendint16(duckdbappender appender, int16_t value);

Append an int32t value to the appender. DUCKDBAPI duckdbstate duckdbappendint32(duckdbappender appender, int32_t value);

Append an int64t value to the appender. DUCKDBAPI duckdbstate duckdbappendint64(duckdbappender appender, int64_t value);

Append an int8t value to the appender. DUCKDBAPI duckdbstate duckdbappendint8(duckdbappender appender, int8_t value);

Append a duckdbinterval value to the appender. DUCKDBAPI duckdbstate duckdbappendinterval(duckdbappender appender, duckdb_interval value);

Append a NULL value to the appender (of any type). DUCKDBAPI duckdbstate duckdbappendnull(duckdb_appender appender);

Append a duckdbtime value to the appender. DUCKDBAPI duckdbstate duckdbappendtime(duckdbappender appender, duckdb_time value);

Append a duckdbtimestamp value to the appender. DUCKDBAPI duckdbstate duckdbappendtimestamp(duckdbappender appender, duckdb_timestamp value);

Append a duckdbuhugeint value to the appender. DUCKDBAPI duckdbstate duckdbappenduhugeint(duckdbappender appender, duckdb_uhugeint value);

Append a uint16t value to the appender. DUCKDBAPI duckdbstate duckdbappenduint16(duckdbappender appender, uint16_t value);

Append a uint32t value to the appender. DUCKDBAPI duckdbstate duckdbappenduint32(duckdbappender appender, uint32_t value);

Append a uint64t value to the appender. DUCKDBAPI duckdbstate duckdbappenduint64(duckdbappender appender, uint64_t value);

Append a uint8t value to the appender. DUCKDBAPI duckdbstate duckdbappenduint8(duckdbappender appender, uint8_t value);

Append a varchar value to the appender. DUCKDBAPI duckdbstate duckdbappendvarchar(duckdb_appender appender, const char *val);

Append a varchar value to the appender. DUCKDBAPI duckdbstate duckdbappendvarcharlength(duckdbappender appender, const char *val, idx_t length);

A nop function, provided for backwards compatibility reasons. Does nothing. Only duckdb_appender_end_row is required. DUCKDBAPI duckdbstate duckdbappenderbeginrow(duckdbappender appender);

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.

• appender: The appender to flush and close.
• returns: DuckDBSuccess on success or DuckDBError on failure.

DUCKDBAPI duckdbstate duckdbappenderclose(duckdb_appender appender);

Creates an appender object.

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

DUCKDBAPI duckdbstate duckdbappendercreate(duckdbconnection connection, const char *schema, const char *table, duckdbappender *out_appender);

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.

• appender: The appender to flush, close and destroy.
• returns: DuckDBSuccess on success or DuckDBError on failure.

DUCKDBAPI duckdbstate duckdbappenderdestroy(duckdb_appender *appender);

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

• appender: The appender.
• returns: DuckDBSuccess on success or DuckDBError on failure.

DUCKDBAPI duckdbstate duckdbappenderendrow(duckdbappender appender);

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.

• appender: The appender to get the error from.
• returns: The error message, or nullptr if there is none.

DUCKDBAPI const char *duckdbappendererror(duckdbappender appender);

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.

• appender: The appender to flush.
• returns: DuckDBSuccess on success or DuckDBError on failure.

DUCKDBAPI duckdbstate duckdbappenderflush(duckdb_appender appender);

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

• info: The info object
• name: The name of the column
• type: The logical type of the column

Binds a blob value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindblob(duckdbpreparedstatement preparedstatement, idxt paramidx, const void *data, idxt length);

Binds a bool value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindboolean(duckdbpreparedstatement preparedstatement, idxt param_idx, bool val);

Binds a duckdbdate value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbinddate(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdb_date val);

Binds a double value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbinddouble(duckdbpreparedstatement preparedstatement, idxt param_idx, double val);

Binds a float value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindfloat(duckdbpreparedstatement preparedstatement, idxt param_idx, float val);

Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

• info: The info object
• returns: The extra info

Retrieves the parameter at the given index.

The result must be destroyed with duckdb_destroy_value.

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

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

• info: The info object
• returns: The number of parameters

Binds a duckdbhugeint value to the prepared statement at the specified index. */ DUCKDBAPI duckdbstate duckdbbindhugeint(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdb_hugeint val);

Binds an int16t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindint16(duckdbpreparedstatement preparedstatement, idxt paramidx, int16_t val);

Binds an int32t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindint32(duckdbpreparedstatement preparedstatement, idxt paramidx, int32_t val);

Binds an int64t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindint64(duckdbpreparedstatement preparedstatement, idxt paramidx, int64_t val);

Binds an int8t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindint8(duckdbpreparedstatement preparedstatement, idxt paramidx, int8_t val);

Binds a duckdbinterval value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindinterval(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdb_interval val);

Binds a NULL value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindnull(duckdbpreparedstatement preparedstatement, idxt param_idx);

Retrieves the parameter at the given index.

The result must be destroyed with duckdb_destroy_value.

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

Sets the cardinality estimate for the table function, used for optimization.

• info: The bind data object.
• is_exact: Whether or not the cardinality estimate is exact, or an approximation

Report that an error has occurred during bind.

• info: The info object
• error: The error message

Binds a duckdbtime value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindtime(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdb_time val);

Binds a duckdbtimestamp value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindtimestamp(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdb_timestamp val);

Binds an duckdbuhugeint value to the prepared statement at the specified index. */ DUCKDBAPI duckdbstate duckdbbindhugeint(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdb_uhugeint val);

Binds an uint16t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbinduint16(duckdbpreparedstatement preparedstatement, idxt paramidx, uint16_t val);

Binds an uint32t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbinduint32(duckdbpreparedstatement preparedstatement, idxt paramidx, uint32_t val);

Binds an uint64t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbinduint64(duckdbpreparedstatement preparedstatement, idxt paramidx, uint64_t val);

Binds an uint8t value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbinduint8(duckdbpreparedstatement preparedstatement, idxt paramidx, uint8_t val);

Binds a null-terminated varchar value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindvarchar(duckdbpreparedstatement preparedstatement, idxt param_idx, const char *val);

Binds a varchar value to the prepared statement at the specified index. DUCKDBAPI duckdbstate duckdbbindvarcharlength(duckdbpreparedstatement preparedstatement, idxt paramidx, const char *val, idx_t length);

duckdb_close(database)

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.

• database: The database object to shut down.

duckdb_column_count(result)

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

• result: The result object.
• returns: The number of columns present in the result object.

duckdb_column_data(result,col)

Returns the data of a specific column of a result in columnar format. This is the fastest way of accessing data in a query result, as no conversion or type checking must be performed (outside of the original switch). If performance is a concern, it is recommended to use this API over the duckdb_value functions. The function returns a dense array which contains the result data. The exact type stored in the array depends on the corresponding duckdbtype (as provided by `duckdbcolumntype). For the exact type by which the data should be accessed, see the comments in [the types section](types) or theDUCKDBTYPEenum. For example, for a column of typeDUCKDBTYPEINTEGER`, 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]);

• result: The result object to fetch the column data from.
• col: The column index.
• returns: The column data of the specified column.

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.

• 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_name(result,col)

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.

• 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(result,col)

Returns the column type of the specified column. Returns DUCKDB_TYPE_INVALID if the column is out of range.

• result: The result object to fetch the column type from.
• col: The column index.
• returns: The column type of the specified column.

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.

• returns: The amount of config options available.

duckdb_connect(database, out_connection)

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

• database: The database file to connect to.
• out_connection: The result connection object.
• returns: DuckDBSuccess on success or DuckDBError on failure.

duckdb_create_config(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.

• out_config: The result configuration object.
• returns: DuckDBSuccess on success or DuckDBError on failure.

Creates an empty DataChunk with the specified set of types.

• types: An array of types of the data chunk.
• column_count: The number of columns.
• returns: The data chunk.

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.

• width: The width of the decimal type
• scale: The scale of the decimal type
• returns: The logical type.

Creates a value from an int64

• value: The bigint value
• returns: The value. This must be destroyed with duckdb_destroy_value.

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.

• type: The primitive type to create.
• returns: The logical type type.

Creates a new empty table function.

The return value should be destroyed with duckdb_destroy_table_function.

• returns: The table function object.

Creates a task state that can be used with duckdbexecutetasksstate to execute tasks until duckdbfinish_execution is called on the state.

duckdbdestroystate should be called on the result in order to free memory.

• returns: The task state that can be used with duckdbexecutetasks_state.

Creates a value from a null-terminated string

• value: The null-terminated string
• returns: The value. This must be destroyed with duckdb_destroy_value.

Creates a value from a string

• value: The text
• length: The length of the text
• returns: The value. This must be destroyed with duckdb_destroy_value.

Retrieves the number of columns in a data chunk.

• chunk: The data chunk to get the data from
• returns: The number of columns in the data chunk

Retrieves the current number of tuples in a data chunk.

• chunk: The data chunk to get the data from
• returns: The number of tuples in the data chunk

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.

• chunk: The data chunk to get the data from
• returns: The vector

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

• chunk: The data chunk to reset.

Sets the current number of tuples in a data chunk.

• chunk: The data chunk to set the size in
• size: The number of tuples in the data chunk

Retrieves the internal storage type of a decimal type.

• type: The logical type object
• returns: The internal type of the decimal type

Retrieves the scale of a decimal type.

• type: The logical type object
• returns: The scale of the decimal type

Retrieves the width of a decimal type.

• type: The logical type object
• returns: The width of the decimal type

duckdb_destroy_config(config)

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

• config: The configuration object to destroy.

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

• chunk: The data chunk to destroy.

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

• type: The logical type to destroy.

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

• pending_result: The pending result to destroy.

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

• prepared_statement: The prepared statement to destroy.

DUCKDBAPI void duckdbdestroyprepare(duckdbpreparedstatement *preparedstatement);

duckdb_destroy_result(result)

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

• result: The result to destroy.

Destroys the given table function object.

• table_function: The table function to destroy

Destroys the task state returned from duckdbcreatetask_state.

Note that this should not be called while there is an active duckdbexecutetasks_state running on the task state.

• state: The task state to clean up

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

• value: The value to destroy.

duckdb_disconnect(connection)

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

• connection: The connection to close.

Retrieves the dictionary size of the enum type

• type: The logical type object
• returns: The dictionary size of the enum type

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

The result must be freed with duckdb_free

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

Retrieves the internal storage type of an enum type.

• type: The logical type object
• returns: The internal type of the enum type

Execute DuckDB tasks on this thread.

The thread will keep on executing tasks until either duckdbfinishexecution is called on the state, max_tasks tasks have been executed or there are no more tasks to be executed.

Multiple threads can share the same duckdbtaskstate.

• state: The task state of the executor
• max_tasks: The maximum amount of tasks to execute
• returns: The amount of tasks that have actually been executed

Fully execute a pending query result, returning the final query result.

If duckdbpendingexecutetask has been called until DUCKDBPENDINGRESULTREADY was returned, this will return fast. Otherwise, all remaining tasks must be executed first.

• pending_result: The pending result to execute.
• out_result: The result object.
• returns: DuckDBSuccess on success or DuckDBError on failure.

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.

• prepared_statement: The prepared statement to execute.
• out_result: The query result.
• returns: DuckDBSuccess on success or DuckDBError on failure.

DUCKDBAPI duckdbstate duckdbexecuteprepared(duckdbpreparedstatement preparedstatement, duckdbresult *out_result);

Execute DuckDB tasks on this thread.

Will return after max_tasks have been executed, or if there are no more tasks present.

• database: The database object to execute tasks for
• max_tasks: The maximum amount of tasks to execute

Execute DuckDB tasks on this thread.

The thread will keep on executing tasks forever, until duckdbfinishexecution is called on the state. Multiple threads can share the same duckdbtaskstate.

• database: The database object to execute tasks for
• state: The task state of the executor

Returns true if execution of the current query is finished.

• con: The connection on which to check

Finish execution on a specific task.

• state: The task state to finish execution

duckdbfree(ptr) Free a value returned from `duckdbmalloc,duckdbvaluevarcharorduckdbvalueblob`.

• ptr: The memory region to de-allocate.

DUCKDBAPI void duckdbfree(void *ptr);

Decompose a TIME_TZ objects into micros and a timezone offset.

Use duckdb_from_time to further decompose the micros into hour, minute, second and microsecond.

• micros: The time object, as obtained from a DUCKDB_TYPE_TIME_TZ column.
• out_micros: The microsecond component of the time.
• out_offset: The timezone offset component of the time.

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.

• info: The info object
• returns: The bind data object

Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

• info: The info object
• returns: The extra info

Gets the init data set by duckdb_init_set_init_data during the init.

• info: The info object
• returns: The init data object

Gets the init data set by duckdb_init_set_init_data during the local_init.

• info: The info object
• returns: The init data object

Report that an error has occurred while executing the function.

• info: The info object
• error: The error message

duckdb_get_config_flag(index,out_name,out_description)

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.

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

Obtains an int64 of the given value.

• value: The value
• returns: The int64 value, or 0 if no conversion is possible

Retrieves the type class of a duckdb_logical_type.

• type: The logical type object
• returns: The type id

Obtains a string representation of the given value. The result must be destroyed with duckdb_free.

• value: The value
• returns: The string value. This must be destroyed with duckdb_free.

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.

• info: The info object
• returns: The bind data object

Returns the number of projected columns.

This function must be used if projection pushdown is enabled to figure out which columns to emit.

• info: The info object
• returns: The number of projected columns.

Returns the column index of the projected column at the specified position.

This function must be used if projection pushdown is enabled to figure out which columns to emit.

• info: The info object
• columnindex: The index at which to get the projected column index, from 0..duckdbinitgetcolumn_count(info)
• returns: The column index of the projected column.

Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

• info: The info object
• returns: The extra info

Report that an error has occurred during init.

• info: The info object
• error: The error message

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

• info: The info object
• extra_data: The init data object.
• destroy: The callback that will be called to destroy the init data (if any)

Sets how many threads can process this table function in parallel (default: 1)

• info: The info object
• max_threads: The maximum amount of threads that can process this table function

Retrieves the child type of the given list type.

The result must be freed with duckdb_destroy_logical_type

• type: The logical type object
• returns: The child type of the list type. Must be destroyed with duckdb_destroy_logical_type.

Retrieves the child vector of a list vector.

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

• vector: The vector
• returns: The child vector

Returns the size of the child vector of the list

• vector: The vector
• returns: The size of the child list

duckdb_malloc(size)

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

• size: The number of bytes to allocate.
• returns: A pointer to the allocated memory region.

DUCKDBAPI void *duckdbmalloc(size_t size);

Returns the number of parameters that can be provided to the given prepared statement. Returns 0 if the query was not successfully prepared.

• prepared_statement: The prepared statement to obtain the number of parameters for.

DUCKDBAPI idxt duckdbnparams(duckdbpreparedstatement preparedstatement);

duckdb_nullmask_data(result,col)

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
", row);
} else {
    printf("Data for row %d: %d
", row, data[row]);
}

• result: The result object to fetch the nullmask from.
• col: The column index.
• returns: The nullmask of the specified column.

duckdb_open(path, out_database)

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

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

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

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

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.

• prepared_statement: The prepared statement.
• param_idx: The parameter index.
• returns: The parameter type

DUCKDBAPI duckdbtype duckdbparamtype(duckdbpreparedstatement preparedstatement, idxt param_idx);

Returns the error message contained within the pending result.

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

• result: The pending result to fetch the error from.
• returns: The error of the pending result.

Checks the state of the execution, returning it. The pending result represents an intermediate structure for a query that is not yet fully executed.

If this returns DUCKDBPENDINGRESULTREADY, the duckdbexecutepending function can be called to obtain the result. If this returns DUCKDBPENDINGRESULTNOTREADY, the duckdbpendingexecutecheckstate function should be called again. If this returns DUCKDBPENDING_ERROR, an error occurred during execution.

The error message can be obtained by calling duckdbpendingerror on the pending_result.

• pending_result: The pending result to check the state of.
• returns: The state of the pending result.

Executes a single task within the query, returning whether or not the query is ready.

If this returns DUCKDBPENDINGRESULTREADY, the duckdbexecutepending function can be called to obtain the result. If this returns DUCKDBPENDINGRESULTNOTREADY, the duckdbpendingexecutetask function should be called again. If this returns DUCKDBPENDINGERROR, an error occurred during execution.

The error message can be obtained by calling duckdbpendingerror on the pending_result.

• pending_result: The pending result to execute a task within.
• returns: The state of the pending result after the execution.

Returns whether a duckdbpendingstate is finished executing. For example if pending_state is DUCKDBPENDINGRESULT_READY, this function will return true.

• pending_state: The pending state on which to decide whether to finish execution.
• returns: Boolean indicating pending execution should be considered finished.

Executes the prepared statement with the given bound parameters, and returns a pending result. The pending result represents an intermediate structure for a query that is not yet fully executed. The pending result can be used to incrementally execute a query, returning control to the client between tasks.

Note that after calling duckdb_pending_prepared, the pending result should always be destroyed using duckdb_destroy_pending, even if this function returns DuckDBError.

• prepared_statement: The prepared statement to execute.
• out_result: The pending query result.
• returns: DuckDBSuccess on success or DuckDBError on failure.

Executes the prepared statement with the given bound parameters, and returns a pending result. This pending result will create a streaming duckdb_result when executed. The pending result represents an intermediate structure for a query that is not yet fully executed.

Note that after calling duckdb_pending_prepared_streaming, the pending result should always be destroyed using duckdb_destroy_pending, even if this function returns DuckDBError.

• prepared_statement: The prepared statement to execute.
• out_result: The pending query result.
• returns: DuckDBSuccess on success or DuckDBError on failure.

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.

• connection: The connection object
• query: The SQL query to prepare
• outpreparedstatement: The resulting prepared statement object
• returns: DuckDBSuccess on success or DuckDBError on failure.

DUCKDBAPI duckdbstate duckdbprepare(duckdbconnection connection, const char *query, duckdbpreparedstatement *outpreparedstatement);

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.

• prepared_statement: The prepared statement to obtain the error from.
• returns: The error message, or nullptr if there is none.

DUCKDBAPI const char *duckdbprepareerror(duckdbpreparedstatement preparedstatement);

duckdb_query(connection,query,out_result)

Executes a SQL query within a connection and stores the full (materialized) result in the outresult pointer. If the query fails to execute, DuckDBError is returned and the error message can be retrieved by calling `duckdbresulterror. Note that after runningduckdbquery,duckdbdestroyresult` must be called on the result object even if the query fails, otherwise the error stored within the result will not be freed correctly.

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

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.

• con: The connection to register it in.
• function: The function pointer
• returns: Whether or not the registration was successful.

Adds a parameter to the replacement scan function.

• info: The info object
• parameter: The parameter to add. The function will call duckdb_destroy_value on the parameter.

Report that an error has occurred while executing the replacement scan.

• info: The info object
• error: The error message

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.

• info: The info object
• function_name: The function name to substitute.

Returns the number of data chunks present in the result.

• result: The result object
• returns: The resulting data chunk. Returns NULL if the chunk index is out of bounds.

duckdb_result_error(result)

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.

• result: The result object to fetch the nullmask from.
• returns: The error of the result.

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.

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

Checks if the type of the internal result is StreamQueryResult.

• result: The result object to check.
• returns: Whether or not the result object is of the type StreamQueryResult

duckdb_row_count(result)

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

• result: The result object.
• returns: The number of rows present in the result object.

duckdb_rows_changed(result)

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.

• result: The result object.
• returns: The number of rows changed.

duckdb_set_config(config,name,option)

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.

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

Fetches a data chunk from the (streaming) 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 can only be used on duckdbresults created with 'duckdbpendingpreparedstreaming'

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 or the materialized result functions).

It is not known beforehand how many chunks will be returned by this result.

• result: The result object to fetch the data chunk from.
• returns: The resulting data chunk. Returns NULL if the result has an error.

Returns the number of children of a struct type.

• type: The logical type object
• returns: The number of children of a struct type.

Retrieves the name of the struct child.

The result must be freed with duckdb_free

• type: The logical type object
• index: The child index
• returns: The name of the struct type. Must be freed with duckdb_free.

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

The result must be freed with duckdb_destroy_logical_type

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

Retrieves the child vector of a struct vector.

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

• vector: The vector
• index: The child index
• returns: The child vector

Adds a parameter to the table function.

• table_function: The table function
• type: The type of the parameter to add.

Sets the bind function of the table function

• table_function: The table function
• bind: The bind function

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

• table_function: The table function
• extra_info: The extra information
• destroy: The callback that will be called to destroy the bind data (if any)

Sets the main function of the table function

• table_function: The table function
• function: The function

Sets the init function of the table function

• table_function: The table function
• init: The init function

Sets the thread-local init function of the table function

• table_function: The table function
• init: The init function

Sets the name of the given table function.

• table_function: The table function
• name: The name of the table function

Sets whether or not the given table function supports projection pushdown.

If this is set to true, the system will provide a list of all required columns in the init stage through the duckdb_init_get_column_count and duckdb_init_get_column_index functions. If this is set to false (the default), the system will expect all columns to be projected.

• table_function: The table function
• pushdown: True if the table function supports projection pushdown, false otherwise.

Check if the provided duckdbtaskstate has finished execution

• state: The task state to inspect
• returns: Whether or not duckdbfinishexecution has been called on the task state

Returns the number of members of a union type.

• type: The logical type object
• returns: The number of members of a union type.

Retrieves the name of the union member.

The result must be freed with duckdb_free

• type: The logical type object
• index: The member index
• returns: The name of the union member. Must be freed with duckdb_free.

Retrieves the member type of the given union type at the specified index.

The result must be freed with duckdb_destroy_logical_type

• type: The logical type object
• index: The member index
• returns: The member type of the union type. Must be destroyed with duckdb_destroy_logical_type.

Retrieves the member vector of a union vector.

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

• vector: The vector
• index: The member index
• returns: The member vector

duckdb_value_boolean(result,col,row)

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

duckdbvaluedate(result,col,row)

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

DUCKDBAPI duckdbdate duckdbvaluedate(duckdbresult *result, idxt col, idx_t row);

duckdb_value_double(result,col,row)

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

duckdb_value_float(result,col,row)

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

duckdb_value_hugeint(result,col,row)

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

duckdb_value_int16(result,col,row)

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

duckdb_value_int32(result,col,row)

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

duckdb_value_int64(result,col,row)

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

duckdb_value_int8(result,col,row)

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

duckdbvalueinterval(result,col,row)

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

DUCKDBAPI duckdbinterval duckdbvalueinterval(duckdbresult *result, idxt col, idx_t row);

duckdbvalueis_null(result,col,row)

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

DUCKDBAPI bool duckdbvalueisnull(duckdbresult *result, idxt col, idx_t row);

duckdbvaluetime(result,col,row)

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

DUCKDBAPI duckdbtime duckdbvaluetime(duckdbresult *result, idxt col, idx_t row);

duckdbvaluetimestamp(result,col,row)

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

DUCKDBAPI duckdbtimestamp duckdbvaluetimestamp(duckdbresult *result, idxt col, idx_t row);

duckdb_value_uhugeint(result,col,row)

• returns: The duckdb_uhugeint value at the specified location, or 0 if the value cannot be converted.

duckdb_value_uint16(result,col,row)

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

duckdb_value_uint32(result,col,row)

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

duckdb_value_uint64(result,col,row)

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

duckdb_value_uint8(result,col,row)

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

duckdbvaluevarchar(result,col,row)

• returns: The char* value at the specified location, or nullptr if the value cannot be converted.

The result must be freed with duckdb_free. DUCKDBAPI char *duckdbvaluevarchar(duckdbresult *result, idxt col, idxt row);

duckdbvaluevarchar_internal(result,col,row)

• 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. DUCKDBAPI char *duckdbvaluevarcharinternal(duckdbresult *result, idxt col, idx_t row);

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

• vector: The vector to alter
• index: The row position in the vector to assign the string to
• str: The null-terminated string

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

• vector: The vector to alter
• index: The row position in the vector to assign the string to
• str: The null-terminated string
• str_len: The string length

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.

• vector: The vector to alter

Retrieves the column type of the specified vector.

The result must be destroyed with duckdb_destroy_logical_type.

• vector: The vector get the data from
• returns: The type of the vector

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.

• vector: The vector to get the data from
• returns: The data pointer

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 uint64t values, where each uint64t 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:

idxt entryidx = rowidx / 64; idxt idxinentry = rowidx % 64; bool isvalid = validitymask[entryidx] & (1 << idxinentry);

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

• vector: The vector to get the data from
• returns: The pointer to the validity mask, or NULL if no validity mask is present

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.

• returns: The vector size.

DuckDB.load!(con, input_df, table)

Load an input DataFrame input_df into a new DuckDB table that will be named table.

Executes a SQL query within a connection and returns the full (materialized) result.

The query function is able to run queries with multiple statements, unlike DBInterface.execute(@ref) which is only able to prepare a single statement.

DuckDB.rollback(db)

rollback transaction