DuckDB
Documentation for DuckDB.
DuckDB.DB
DuckDB.duckdb_date
DuckDB.duckdb_hugeint
DuckDB.duckdb_time
DuckDB.duckdb_timestamp
DBInterface.execute
DuckDB.close
DuckDB.connect
DuckDB.disconnect
DuckDB.duckdb_append_blob
DuckDB.duckdb_append_bool
DuckDB.duckdb_append_date
DuckDB.duckdb_append_double
DuckDB.duckdb_append_float
DuckDB.duckdb_append_hugeint
DuckDB.duckdb_append_int16
DuckDB.duckdb_append_int32
DuckDB.duckdb_append_int64
DuckDB.duckdb_append_int8
DuckDB.duckdb_append_interval
DuckDB.duckdb_append_null
DuckDB.duckdb_append_time
DuckDB.duckdb_append_timestamp
DuckDB.duckdb_append_uint16
DuckDB.duckdb_append_uint32
DuckDB.duckdb_append_uint64
DuckDB.duckdb_append_uint8
DuckDB.duckdb_append_varchar
DuckDB.duckdb_append_varchar_length
DuckDB.duckdb_appender_begin_row
DuckDB.duckdb_appender_close
DuckDB.duckdb_appender_create
DuckDB.duckdb_appender_destroy
DuckDB.duckdb_appender_end_row
DuckDB.duckdb_appender_error
DuckDB.duckdb_appender_flush
DuckDB.duckdb_arrow_column_count
DuckDB.duckdb_arrow_row_count
DuckDB.duckdb_arrow_rows_changed
DuckDB.duckdb_bind_blob
DuckDB.duckdb_bind_boolean
DuckDB.duckdb_bind_date
DuckDB.duckdb_bind_double
DuckDB.duckdb_bind_float
DuckDB.duckdb_bind_hugeint
DuckDB.duckdb_bind_int16
DuckDB.duckdb_bind_int32
DuckDB.duckdb_bind_int64
DuckDB.duckdb_bind_int8
DuckDB.duckdb_bind_interval
DuckDB.duckdb_bind_null
DuckDB.duckdb_bind_time
DuckDB.duckdb_bind_timestamp
DuckDB.duckdb_bind_uint16
DuckDB.duckdb_bind_uint32
DuckDB.duckdb_bind_uint64
DuckDB.duckdb_bind_uint8
DuckDB.duckdb_bind_varchar
DuckDB.duckdb_bind_varchar_length
DuckDB.duckdb_close
DuckDB.duckdb_column_count
DuckDB.duckdb_column_data
DuckDB.duckdb_column_name
DuckDB.duckdb_column_type
DuckDB.duckdb_config_count
DuckDB.duckdb_connect
DuckDB.duckdb_create_config
DuckDB.duckdb_destroy_arrow
DuckDB.duckdb_destroy_config
DuckDB.duckdb_destroy_prepare
DuckDB.duckdb_destroy_result
DuckDB.duckdb_disconnect
DuckDB.duckdb_double_to_hugeint
DuckDB.duckdb_execute_prepared
DuckDB.duckdb_execute_prepared_arrow
DuckDB.duckdb_free
DuckDB.duckdb_from_date
DuckDB.duckdb_from_time
DuckDB.duckdb_from_timestamp
DuckDB.duckdb_get_config_flag
DuckDB.duckdb_hugeint_to_double
DuckDB.duckdb_malloc
DuckDB.duckdb_nparams
DuckDB.duckdb_nullmask_data
DuckDB.duckdb_open
DuckDB.duckdb_param_type
DuckDB.duckdb_prepare
DuckDB.duckdb_prepare_error
DuckDB.duckdb_query
DuckDB.duckdb_query_arrow
DuckDB.duckdb_query_arrow_array
DuckDB.duckdb_query_arrow_error
DuckDB.duckdb_query_arrow_schema
DuckDB.duckdb_result_error
DuckDB.duckdb_row_count
DuckDB.duckdb_rows_changed
DuckDB.duckdb_set_config
DuckDB.duckdb_to_date
DuckDB.duckdb_to_time
DuckDB.duckdb_to_timestamp
DuckDB.duckdb_value_blob
DuckDB.duckdb_value_boolean
DuckDB.duckdb_value_date
DuckDB.duckdb_value_double
DuckDB.duckdb_value_float
DuckDB.duckdb_value_hugeint
DuckDB.duckdb_value_int16
DuckDB.duckdb_value_int32
DuckDB.duckdb_value_int64
DuckDB.duckdb_value_int8
DuckDB.duckdb_value_interval
DuckDB.duckdb_value_is_null
DuckDB.duckdb_value_time
DuckDB.duckdb_value_timestamp
DuckDB.duckdb_value_uint16
DuckDB.duckdb_value_uint32
DuckDB.duckdb_value_uint64
DuckDB.duckdb_value_uint8
DuckDB.duckdb_value_varchar
DuckDB.duckdb_value_varchar_internal
DuckDB.execute
DuckDB.toDataFrame
DuckDB.toDataFrame
DuckDB.DB
— Type`DuckDB.DB()` => in-memory DuckDB database
`DuckDB.DB(file)` => file-based DuckDB database
Constructors for a representation of a DuckDB database, either backed by an on-disk file or in-memory.
DuckDB.DB
requires the file
string argument in the 2nd definition as the name of either a pre-defined DuckDB database to be opened, or if the file doesn't exist, a database will be created.
The DuckDB.DB
object represents a single connection to a DuckDB database. All other DuckDB.jl functions take an DuckDB.DB
as the first argument as context.
To create an in-memory temporary database, call DuckDB.DB()
.
The DuckDB.DB
will be automatically closed/shutdown when it goes out of scope (i.e. the end of the Julia session, end of a function call wherein it was created, etc.)
NOTE: This borrows heavily from SQLite.jl, here
DuckDB.duckdb_date
— TypeDays are stored as days since 1970-01-01
Use the duckdbfromdate/duckdbtodate function to extract individual information
DuckDB.duckdb_hugeint
— TypeHugeints 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
DuckDB.duckdb_time
— TypeTime is stored as microseconds since 00:00:00
Use the duckdbfromtime/duckdbtotime function to extract individual information
DuckDB.duckdb_timestamp
— TypeTimestamps are stored as microseconds since 1970-01-01
Use the duckdbfromtimestamp/duckdbtotimestamp function to extract individual information
DBInterface.execute
— MethodDBInterface.execute(db::DB, sql::String, [params])
TODO: Support DBInterface statements
Take inputs given by db
and sql
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.
TODO: Support Tables.jl
DuckDB.close
— Methodclose(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.connect
— Methodconnect(path)
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.
path
: Path to the database file on disk or:memory:
to open an in-memory database.- returns: a connection handle
DuckDB.disconnect
— Methoddisconnect(connection)
Closes the specified connection and de-allocates all memory allocated for that connection.
connection
: The connection to close.
DuckDB.duckdb_append_blob
— MethodAppend a blob value to the appender.
DUCKDBAPI duckdbstate duckdbappendblob(duckdbappender appender, const void *data, idxt length);
DuckDB.duckdb_append_bool
— MethodAppend a bool value to the appender.
DUCKDBAPI duckdbstate duckdbappendbool(duckdb_appender appender, bool value);
DuckDB.duckdb_append_date
— MethodAppend a duckdb_date value to the appender.
DUCKDBAPI duckdbstate duckdbappenddate(duckdbappender appender, duckdbdate value);
DuckDB.duckdb_append_double
— MethodAppend a double value to the appender.
DUCKDBAPI duckdbstate duckdbappenddouble(duckdb_appender appender, double value);
DuckDB.duckdb_append_float
— MethodAppend a float value to the appender.
DUCKDBAPI duckdbstate duckdbappendfloat(duckdb_appender appender, float value);
DuckDB.duckdb_append_hugeint
— MethodAppend a duckdb_hugeint value to the appender.
DUCKDBAPI duckdbstate duckdbappendhugeint(duckdbappender appender, duckdbhugeint value);
DuckDB.duckdb_append_int16
— MethodAppend an int16_t value to the appender.
DUCKDBAPI duckdbstate duckdbappendint16(duckdbappender appender, int16t value);
DuckDB.duckdb_append_int32
— MethodAppend an int32_t value to the appender.
DUCKDBAPI duckdbstate duckdbappendint32(duckdbappender appender, int32t value);
DuckDB.duckdb_append_int64
— MethodAppend an int64_t value to the appender.
DUCKDBAPI duckdbstate duckdbappendint64(duckdbappender appender, int64t value);
DuckDB.duckdb_append_int8
— MethodAppend an int8_t value to the appender.
DUCKDBAPI duckdbstate duckdbappendint8(duckdbappender appender, int8t value);
DuckDB.duckdb_append_interval
— MethodAppend a duckdb_interval value to the appender.
DUCKDBAPI duckdbstate duckdbappendinterval(duckdbappender appender, duckdbinterval value);
DuckDB.duckdb_append_null
— MethodAppend a NULL value to the appender (of any type).
DUCKDBAPI duckdbstate duckdbappendnull(duckdb_appender appender);
DuckDB.duckdb_append_time
— MethodAppend a duckdb_time value to the appender.
DUCKDBAPI duckdbstate duckdbappendtime(duckdbappender appender, duckdbtime value);
DuckDB.duckdb_append_timestamp
— MethodAppend a duckdb_timestamp value to the appender.
DUCKDBAPI duckdbstate duckdbappendtimestamp(duckdbappender appender, duckdbtimestamp value);
DuckDB.duckdb_append_uint16
— MethodAppend a uint16_t value to the appender.
DUCKDBAPI duckdbstate duckdbappenduint16(duckdbappender appender, uint16t value);
DuckDB.duckdb_append_uint32
— MethodAppend a uint32_t value to the appender.
DUCKDBAPI duckdbstate duckdbappenduint32(duckdbappender appender, uint32t value);
DuckDB.duckdb_append_uint64
— MethodAppend a uint64_t value to the appender.
DUCKDBAPI duckdbstate duckdbappenduint64(duckdbappender appender, uint64t value);
DuckDB.duckdb_append_uint8
— MethodAppend a uint8_t value to the appender.
DUCKDBAPI duckdbstate duckdbappenduint8(duckdbappender appender, uint8t value);
DuckDB.duckdb_append_varchar
— MethodAppend a varchar value to the appender.
DUCKDBAPI duckdbstate duckdbappendvarchar(duckdb_appender appender, const char *val);
DuckDB.duckdb_append_varchar_length
— MethodAppend a varchar value to the appender.
DUCKDBAPI duckdbstate duckdbappendvarcharlength(duckdbappender appender, const char *val, idx_t length);
DuckDB.duckdb_appender_begin_row
— MethodA nop function, provided for backwards compatibility reasons. Does nothing. Only duckdb_appender_end_row
is required.
DUCKDBAPI duckdbstate duckdbappenderbeginrow(duckdbappender appender);
DuckDB.duckdb_appender_close
— MethodClose 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 orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbappenderclose(duckdb_appender appender);
DuckDB.duckdb_appender_create
— MethodCreates 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 orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbappendercreate(duckdbconnection connection, const char *schema, const char *table, duckdbappender *out_appender);
DuckDB.duckdb_appender_destroy
— MethodClose 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 orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbappenderdestroy(duckdb_appender *appender);
DuckDB.duckdb_appender_end_row
— MethodFinish the current row of appends. After end_row is called, the next row can be appended.
- appender: The appender.
- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbappenderendrow(duckdbappender appender);
DuckDB.duckdb_appender_error
— MethodReturns 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);
DuckDB.duckdb_appender_flush
— MethodFlush 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 orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbappenderflush(duckdb_appender appender);
DuckDB.duckdb_arrow_column_count
— MethodReturns the number of columns present in a the arrow result object.
- result: The result object.
- returns: The number of columns present in the result object.
DUCKDBAPI idxt duckdbarrowcolumncount(duckdbarrow result);
DuckDB.duckdb_arrow_row_count
— MethodReturns the number of rows present in a the arrow result object.
- result: The result object.
- returns: The number of rows present in the result object.
DUCKDBAPI idxt duckdbarrowrowcount(duckdbarrow result);
DuckDB.duckdb_arrow_rows_changed
— MethodReturns 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.
- result: The result object.
- returns: The number of rows changed.
DUCKDBAPI idxt duckdbarrowrowschanged(duckdbarrow result);
DuckDB.duckdb_bind_blob
— MethodBinds a blob value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindblob(duckdbpreparedstatement preparedstatement, idxt paramidx, const void *data, idxt length);
DuckDB.duckdb_bind_boolean
— MethodBinds a bool value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindboolean(duckdbpreparedstatement preparedstatement, idxt param_idx, bool val);
DuckDB.duckdb_bind_date
— MethodBinds a duckdb_date value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbinddate(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdbdate val);
DuckDB.duckdb_bind_double
— MethodBinds an double value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbinddouble(duckdbpreparedstatement preparedstatement, idxt param_idx, double val);
DuckDB.duckdb_bind_float
— MethodBinds an float value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindfloat(duckdbpreparedstatement preparedstatement, idxt param_idx, float val);
DuckDB.duckdb_bind_hugeint
— MethodBinds an duckdbhugeint value to the prepared statement at the specified index. */ DUCKDBAPI duckdbstate duckdbbindhugeint(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdb_hugeint val);
DuckDB.duckdb_bind_int16
— MethodBinds an int16_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindint16(duckdbpreparedstatement preparedstatement, idxt paramidx, int16t val);
DuckDB.duckdb_bind_int32
— MethodBinds an int32_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindint32(duckdbpreparedstatement preparedstatement, idxt paramidx, int32t val);
DuckDB.duckdb_bind_int64
— MethodBinds an int64_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindint64(duckdbpreparedstatement preparedstatement, idxt paramidx, int64t val);
DuckDB.duckdb_bind_int8
— MethodBinds an int8_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindint8(duckdbpreparedstatement preparedstatement, idxt paramidx, int8t val);
DuckDB.duckdb_bind_interval
— MethodBinds a duckdb_interval value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindinterval(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdbinterval val);
DuckDB.duckdb_bind_null
— MethodBinds a NULL value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindnull(duckdbpreparedstatement preparedstatement, idxt param_idx);
DuckDB.duckdb_bind_time
— MethodBinds a duckdb_time value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindtime(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdbtime val);
DuckDB.duckdb_bind_timestamp
— MethodBinds a duckdb_timestamp value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindtimestamp(duckdbpreparedstatement preparedstatement, idxt paramidx, duckdbtimestamp val);
DuckDB.duckdb_bind_uint16
— MethodBinds an uint16_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbinduint16(duckdbpreparedstatement preparedstatement, idxt paramidx, uint16t val);
DuckDB.duckdb_bind_uint32
— MethodBinds an uint32_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbinduint32(duckdbpreparedstatement preparedstatement, idxt paramidx, uint32t val);
DuckDB.duckdb_bind_uint64
— MethodBinds an uint64_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbinduint64(duckdbpreparedstatement preparedstatement, idxt paramidx, uint64t val);
DuckDB.duckdb_bind_uint8
— MethodBinds an uint8_t value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbinduint8(duckdbpreparedstatement preparedstatement, idxt paramidx, uint8t val);
DuckDB.duckdb_bind_varchar
— MethodBinds a null-terminated varchar value to the prepared statement at the specified index.
DUCKDBAPI duckdbstate duckdbbindvarchar(duckdbpreparedstatement preparedstatement, idxt param_idx, const char *val);
DuckDB.duckdb_bind_varchar_length
— MethodBinds 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.duckdb_close
— Methodduckdb_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.duckdb_column_count
— Methodduckdb_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.duckdb_column_data
— Methodduckdb_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 the
DUCKDBTYPE` 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]);
result
: The result object to fetch the column data from.col
: The column index.- returns: The column data of the specified column.
DuckDB.duckdb_column_name
— Methodduckdb_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.duckdb_column_type
— Methodduckdb_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.duckdb_config_count
— Methodduckdb_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.duckdb_connect
— Methodduckdb_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 orDuckDBError
on failure.
DuckDB.duckdb_create_config
— Methodduckdb_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 orDuckDBError
on failure.
DuckDB.duckdb_destroy_arrow
— MethodCloses the result and de-allocates all memory allocated for the arrow result.
- result: The result to destroy.
DUCKDBAPI void duckdbdestroyarrow(duckdbarrow *result);
DuckDB.duckdb_destroy_config
— Methodduckdb_destroy_config(config)
Destroys the specified configuration option and de-allocates all memory allocated for the object.
config
: The configuration object to destroy.
DuckDB.duckdb_destroy_prepare
— MethodCloses 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.duckdb_destroy_result
— Methodduckdb_destroy_result(result)
Closes the result and de-allocates all memory allocated for that connection.
result
: The result to destroy.
DuckDB.duckdb_disconnect
— Methodduckdb_disconnect(connection)
Closes the specified connection and de-allocates all memory allocated for that connection.
connection
: The connection to close.
DuckDB.duckdb_double_to_hugeint
— Methodduckdbdoubleto_hugeint(val)
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.
- val: The double value.
- returns: The converted
duckdb_hugeint
element.
DUCKDBAPI duckdbhugeint duckdbdoubleto_hugeint(double val);
DuckDB.duckdb_execute_prepared
— MethodExecutes 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 orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbexecuteprepared(duckdbpreparedstatement preparedstatement, duckdbresult *out_result);
DuckDB.duckdb_execute_prepared_arrow
— MethodExecutes the prepared statement with the given bound parameters, and returns an arrow query result.
- prepared_statement: The prepared statement to execute.
- out_result: The query result.
- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbexecutepreparedarrow(duckdbpreparedstatement preparedstatement, duckdbarrow *outresult);
DuckDB.duckdb_free
— Methodduckdb_free(ptr)
Free a value returned from duckdb_malloc
, duckdb_value_varchar
or duckdb_value_blob
.
- ptr: The memory region to de-allocate.
DUCKDBAPI void duckdbfree(void *ptr);
DuckDB.duckdb_from_date
— Methodduckdbfromdate(date)
Decompose a duckdb_date
object into year, month and date (stored as duckdb_date_struct
).
- date: The date object, as obtained from a
DUCKDB_TYPE_DATE
column. - returns: The
duckdb_date_struct
with the decomposed elements.
DUCKDBAPI duckdbdatestruct duckdbfromdate(duckdbdate date);
DuckDB.duckdb_from_time
— Methodduckdbfromtime(time)
Decompose a duckdb_time
object into hour, minute, second and microsecond (stored as duckdb_time_struct
).
- time: The time object, as obtained from a
DUCKDB_TYPE_TIME
column. - returns: The
duckdb_time_struct
with the decomposed elements.
DUCKDBAPI duckdbtimestruct duckdbfromtime(duckdbtime time);
DuckDB.duckdb_from_timestamp
— Methodduckdbfromtimestamp(ts)
Decompose a duckdb_timestamp
object into a duckdb_timestamp_struct
.
- ts: The ts object, as obtained from a
DUCKDB_TYPE_TIMESTAMP
column. - returns: The
duckdb_timestamp_struct
with the decomposed elements.
DUCKDBAPI duckdbtimestampstruct duckdbfromtimestamp(duckdbtimestamp ts);
DuckDB.duckdb_get_config_flag
— Methodduckdb_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 andduckdb_config_count
)out_name
: A name of the configuration flag.out_description
: A description of the configuration flag.- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DuckDB.duckdb_hugeint_to_double
— Methodduckdbhugeintto_double(val)
Converts a duckdbhugeint object (as obtained from a `DUCKDBTYPE_HUGEINT` column) into a double.
- val: The hugeint value.
- returns: The converted
double
element.
DUCKDBAPI double duckdbhugeinttodouble(duckdb_hugeint val);
DuckDB.duckdb_malloc
— Methodduckdb_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);
DuckDB.duckdb_nparams
— MethodReturns 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.duckdb_nullmask_data
— Methodduckdb_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.duckdb_open
— Methodduckdb_open(path, out_database)
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.
path
: Path to the database file on disk, ornullptr
or:memory:
to open an in-memory database.out_database
: The result database object.- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DuckDB.duckdb_param_type
— MethodReturns 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);
DuckDB.duckdb_prepare
— MethodCreate 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 orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbprepare(duckdbconnection connection, const char *query, duckdbpreparedstatement *outpreparedstatement);
DuckDB.duckdb_prepare_error
— MethodReturns 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.duckdb_query
— Methodduckdb_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 `duckdbresult_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.
connection
: The connection to perform the query in.query
: The SQL query to run.out_result
: The query result.- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DuckDB.duckdb_query_arrow
— MethodExecutes 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.
- connection: The connection to perform the query in.
- query: The SQL query to run.
- out_result: The query result.
- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbqueryarrow(duckdbconnection connection, const char *query, duckdbarrow *out_result);
DuckDB.duckdb_query_arrow_array
— MethodFetch an internal arrow array from the arrow result.
This function can be called multiple time to get next chunks, which will free the previous outarray. So consume the outarray before calling this function again.
- result: The result to fetch the array from.
- out_array: The output array.
- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbqueryarrowarray(duckdbarrow result, duckdbarrowarray *out_array);
DuckDB.duckdb_query_arrow_error
— MethodReturns 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.
- result: The result object to fetch the nullmask from.
- returns: The error of the result.
DUCKDBAPI const char *duckdbqueryarrowerror(duckdb_arrow result);
DuckDB.duckdb_query_arrow_schema
— MethodFetch the internal arrow schema from the arrow result.
- result: The result to fetch the schema from.
- out_schema: The output schema.
- returns:
DuckDBSuccess
on success orDuckDBError
on failure.
DUCKDBAPI duckdbstate duckdbqueryarrowschema(duckdbarrow result, duckdbarrowschema *out_schema);
DuckDB.duckdb_result_error
— Methodduckdb_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.
DuckDB.duckdb_row_count
— Methodduckdb_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.duckdb_rows_changed
— Methodduckdb_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.duckdb_set_config
— Methodduckdb_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 orDuckDBError
on failure.
DuckDB.duckdb_to_date
— Methodduckdbtodate(date)
Re-compose a duckdb_date
from year, month and date (duckdb_date_struct
).
- date: The year, month and date stored in a
duckdb_date_struct
. - returns: The
duckdb_date
element.
DUCKDBAPI duckdbdate duckdbtodate(duckdbdatestruct date);
DuckDB.duckdb_to_time
— Methodduckdbtotime(time)
Re-compose a duckdb_time
from hour, minute, second and microsecond (duckdb_time_struct
).
- time: The hour, minute, second and microsecond in a
duckdb_time_struct
. - returns: The
duckdb_time
element.
DUCKDBAPI duckdbtime duckdbtotime(duckdbtimestruct time);
DuckDB.duckdb_to_timestamp
— Methodduckdbtotimestamp(ts)
Re-compose a duckdb_timestamp
from a duckdbtimestampstruct.
- ts: The de-composed elements in a
duckdb_timestamp_struct
. - returns: The
duckdb_timestamp
element.
*/ DUCKDBAPI duckdbtimestamp duckdbtotimestamp(duckdbtimestampstruct ts);
DuckDB.duckdb_value_blob
— Methodduckdbvalueblob(result,col,row)
- 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.
DUCKDBAPI duckdbblob duckdbvalueblob(duckdbresult *result, idxt col, idx_t row);
DuckDB.duckdb_value_boolean
— Methodduckdb_value_boolean(result,col,row)
- returns: The boolean value at the specified location, or false if the value cannot be converted.
DuckDB.duckdb_value_date
— Methodduckdbvaluedate(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.duckdb_value_double
— Methodduckdb_value_double(result,col,row)
- returns: The double value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_float
— Methodduckdb_value_float(result,col,row)
- returns: The float value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_hugeint
— Methodduckdb_value_hugeint(result,col,row)
- returns: The duckdb_hugeint value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_int16
— Methodduckdb_value_int16(result,col,row)
- returns: The int16_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_int32
— Methodduckdb_value_int32(result,col,row)
- returns: The int32_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_int64
— Methodduckdb_value_int64(result,col,row)
- returns: The int64_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_int8
— Methodduckdb_value_int8(result,col,row)
- returns: The int8_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_interval
— Methodduckdbvalueinterval(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);
DuckDB.duckdb_value_is_null
— Methodduckdbvalueis_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);
DuckDB.duckdb_value_time
— Methodduckdbvaluetime(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);
DuckDB.duckdb_value_timestamp
— Methodduckdbvaluetimestamp(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.duckdb_value_uint16
— Methodduckdb_value_uint16(result,col,row)
- returns: The uint16_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_uint32
— Methodduckdb_value_uint32(result,col,row)
- returns: The uint32_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_uint64
— Methodduckdb_value_uint64(result,col,row)
- returns: The uint64_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_uint8
— Methodduckdb_value_uint8(result,col,row)
- returns: The uint8_t value at the specified location, or 0 if the value cannot be converted.
DuckDB.duckdb_value_varchar
— Methodduckdbvaluevarchar(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);
DuckDB.duckdb_value_varchar_internal
— Methodduckdbvaluevarchar_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);
DuckDB.execute
— Methodexecute(connection, query)
Executes a SQL query within a connection and returns the full (materialized) result. 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 duckdbquery, duckdbdestroy_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.
connection
: The connection to perform the query in.query
: The SQL query to run.- returns: the full result pointer
DuckDB.toDataFrame
— MethodtoDataFrame(result::Ref{duckdb_result})::DataFrame
Creates a DataFrame from the full result
result
: the full result fromexecute
- returns: the abstract dataframe
DuckDB.toDataFrame
— MethodtoDataFrame(connection::Ref{Ptr{Cvoid}},query::String)::DataFrame
Creates a DataFrame from a SQL query within a connection.
connection
: The connection to perform the query in.query
: The SQL query to run.- returns: the abstract dataframe