diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c52b694..8ebdecf 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -19,7 +19,7 @@ env: SCONS_CACHE: ${{ github.workspace }}/.scons-cache/ EM_VERSION: 3.1.39 EM_CACHE_FOLDER: "emsdk-cache" - DUCKDB_BASE_URL: https://github.com/duckdb/duckdb/releases/download/v1.0.0/ + DUCKDB_BASE_URL: https://github.com/duckdb/duckdb/releases/download/v1.1.2/ jobs: matrix: diff --git a/src/duckdb/duckdb.h b/src/duckdb/duckdb.h index 395befc..7a307fa 100644 --- a/src/duckdb/duckdb.h +++ b/src/duckdb/duckdb.h @@ -6,17 +6,25 @@ // // //===----------------------------------------------------------------------===// +// +// !!!!!!! +// WARNING: this file is autogenerated by scripts/generate_c_api.py, manual changes will be overwritten +// !!!!!!! #pragma once //! duplicate of duckdb/main/winapi.hpp #ifndef DUCKDB_API #ifdef _WIN32 +#ifdef DUCKDB_STATIC_BUILD +#define DUCKDB_API +#else #if defined(DUCKDB_BUILD_LIBRARY) && !defined(DUCKDB_BUILD_LOADABLE_EXTENSION) #define DUCKDB_API __declspec(dllexport) #else #define DUCKDB_API __declspec(dllimport) #endif +#endif #else #define DUCKDB_API #endif @@ -25,41 +33,20 @@ //! duplicate of duckdb/main/winapi.hpp #ifndef DUCKDB_EXTENSION_API #ifdef _WIN32 +#ifdef DUCKDB_STATIC_BUILD +#define DUCKDB_EXTENSION_API +#else #ifdef DUCKDB_BUILD_LOADABLE_EXTENSION #define DUCKDB_EXTENSION_API __declspec(dllexport) #else #define DUCKDB_EXTENSION_API #endif +#endif #else #define DUCKDB_EXTENSION_API __attribute__((visibility("default"))) #endif #endif -//! In the future, we are planning to move extension functions to a separate header. For now you can set the define -//! below to remove the functions that are planned to be moved out of this header. -// #define DUCKDB_NO_EXTENSION_FUNCTIONS - -//! Set the define below to remove all functions that are deprecated or planned to be deprecated -// #define DUCKDB_API_NO_DEPRECATED - -//! API versions -//! If no explicit API version is defined, the latest API version is used. -//! Note that using older API versions (i.e. not using DUCKDB_API_LATEST) is deprecated. -//! These will not be supported long-term, and will be removed in future versions. -#ifndef DUCKDB_API_0_3_1 -#define DUCKDB_API_0_3_1 1 -#endif -#ifndef DUCKDB_API_0_3_2 -#define DUCKDB_API_0_3_2 2 -#endif -#ifndef DUCKDB_API_LATEST -#define DUCKDB_API_LATEST DUCKDB_API_0_3_2 -#endif - -#ifndef DUCKDB_API_VERSION -#define DUCKDB_API_VERSION DUCKDB_API_LATEST -#endif - #include #include #include @@ -142,25 +129,31 @@ typedef enum DUCKDB_TYPE { DUCKDB_TYPE_TIME_TZ = 30, // duckdb_timestamp DUCKDB_TYPE_TIMESTAMP_TZ = 31, + // ANY type + DUCKDB_TYPE_ANY = 34, + // duckdb_varint + DUCKDB_TYPE_VARINT = 35, + // SQLNULL type + DUCKDB_TYPE_SQLNULL = 36, } duckdb_type; //! An enum over the returned state of different functions. -typedef enum { DuckDBSuccess = 0, DuckDBError = 1 } duckdb_state; +typedef enum duckdb_state { DuckDBSuccess = 0, DuckDBError = 1 } duckdb_state; //! An enum over the pending state of a pending query result. -typedef enum { +typedef enum duckdb_pending_state { DUCKDB_PENDING_RESULT_READY = 0, DUCKDB_PENDING_RESULT_NOT_READY = 1, DUCKDB_PENDING_ERROR = 2, DUCKDB_PENDING_NO_TASKS_AVAILABLE = 3 } duckdb_pending_state; //! An enum over DuckDB's different result types. -typedef enum { +typedef enum duckdb_result_type { DUCKDB_RESULT_TYPE_INVALID = 0, DUCKDB_RESULT_TYPE_CHANGED_ROWS = 1, DUCKDB_RESULT_TYPE_NOTHING = 2, DUCKDB_RESULT_TYPE_QUERY_RESULT = 3, } duckdb_result_type; //! An enum over DuckDB's different statement types. -typedef enum { +typedef enum duckdb_statement_type { DUCKDB_STATEMENT_TYPE_INVALID = 0, DUCKDB_STATEMENT_TYPE_SELECT = 1, DUCKDB_STATEMENT_TYPE_INSERT = 2, @@ -190,6 +183,54 @@ typedef enum { DUCKDB_STATEMENT_TYPE_DETACH = 26, DUCKDB_STATEMENT_TYPE_MULTI = 27, } duckdb_statement_type; +//! An enum over DuckDB's different result types. +typedef enum duckdb_error_type { + DUCKDB_ERROR_INVALID = 0, + DUCKDB_ERROR_OUT_OF_RANGE = 1, + DUCKDB_ERROR_CONVERSION = 2, + DUCKDB_ERROR_UNKNOWN_TYPE = 3, + DUCKDB_ERROR_DECIMAL = 4, + DUCKDB_ERROR_MISMATCH_TYPE = 5, + DUCKDB_ERROR_DIVIDE_BY_ZERO = 6, + DUCKDB_ERROR_OBJECT_SIZE = 7, + DUCKDB_ERROR_INVALID_TYPE = 8, + DUCKDB_ERROR_SERIALIZATION = 9, + DUCKDB_ERROR_TRANSACTION = 10, + DUCKDB_ERROR_NOT_IMPLEMENTED = 11, + DUCKDB_ERROR_EXPRESSION = 12, + DUCKDB_ERROR_CATALOG = 13, + DUCKDB_ERROR_PARSER = 14, + DUCKDB_ERROR_PLANNER = 15, + DUCKDB_ERROR_SCHEDULER = 16, + DUCKDB_ERROR_EXECUTOR = 17, + DUCKDB_ERROR_CONSTRAINT = 18, + DUCKDB_ERROR_INDEX = 19, + DUCKDB_ERROR_STAT = 20, + DUCKDB_ERROR_CONNECTION = 21, + DUCKDB_ERROR_SYNTAX = 22, + DUCKDB_ERROR_SETTINGS = 23, + DUCKDB_ERROR_BINDER = 24, + DUCKDB_ERROR_NETWORK = 25, + DUCKDB_ERROR_OPTIMIZER = 26, + DUCKDB_ERROR_NULL_POINTER = 27, + DUCKDB_ERROR_IO = 28, + DUCKDB_ERROR_INTERRUPT = 29, + DUCKDB_ERROR_FATAL = 30, + DUCKDB_ERROR_INTERNAL = 31, + DUCKDB_ERROR_INVALID_INPUT = 32, + DUCKDB_ERROR_OUT_OF_MEMORY = 33, + DUCKDB_ERROR_PERMISSION = 34, + DUCKDB_ERROR_PARAMETER_NOT_RESOLVED = 35, + DUCKDB_ERROR_PARAMETER_NOT_ALLOWED = 36, + DUCKDB_ERROR_DEPENDENCY = 37, + DUCKDB_ERROR_HTTP = 38, + DUCKDB_ERROR_MISSING_EXTENSION = 39, + DUCKDB_ERROR_AUTOLOAD = 40, + DUCKDB_ERROR_SEQUENCE = 41, + DUCKDB_INVALID_CONFIGURATION = 42 +} duckdb_error_type; +//! An enum over DuckDB's different cast modes. +typedef enum duckdb_cast_mode { DUCKDB_CAST_NORMAL = 0, DUCKDB_CAST_TRY = 1 } duckdb_cast_mode; //===--------------------------------------------------------------------===// // General type definitions @@ -313,28 +354,21 @@ typedef struct { //! duckdb_column_type, and duckdb_column_name, which take the result and the column index //! as their parameters typedef struct { -#if DUCKDB_API_VERSION < DUCKDB_API_0_3_2 - void *data; - bool *nullmask; - duckdb_type type; - char *name; -#else // deprecated, use duckdb_column_data - void *__deprecated_data; + void *deprecated_data; // deprecated, use duckdb_nullmask_data - bool *__deprecated_nullmask; + bool *deprecated_nullmask; // deprecated, use duckdb_column_type - duckdb_type __deprecated_type; + duckdb_type deprecated_type; // deprecated, use duckdb_column_name - char *__deprecated_name; -#endif + char *deprecated_name; void *internal_data; } duckdb_column; //! A vector to a specified column in a data chunk. Lives as long as the //! data chunk lives, i.e., must not be destroyed. typedef struct _duckdb_vector { - void *__vctr; + void *internal_ptr; } * duckdb_vector; //===--------------------------------------------------------------------===// @@ -358,100 +392,177 @@ typedef struct { //! A query result consists of a pointer to its internal data. //! Must be freed with 'duckdb_destroy_result'. typedef struct { -#if DUCKDB_API_VERSION < DUCKDB_API_0_3_2 - idx_t column_count; - idx_t row_count; - idx_t rows_changed; - duckdb_column *columns; - char *error_message; -#else // deprecated, use duckdb_column_count - idx_t __deprecated_column_count; + idx_t deprecated_column_count; // deprecated, use duckdb_row_count - idx_t __deprecated_row_count; + idx_t deprecated_row_count; // deprecated, use duckdb_rows_changed - idx_t __deprecated_rows_changed; + idx_t deprecated_rows_changed; // deprecated, use duckdb_column_*-family of functions - duckdb_column *__deprecated_columns; + duckdb_column *deprecated_columns; // deprecated, use duckdb_result_error - char *__deprecated_error_message; -#endif + char *deprecated_error_message; void *internal_data; } duckdb_result; //! A database object. Should be closed with `duckdb_close`. typedef struct _duckdb_database { - void *__db; + void *internal_ptr; } * duckdb_database; //! A connection to a duckdb database. Must be closed with `duckdb_disconnect`. typedef struct _duckdb_connection { - void *__conn; + void *internal_ptr; } * duckdb_connection; //! A prepared statement is a parameterized query that allows you to bind parameters to it. //! Must be destroyed with `duckdb_destroy_prepare`. typedef struct _duckdb_prepared_statement { - void *__prep; + void *internal_ptr; } * duckdb_prepared_statement; //! Extracted statements. Must be destroyed with `duckdb_destroy_extracted`. typedef struct _duckdb_extracted_statements { - void *__extrac; + void *internal_ptr; } * duckdb_extracted_statements; //! The pending result represents an intermediate structure for a query that is not yet fully executed. //! Must be destroyed with `duckdb_destroy_pending`. typedef struct _duckdb_pending_result { - void *__pend; + void *internal_ptr; } * duckdb_pending_result; //! The appender enables fast data loading into DuckDB. //! Must be destroyed with `duckdb_appender_destroy`. typedef struct _duckdb_appender { - void *__appn; + void *internal_ptr; } * duckdb_appender; +//! The table description allows querying info about the table. +//! Must be destroyed with `duckdb_table_description_destroy`. +typedef struct _duckdb_table_description { + void *internal_ptr; +} * duckdb_table_description; + //! Can be used to provide start-up options for the DuckDB instance. //! Must be destroyed with `duckdb_destroy_config`. typedef struct _duckdb_config { - void *__cnfg; + void *internal_ptr; } * duckdb_config; //! Holds an internal logical type. //! Must be destroyed with `duckdb_destroy_logical_type`. typedef struct _duckdb_logical_type { - void *__lglt; + void *internal_ptr; } * duckdb_logical_type; +//! Holds extra information used when registering a custom logical type. +//! Reserved for future use. +typedef struct _duckdb_create_type_info { + void *internal_ptr; +} * duckdb_create_type_info; + //! Contains a data chunk from a duckdb_result. //! Must be destroyed with `duckdb_destroy_data_chunk`. typedef struct _duckdb_data_chunk { - void *__dtck; + void *internal_ptr; } * duckdb_data_chunk; //! Holds a DuckDB value, which wraps a type. //! Must be destroyed with `duckdb_destroy_value`. typedef struct _duckdb_value { - void *__val; + void *internal_ptr; } * duckdb_value; +//! Holds a recursive tree that matches the query plan. +typedef struct _duckdb_profiling_info { + void *internal_ptr; +} * duckdb_profiling_info; + +//===--------------------------------------------------------------------===// +// C API Extension info +//===--------------------------------------------------------------------===// +//! Holds state during the C API extension intialization process +typedef struct _duckdb_extension_info { + void *internal_ptr; +} * duckdb_extension_info; + +//===--------------------------------------------------------------------===// +// Function types +//===--------------------------------------------------------------------===// +//! Additional function info. When setting this info, it is necessary to pass a destroy-callback function. +typedef struct _duckdb_function_info { + void *internal_ptr; +} * duckdb_function_info; + +//===--------------------------------------------------------------------===// +// Scalar function types +//===--------------------------------------------------------------------===// +//! A scalar function. Must be destroyed with `duckdb_destroy_scalar_function`. +typedef struct _duckdb_scalar_function { + void *internal_ptr; +} * duckdb_scalar_function; + +//! A scalar function set. Must be destroyed with `duckdb_destroy_scalar_function_set`. +typedef struct _duckdb_scalar_function_set { + void *internal_ptr; +} * duckdb_scalar_function_set; + +//! The main function of the scalar function. +typedef void (*duckdb_scalar_function_t)(duckdb_function_info info, duckdb_data_chunk input, duckdb_vector output); + +//===--------------------------------------------------------------------===// +// Aggregate function types +//===--------------------------------------------------------------------===// +//! An aggregate function. Must be destroyed with `duckdb_destroy_aggregate_function`. +typedef struct _duckdb_aggregate_function { + void *internal_ptr; +} * duckdb_aggregate_function; + +//! A aggregate function set. Must be destroyed with `duckdb_destroy_aggregate_function_set`. +typedef struct _duckdb_aggregate_function_set { + void *internal_ptr; +} * duckdb_aggregate_function_set; + +//! Aggregate state +typedef struct _duckdb_aggregate_state { + void *internal_ptr; +} * duckdb_aggregate_state; + +//! Returns the aggregate state size +typedef idx_t (*duckdb_aggregate_state_size)(duckdb_function_info info); +//! Initialize the aggregate state +typedef void (*duckdb_aggregate_init_t)(duckdb_function_info info, duckdb_aggregate_state state); +//! Destroy aggregate state (optional) +typedef void (*duckdb_aggregate_destroy_t)(duckdb_aggregate_state *states, idx_t count); +//! Update a set of aggregate states with new values +typedef void (*duckdb_aggregate_update_t)(duckdb_function_info info, duckdb_data_chunk input, + duckdb_aggregate_state *states); +//! Combine aggregate states +typedef void (*duckdb_aggregate_combine_t)(duckdb_function_info info, duckdb_aggregate_state *source, + duckdb_aggregate_state *target, idx_t count); +//! Finalize aggregate states into a result vector +typedef void (*duckdb_aggregate_finalize_t)(duckdb_function_info info, duckdb_aggregate_state *source, + duckdb_vector result, idx_t count, idx_t offset); + //===--------------------------------------------------------------------===// // Table function types //===--------------------------------------------------------------------===// -#ifndef DUCKDB_NO_EXTENSION_FUNCTIONS //! A table function. Must be destroyed with `duckdb_destroy_table_function`. -typedef void *duckdb_table_function; +typedef struct _duckdb_table_function { + void *internal_ptr; +} * duckdb_table_function; //! The bind info of the function. When setting this info, it is necessary to pass a destroy-callback function. -typedef void *duckdb_bind_info; +typedef struct _duckdb_bind_info { + void *internal_ptr; +} * duckdb_bind_info; //! Additional function init info. When setting this info, it is necessary to pass a destroy-callback function. -typedef void *duckdb_init_info; - -//! Additional function info. When setting this info, it is necessary to pass a destroy-callback function. -typedef void *duckdb_function_info; +typedef struct _duckdb_init_info { + void *internal_ptr; +} * duckdb_init_info; //! The bind function of the table function. typedef void (*duckdb_table_function_bind_t)(duckdb_bind_info info); @@ -462,16 +573,29 @@ typedef void (*duckdb_table_function_init_t)(duckdb_init_info info); //! The main function of the table function. typedef void (*duckdb_table_function_t)(duckdb_function_info info, duckdb_data_chunk output); +//===--------------------------------------------------------------------===// +// Cast types +//===--------------------------------------------------------------------===// + +//! A cast function. Must be destroyed with `duckdb_destroy_cast_function`. +typedef struct _duckdb_cast_function { + void *internal_ptr; +} * duckdb_cast_function; + +typedef bool (*duckdb_cast_function_t)(duckdb_function_info info, idx_t count, duckdb_vector input, + duckdb_vector output); + //===--------------------------------------------------------------------===// // Replacement scan types //===--------------------------------------------------------------------===// //! Additional replacement scan info. When setting this info, it is necessary to pass a destroy-callback function. -typedef void *duckdb_replacement_scan_info; +typedef struct _duckdb_replacement_scan_info { + void *internal_ptr; +} * duckdb_replacement_scan_info; //! A replacement scan function that can be added to a database. typedef void (*duckdb_replacement_callback_t)(duckdb_replacement_scan_info info, const char *table_name, void *data); -#endif //===--------------------------------------------------------------------===// // Arrow-related types @@ -479,30 +603,43 @@ typedef void (*duckdb_replacement_callback_t)(duckdb_replacement_scan_info info, //! Holds an arrow query result. Must be destroyed with `duckdb_destroy_arrow`. typedef struct _duckdb_arrow { - void *__arrw; + void *internal_ptr; } * duckdb_arrow; //! Holds an arrow array stream. Must be destroyed with `duckdb_destroy_arrow_stream`. typedef struct _duckdb_arrow_stream { - void *__arrwstr; + void *internal_ptr; } * duckdb_arrow_stream; //! Holds an arrow schema. Remember to release the respective ArrowSchema object. typedef struct _duckdb_arrow_schema { - void *__arrs; + void *internal_ptr; } * duckdb_arrow_schema; //! Holds an arrow array. Remember to release the respective ArrowArray object. typedef struct _duckdb_arrow_array { - void *__arra; + void *internal_ptr; } * duckdb_arrow_array; +//===--------------------------------------------------------------------===// +// DuckDB extension access +//===--------------------------------------------------------------------===// +//! Passed to C API extension as parameter to the entrypoint +struct duckdb_extension_access { + //! Indicate that an error has occured + void (*set_error)(duckdb_extension_info info, const char *error); + //! Fetch the database from duckdb to register extensions to + duckdb_database *(*get_database)(duckdb_extension_info info); + //! Fetch the API + const void *(*get_api)(duckdb_extension_info info, const char *version); +}; + //===--------------------------------------------------------------------===// // Functions //===--------------------------------------------------------------------===// //===--------------------------------------------------------------------===// -// Open/Connect +// Open Connect //===--------------------------------------------------------------------===// /*! @@ -510,9 +647,9 @@ Creates a new database or opens an existing database file stored at the given pa If no path is given a new in-memory database is created instead. The instantiated database should be closed with 'duckdb_close'. -* 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. +* @param path Path to the database file on disk, or `nullptr` or `:memory:` to open an in-memory database. +* @param out_database The result database object. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_open(const char *path, duckdb_database *out_database); @@ -520,12 +657,12 @@ DUCKDB_API duckdb_state duckdb_open(const char *path, duckdb_database *out_datab Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the given path. The instantiated database should be closed with 'duckdb_close'. -* 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. +* @param path Path to the database file on disk, or `nullptr` or `:memory:` to open an in-memory database. +* @param out_database The result database object. +* @param config (Optional) configuration used to start up the database system. +* @param 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. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config, char **out_error); @@ -536,7 +673,7 @@ This should be called after you are done with any database allocated through `du 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. +* @param database The database object to shut down. */ DUCKDB_API void duckdb_close(duckdb_database *database); @@ -545,31 +682,31 @@ Opens a connection to a database. Connections are required to query the database associated with the connection. The instantiated connection should be closed using 'duckdb_disconnect'. -* database: The database file to connect to. -* out_connection: The result connection object. -* returns: `DuckDBSuccess` on success or `DuckDBError` on failure. +* @param database The database file to connect to. +* @param out_connection The result connection object. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection); /*! Interrupt running query -* connection: The connection to interrupt +* @param connection The connection to interrupt */ DUCKDB_API void duckdb_interrupt(duckdb_connection connection); /*! Get progress of the running query -* connection: The working connection -* returns: -1 if no progress or a percentage of the progress +* @param connection The working connection +* @return -1 if no progress or a percentage of the progress */ DUCKDB_API duckdb_query_progress_type duckdb_query_progress(duckdb_connection connection); /*! Closes the specified connection and de-allocates all memory allocated for that connection. -* connection: The connection to close. +* @param connection The connection to close. */ DUCKDB_API void duckdb_disconnect(duckdb_connection *connection); @@ -591,8 +728,11 @@ The duckdb_config must be destroyed using 'duckdb_destroy_config' This will always succeed unless there is a malloc failure. -* out_config: The result configuration object. -* returns: `DuckDBSuccess` on success or `DuckDBError` on failure. +Note that `duckdb_destroy_config` should always be called on the resulting config, even if the function returns +`DuckDBError`. + +* @param out_config The result configuration object. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_create_config(duckdb_config *out_config); @@ -601,7 +741,7 @@ This returns the total amount of configuration options available for usage with This should not be called in a loop as it internally loops over all the options. -* returns: The amount of config options available. +* @return The amount of config options available. */ DUCKDB_API size_t duckdb_config_count(); @@ -611,10 +751,10 @@ display configuration options. This will succeed unless `index` is out of range 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. +* @param index The index of the configuration option (between 0 and `duckdb_config_count`) +* @param out_name A name of the configuration flag. +* @param out_description A description of the configuration flag. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_get_config_flag(size_t index, const char **out_name, const char **out_description); @@ -626,17 +766,17 @@ 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. +* @param config The configuration object to set the option on. +* @param name The name of the configuration flag to set. +* @param option The value to set the configuration flag to. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_set_config(duckdb_config config, const char *name, const char *option); /*! Destroys the specified configuration object and de-allocates all memory allocated for the object. -* config: The configuration object to destroy. +* @param config The configuration object to destroy. */ DUCKDB_API void duckdb_destroy_config(duckdb_config *config); @@ -652,17 +792,17 @@ If the query fails to execute, DuckDBError is returned and the error message can 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 or `DuckDBError` on failure. +* @param connection The connection to perform the query in. +* @param query The SQL query to run. +* @param out_result The query result. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_query(duckdb_connection connection, const char *query, duckdb_result *out_result); /*! Closes the result and de-allocates all memory allocated for that connection. -* result: The result to destroy. +* @param result The result to destroy. */ DUCKDB_API void duckdb_destroy_result(duckdb_result *result); @@ -672,9 +812,9 @@ 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. +* @param result The result object to fetch the column name from. +* @param col The column index. +* @return The column name of the specified column. */ DUCKDB_API const char *duckdb_column_name(duckdb_result *result, idx_t col); @@ -683,18 +823,18 @@ 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. +* @param result The result object to fetch the column type from. +* @param col The column index. +* @return The column type of the specified column. */ DUCKDB_API duckdb_type duckdb_column_type(duckdb_result *result, idx_t col); /*! Returns the statement type of the statement that was executed -* result: The result object to fetch the statement type from. - * returns: duckdb_statement_type value or DUCKDB_STATEMENT_TYPE_INVALID - */ +* @param result The result object to fetch the statement type from. +* @return duckdb_statement_type value or DUCKDB_STATEMENT_TYPE_INVALID +*/ DUCKDB_API duckdb_statement_type duckdb_result_statement_type(duckdb_result result); /*! @@ -704,17 +844,17 @@ The return type of this call should be destroyed with `duckdb_destroy_logical_ty 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. +* @param result The result object to fetch the column type from. +* @param col The column index. +* @return The logical column type of the specified column. */ DUCKDB_API duckdb_logical_type duckdb_column_logical_type(duckdb_result *result, idx_t col); /*! 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. +* @param result The result object. +* @return The number of columns present in the result object. */ DUCKDB_API idx_t duckdb_column_count(duckdb_result *result); @@ -724,18 +864,18 @@ DUCKDB_API idx_t duckdb_column_count(duckdb_result *result); Returns the number of rows present in the result object. -* result: The result object. -* returns: The number of rows present in the result object. +* @param result The result object. +* @return The number of rows present in the result object. */ DUCKDB_API idx_t duckdb_row_count(duckdb_result *result); -#endif +#endif /*! 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. +* @param result The result object. +* @return The number of rows changed. */ DUCKDB_API idx_t duckdb_rows_changed(duckdb_result *result); @@ -755,9 +895,9 @@ 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. +* @param result The result object to fetch the column data from. +* @param col The column index. +* @return The column data of the specified column. */ DUCKDB_API void *duckdb_column_data(duckdb_result *result, idx_t col); @@ -778,26 +918,36 @@ if (nullmask[row]) { } ``` -* result: The result object to fetch the nullmask from. -* col: The column index. -* returns: The nullmask of the specified column. +* @param result The result object to fetch the nullmask from. +* @param col The column index. +* @return The nullmask of the specified column. */ DUCKDB_API bool *duckdb_nullmask_data(duckdb_result *result, idx_t col); -#endif +#endif /*! 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 error from. -* returns: The error of the result. +* @param result The result object to fetch the error from. +* @return The error of the result. */ DUCKDB_API const char *duckdb_result_error(duckdb_result *result); +/*! +Returns the result error type contained within the result. The error is only set if `duckdb_query` returns +`DuckDBError`. + +* @param result The result object to fetch the error from. +* @return The error type of the result. +*/ +DUCKDB_API duckdb_error_type duckdb_result_error_type(duckdb_result *result); + //===--------------------------------------------------------------------===// // Result Functions //===--------------------------------------------------------------------===// + #ifndef DUCKDB_API_NO_DEPRECATED /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. @@ -814,9 +964,9 @@ 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. +* @param result The result object to fetch the data chunk from. +* @param chunk_index The chunk index to fetch from. +* @return The resulting data chunk. Returns `NULL` if the chunk index is out of bounds. */ DUCKDB_API duckdb_data_chunk duckdb_result_get_chunk(duckdb_result result, idx_t chunk_index); @@ -825,8 +975,8 @@ DUCKDB_API duckdb_data_chunk duckdb_result_get_chunk(duckdb_result result, idx_t 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 +* @param result The result object to check. +* @return Whether or not the result object is of the type StreamQueryResult */ DUCKDB_API bool duckdb_result_is_streaming(duckdb_result result); @@ -835,159 +985,160 @@ DUCKDB_API bool duckdb_result_is_streaming(duckdb_result result); Returns the number of data chunks present in the result. -* result: The result object -* returns: Number of data chunks present in the result. +* @param result The result object +* @return Number of data chunks present in the result. */ DUCKDB_API idx_t duckdb_result_chunk_count(duckdb_result result); -#endif +#endif /*! Returns the return_type of the given result, or DUCKDB_RETURN_TYPE_INVALID on error -* result: The result object -* returns: The return_type - */ +* @param result The result object +* @return The return_type +*/ DUCKDB_API duckdb_result_type duckdb_result_return_type(duckdb_result result); -#ifndef DUCKDB_API_NO_DEPRECATED //===--------------------------------------------------------------------===// -// Safe fetch functions +// Safe Fetch Functions //===--------------------------------------------------------------------===// // These functions will perform conversions if necessary. // On failure (e.g. if conversion cannot be performed or if the value is NULL) a default value is returned. // Note that these functions are slow since they perform bounds checking and conversion // For fast access of values prefer using `duckdb_result_get_chunk` - +#ifndef DUCKDB_API_NO_DEPRECATED /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The boolean value at the specified location, or false if the value cannot be converted. - */ +* @return The boolean value at the specified location, or false if the value cannot be converted. +*/ DUCKDB_API bool duckdb_value_boolean(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The int8_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The int8_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API int8_t duckdb_value_int8(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The int16_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The int16_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API int16_t duckdb_value_int16(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The int32_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The int32_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API int32_t duckdb_value_int32(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The int64_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The int64_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API int64_t duckdb_value_int64(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The duckdb_hugeint value at the specified location, or 0 if the value cannot be converted. - */ +* @return The duckdb_hugeint value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API duckdb_hugeint duckdb_value_hugeint(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The duckdb_uhugeint value at the specified location, or 0 if the value cannot be converted. - */ +* @return The duckdb_uhugeint value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API duckdb_uhugeint duckdb_value_uhugeint(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The duckdb_decimal value at the specified location, or 0 if the value cannot be converted. - */ +* @return The duckdb_decimal value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API duckdb_decimal duckdb_value_decimal(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The uint8_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The uint8_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API uint8_t duckdb_value_uint8(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The uint16_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The uint16_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API uint16_t duckdb_value_uint16(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The uint32_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The uint32_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API uint32_t duckdb_value_uint32(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The uint64_t value at the specified location, or 0 if the value cannot be converted. - */ +* @return The uint64_t value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API uint64_t duckdb_value_uint64(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The float value at the specified location, or 0 if the value cannot be converted. - */ +* @return The float value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API float duckdb_value_float(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The double value at the specified location, or 0 if the value cannot be converted. - */ +* @return The double value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API double duckdb_value_double(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The duckdb_date value at the specified location, or 0 if the value cannot be converted. - */ +* @return The duckdb_date value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API duckdb_date duckdb_value_date(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The duckdb_time value at the specified location, or 0 if the value cannot be converted. - */ +* @return The duckdb_time value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API duckdb_time duckdb_value_time(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The duckdb_timestamp value at the specified location, or 0 if the value cannot be converted. - */ +* @return The duckdb_timestamp value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API duckdb_timestamp duckdb_value_timestamp(duckdb_result *result, idx_t col, idx_t row); /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The duckdb_interval value at the specified location, or 0 if the value cannot be converted. - */ +* @return The duckdb_interval value at the specified location, or 0 if the value cannot be converted. +*/ DUCKDB_API duckdb_interval duckdb_value_interval(duckdb_result *result, idx_t col, idx_t row); /*! -* DEPRECATED: use duckdb_value_string instead. This function does not work correctly if the string contains null bytes. -* returns: The text value at the specified location as a null-terminated string, or nullptr if the value cannot be +**DEPRECATED**: Use duckdb_value_string instead. This function does not work correctly if the string contains null +bytes. + +* @return The text value at the specified location as a null-terminated string, or nullptr if the value cannot be converted. The result must be freed with `duckdb_free`. */ DUCKDB_API char *duckdb_value_varchar(duckdb_result *result, idx_t col, idx_t row); @@ -995,16 +1146,18 @@ DUCKDB_API char *duckdb_value_varchar(duckdb_result *result, idx_t col, idx_t ro /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: The string value at the specified location. Attempts to cast the result value to string. - * No support for nested types, and for other complex types. - * The resulting field "string.data" must be freed with `duckdb_free.` - */ +No support for nested types, and for other complex types. +The resulting field "string.data" must be freed with `duckdb_free.` + +* @return The string value at the specified location. Attempts to cast the result value to string. +*/ DUCKDB_API duckdb_string duckdb_value_string(duckdb_result *result, idx_t col, idx_t row); /*! -* DEPRECATED: use duckdb_value_string_internal instead. This function does not work correctly if the string contains +**DEPRECATED**: Use duckdb_value_string_internal instead. This function does not work correctly if the string contains null bytes. -* returns: The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast. + +* @return 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. @@ -1012,9 +1165,9 @@ The result must NOT be freed. DUCKDB_API char *duckdb_value_varchar_internal(duckdb_result *result, idx_t col, idx_t row); /*! -* DEPRECATED: use duckdb_value_string_internal instead. This function does not work correctly if the string contains +**DEPRECATED**: Use duckdb_value_string_internal instead. This function does not work correctly if the string contains null bytes. -* returns: The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast. +* @return 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. @@ -1024,7 +1177,7 @@ DUCKDB_API duckdb_string duckdb_value_string_internal(duckdb_result *result, idx /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. -* returns: The duckdb_blob value at the specified location. Returns a blob with blob.data set to nullptr if the +* @return 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 field "blob.data" must be freed with `duckdb_free.` */ DUCKDB_API duckdb_blob duckdb_value_blob(duckdb_result *result, idx_t col, idx_t row); @@ -1032,11 +1185,11 @@ DUCKDB_API duckdb_blob duckdb_value_blob(duckdb_result *result, idx_t col, idx_t /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - * returns: Returns true if the value at the specified index is NULL, and false otherwise. - */ +* @return Returns true if the value at the specified index is NULL, and false otherwise. +*/ DUCKDB_API bool duckdb_value_is_null(duckdb_result *result, idx_t col, idx_t row); -#endif +#endif //===--------------------------------------------------------------------===// // Helpers //===--------------------------------------------------------------------===// @@ -1045,8 +1198,8 @@ DUCKDB_API bool duckdb_value_is_null(duckdb_result *result, idx_t col, idx_t row 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. +* @param size The number of bytes to allocate. +* @return A pointer to the allocated memory region. */ DUCKDB_API void *duckdb_malloc(size_t size); @@ -1054,7 +1207,7 @@ DUCKDB_API void *duckdb_malloc(size_t size); Free a value returned from `duckdb_malloc`, `duckdb_value_varchar`, `duckdb_value_blob`, or `duckdb_value_string`. -* ptr: The memory region to de-allocate. +* @param ptr The memory region to de-allocate. */ DUCKDB_API void duckdb_free(void *ptr); @@ -1062,7 +1215,7 @@ DUCKDB_API void duckdb_free(void *ptr); 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. +* @return The vector size. */ DUCKDB_API idx_t duckdb_vector_size(); @@ -1073,48 +1226,64 @@ This means that the data of the string does not have a separate allocation. */ DUCKDB_API bool duckdb_string_is_inlined(duckdb_string_t string); +/*! +Get the string length of a string_t + +* @param string The string to get the length of. +* @return The length. +*/ +DUCKDB_API uint32_t duckdb_string_t_length(duckdb_string_t string); + +/*! +Get a pointer to the string data of a string_t + +* @param string The string to get the pointer to. +* @return The pointer. +*/ +DUCKDB_API const char *duckdb_string_t_data(duckdb_string_t *string); + //===--------------------------------------------------------------------===// -// Date/Time/Timestamp Helpers +// Date Time Timestamp Helpers //===--------------------------------------------------------------------===// /*! 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. +* @param date The date object, as obtained from a `DUCKDB_TYPE_DATE` column. +* @return The `duckdb_date_struct` with the decomposed elements. */ DUCKDB_API duckdb_date_struct duckdb_from_date(duckdb_date 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. +* @param date The year, month and date stored in a `duckdb_date_struct`. +* @return The `duckdb_date` element. */ DUCKDB_API duckdb_date duckdb_to_date(duckdb_date_struct date); /*! Test a `duckdb_date` to see if it is a finite value. -* date: The date object, as obtained from a `DUCKDB_TYPE_DATE` column. -* returns: True if the date is finite, false if it is ±infinity. +* @param date The date object, as obtained from a `DUCKDB_TYPE_DATE` column. +* @return True if the date is finite, false if it is ±infinity. */ DUCKDB_API bool duckdb_is_finite_date(duckdb_date date); /*! 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. +* @param time The time object, as obtained from a `DUCKDB_TYPE_TIME` column. +* @return The `duckdb_time_struct` with the decomposed elements. */ DUCKDB_API duckdb_time_struct duckdb_from_time(duckdb_time time); /*! Create a `duckdb_time_tz` object from micros and a timezone offset. -* micros: The microsecond component of the time. -* offset: The timezone offset component of the time. -* returns: The `duckdb_time_tz` element. +* @param micros The microsecond component of the time. +* @param offset The timezone offset component of the time. +* @return The `duckdb_time_tz` element. */ DUCKDB_API duckdb_time_tz duckdb_create_time_tz(int64_t micros, int32_t offset); @@ -1123,41 +1292,39 @@ 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. +* @param micros The time object, as obtained from a `DUCKDB_TYPE_TIME_TZ` column. */ DUCKDB_API duckdb_time_tz_struct duckdb_from_time_tz(duckdb_time_tz micros); /*! 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. +* @param time The hour, minute, second and microsecond in a `duckdb_time_struct`. +* @return The `duckdb_time` element. */ DUCKDB_API duckdb_time duckdb_to_time(duckdb_time_struct time); /*! 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. +* @param ts The ts object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column. +* @return The `duckdb_timestamp_struct` with the decomposed elements. */ DUCKDB_API duckdb_timestamp_struct duckdb_from_timestamp(duckdb_timestamp ts); /*! Re-compose a `duckdb_timestamp` from a duckdb_timestamp_struct. -* ts: The de-composed elements in a `duckdb_timestamp_struct`. -* returns: The `duckdb_timestamp` element. +* @param ts The de-composed elements in a `duckdb_timestamp_struct`. +* @return The `duckdb_timestamp` element. */ DUCKDB_API duckdb_timestamp duckdb_to_timestamp(duckdb_timestamp_struct ts); /*! Test a `duckdb_timestamp` to see if it is a finite value. -* ts: The timestamp object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column. -* returns: True if the timestamp is finite, false if it is ±infinity. +* @param ts The timestamp object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column. +* @return True if the timestamp is finite, false if it is ±infinity. */ DUCKDB_API bool duckdb_is_finite_timestamp(duckdb_timestamp ts); @@ -1168,8 +1335,8 @@ DUCKDB_API bool duckdb_is_finite_timestamp(duckdb_timestamp ts); /*! Converts a duckdb_hugeint object (as obtained from a `DUCKDB_TYPE_HUGEINT` column) into a double. -* val: The hugeint value. -* returns: The converted `double` element. +* @param val The hugeint value. +* @return The converted `double` element. */ DUCKDB_API double duckdb_hugeint_to_double(duckdb_hugeint val); @@ -1178,8 +1345,8 @@ 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. +* @param val The double value. +* @return The converted `duckdb_hugeint` element. */ DUCKDB_API duckdb_hugeint duckdb_double_to_hugeint(double val); @@ -1190,8 +1357,8 @@ DUCKDB_API duckdb_hugeint duckdb_double_to_hugeint(double val); /*! Converts a duckdb_uhugeint object (as obtained from a `DUCKDB_TYPE_UHUGEINT` column) into a double. -* val: The uhugeint value. -* returns: The converted `double` element. +* @param val The uhugeint value. +* @return The converted `double` element. */ DUCKDB_API double duckdb_uhugeint_to_double(duckdb_uhugeint val); @@ -1200,8 +1367,8 @@ Converts a double value to a duckdb_uhugeint 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_uhugeint` element. +* @param val The double value. +* @return The converted `duckdb_uhugeint` element. */ DUCKDB_API duckdb_uhugeint duckdb_double_to_uhugeint(double val); @@ -1214,16 +1381,16 @@ Converts a double value to a duckdb_decimal object. If the conversion fails because the double value is too big, or the width/scale are invalid the result will be 0. -* val: The double value. -* returns: The converted `duckdb_decimal` element. +* @param val The double value. +* @return The converted `duckdb_decimal` element. */ DUCKDB_API duckdb_decimal duckdb_double_to_decimal(double val, uint8_t width, uint8_t scale); /*! Converts a duckdb_decimal object (as obtained from a `DUCKDB_TYPE_DECIMAL` column) into a double. -* val: The decimal value. -* returns: The converted `double` element. +* @param val The decimal value. +* @return The converted `double` element. */ DUCKDB_API double duckdb_decimal_to_double(duckdb_decimal val); @@ -1240,7 +1407,6 @@ DUCKDB_API double duckdb_decimal_to_double(duckdb_decimal val); // SELECT * FROM tbl WHERE id=? // Or a query with multiple parameters: // SELECT * FROM tbl WHERE id=$1 OR name=$2 - /*! Create a prepared statement object from a query. @@ -1249,10 +1415,10 @@ Note that after calling `duckdb_prepare`, the prepared statement should always b 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 -* out_prepared_statement: The resulting prepared statement object -* returns: `DuckDBSuccess` on success or `DuckDBError` on failure. +* @param connection The connection object +* @param query The SQL query to prepare +* @param out_prepared_statement The resulting prepared statement object +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_prepare(duckdb_connection connection, const char *query, duckdb_prepared_statement *out_prepared_statement); @@ -1260,7 +1426,7 @@ DUCKDB_API duckdb_state duckdb_prepare(duckdb_connection connection, const char /*! Closes the prepared statement and de-allocates all memory allocated for the statement. -* prepared_statement: The prepared statement to destroy. +* @param prepared_statement The prepared statement to destroy. */ DUCKDB_API void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement); @@ -1270,8 +1436,8 @@ 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. +* @param prepared_statement The prepared statement to obtain the error from. +* @return The error message, or `nullptr` if there is none. */ DUCKDB_API const char *duckdb_prepare_error(duckdb_prepared_statement prepared_statement); @@ -1280,7 +1446,7 @@ Returns the number of parameters that can be provided to the given prepared stat Returns 0 if the query was not successfully prepared. -* prepared_statement: The prepared statement to obtain the number of parameters for. +* @param prepared_statement The prepared statement to obtain the number of parameters for. */ DUCKDB_API idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement); @@ -1290,7 +1456,7 @@ The returned string should be freed using `duckdb_free`. Returns NULL if the index is out of range for the provided prepared statement. -* prepared_statement: The prepared statement for which to get the parameter name from. +* @param prepared_statement The prepared statement for which to get the parameter name from. */ DUCKDB_API const char *duckdb_parameter_name(duckdb_prepared_statement prepared_statement, idx_t index); @@ -1299,9 +1465,9 @@ 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 +* @param prepared_statement The prepared statement. +* @param param_idx The parameter index. +* @return The parameter type */ DUCKDB_API duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx); @@ -1313,13 +1479,13 @@ DUCKDB_API duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared /*! Returns the statement type of the statement to be executed - * statement: The prepared statement. - * returns: duckdb_statement_type value or DUCKDB_STATEMENT_TYPE_INVALID - */ +* @param statement The prepared statement. +* @return duckdb_statement_type value or DUCKDB_STATEMENT_TYPE_INVALID +*/ DUCKDB_API duckdb_statement_type duckdb_prepared_statement_type(duckdb_prepared_statement statement); //===--------------------------------------------------------------------===// -// Bind Values to Prepared Statements +// Bind Values To Prepared Statements //===--------------------------------------------------------------------===// /*! @@ -1364,11 +1530,13 @@ Binds a duckdb_hugeint value to the prepared statement at the specified index. */ DUCKDB_API duckdb_state duckdb_bind_hugeint(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_hugeint val); + /*! Binds an duckdb_uhugeint value to the prepared statement at the specified index. */ DUCKDB_API duckdb_state duckdb_bind_uhugeint(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_uhugeint val); + /*! Binds a duckdb_decimal value to the prepared statement at the specified index. */ @@ -1423,6 +1591,12 @@ Binds a duckdb_timestamp value to the prepared statement at the specified index. DUCKDB_API duckdb_state duckdb_bind_timestamp(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_timestamp val); +/*! +Binds a duckdb_timestamp value to the prepared statement at the specified index. +*/ +DUCKDB_API duckdb_state duckdb_bind_timestamp_tz(duckdb_prepared_statement prepared_statement, idx_t param_idx, + duckdb_timestamp val); + /*! Binds a duckdb_interval value to the prepared statement at the specified index. */ @@ -1464,9 +1638,9 @@ between calls to this function. Note that the result must be freed with `duckdb_destroy_result`. -* prepared_statement: The prepared statement to execute. -* out_result: The query result. -* returns: `DuckDBSuccess` on success or `DuckDBError` on failure. +* @param prepared_statement The prepared statement to execute. +* @param out_result The query result. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_execute_prepared(duckdb_prepared_statement prepared_statement, duckdb_result *out_result); @@ -1483,20 +1657,19 @@ between calls to this function. Note that the result must be freed with `duckdb_destroy_result`. -* prepared_statement: The prepared statement to execute. -* out_result: The query result. -* returns: `DuckDBSuccess` on success or `DuckDBError` on failure. +* @param prepared_statement The prepared statement to execute. +* @param out_result The query result. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_execute_prepared_streaming(duckdb_prepared_statement prepared_statement, duckdb_result *out_result); -#endif +#endif //===--------------------------------------------------------------------===// // Extract Statements //===--------------------------------------------------------------------===// // A query string can be extracted into multiple SQL statements. Each statement can be prepared and executed separately. - /*! Extract all statements from a query. Note that after calling `duckdb_extract_statements`, the extracted statements should always be destroyed using @@ -1504,10 +1677,10 @@ Note that after calling `duckdb_extract_statements`, the extracted statements sh If the extract fails, `duckdb_extract_statements_error` can be called to obtain the reason why the extract failed. -* connection: The connection object -* query: The SQL query to extract -* out_extracted_statements: The resulting extracted statements object -* returns: The number of extracted statements or 0 on failure. +* @param connection The connection object +* @param query The SQL query to extract +* @param out_extracted_statements The resulting extracted statements object +* @return The number of extracted statements or 0 on failure. */ DUCKDB_API idx_t duckdb_extract_statements(duckdb_connection connection, const char *query, duckdb_extracted_statements *out_extracted_statements); @@ -1519,28 +1692,29 @@ Note that after calling `duckdb_prepare_extracted_statement`, the prepared state If the prepare fails, `duckdb_prepare_error` can be called to obtain the reason why the prepare failed. -* connection: The connection object -* extracted_statements: The extracted statements object -* index: The index of the extracted statement to prepare -* out_prepared_statement: The resulting prepared statement object -* returns: `DuckDBSuccess` on success or `DuckDBError` on failure. +* @param connection The connection object +* @param extracted_statements The extracted statements object +* @param index The index of the extracted statement to prepare +* @param out_prepared_statement The resulting prepared statement object +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_prepare_extracted_statement(duckdb_connection connection, duckdb_extracted_statements extracted_statements, idx_t index, duckdb_prepared_statement *out_prepared_statement); + /*! Returns the error message contained within the extracted statements. The result of this function must not be freed. It will be cleaned up when `duckdb_destroy_extracted` is called. -* result: The extracted statements to fetch the error from. -* returns: The error of the extracted statements. +* @param extracted_statements The extracted statements to fetch the error from. +* @return The error of the extracted statements. */ DUCKDB_API const char *duckdb_extract_statements_error(duckdb_extracted_statements extracted_statements); /*! De-allocates all memory allocated for the extracted statements. -* extracted_statements: The extracted statements to destroy. +* @param extracted_statements The extracted statements to destroy. */ DUCKDB_API void duckdb_destroy_extracted(duckdb_extracted_statements *extracted_statements); @@ -1556,12 +1730,13 @@ The pending result can be used to incrementally execute a query, returning contr 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. +* @param prepared_statement The prepared statement to execute. +* @param out_result The pending query result. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_pending_prepared(duckdb_prepared_statement prepared_statement, duckdb_pending_result *out_result); + #ifndef DUCKDB_API_NO_DEPRECATED /*! **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. @@ -1573,18 +1748,18 @@ The pending result represents an intermediate structure for a query that is not 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. +* @param prepared_statement The prepared statement to execute. +* @param out_result The pending query result. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_pending_prepared_streaming(duckdb_prepared_statement prepared_statement, duckdb_pending_result *out_result); -#endif +#endif /*! Closes the pending result and de-allocates all memory allocated for the result. -* pending_result: The pending result to destroy. +* @param pending_result The pending result to destroy. */ DUCKDB_API void duckdb_destroy_pending(duckdb_pending_result *pending_result); @@ -1593,8 +1768,8 @@ 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. +* @param pending_result The pending result to fetch the error from. +* @return The error of the pending result. */ DUCKDB_API const char *duckdb_pending_error(duckdb_pending_result pending_result); @@ -1607,8 +1782,8 @@ If this returns DUCKDB_PENDING_ERROR, an error occurred during execution. The error message can be obtained by calling duckdb_pending_error on the pending_result. -* pending_result: The pending result to execute a task within. -* returns: The state of the pending result after the execution. +* @param pending_result The pending result to execute a task within. +* @return The state of the pending result after the execution. */ DUCKDB_API duckdb_pending_state duckdb_pending_execute_task(duckdb_pending_result pending_result); @@ -1619,8 +1794,8 @@ If this returns DUCKDB_PENDING_ERROR, an error occurred during execution. The error message can be obtained by calling duckdb_pending_error on the pending_result. -* pending_result: The pending result. -* returns: The state of the pending result. +* @param pending_result The pending result. +* @return The state of the pending result. */ DUCKDB_API duckdb_pending_state duckdb_pending_execute_check_state(duckdb_pending_result pending_result); @@ -1632,9 +1807,9 @@ Otherwise, all remaining tasks must be executed first. Note that the result must be freed with `duckdb_destroy_result`. -* pending_result: The pending result to execute. -* out_result: The result object. -* returns: `DuckDBSuccess` on success or `DuckDBError` on failure. +* @param pending_result The pending result to execute. +* @param out_result The result object. +* @return `DuckDBSuccess` on success or `DuckDBError` on failure. */ DUCKDB_API duckdb_state duckdb_execute_pending(duckdb_pending_result pending_result, duckdb_result *out_result); @@ -1642,8 +1817,8 @@ DUCKDB_API duckdb_state duckdb_execute_pending(duckdb_pending_result pending_res Returns whether a duckdb_pending_state is finished executing. For example if `pending_state` is DUCKDB_PENDING_RESULT_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. +* @param pending_state The pending state on which to decide whether to finish execution. +* @return Boolean indicating pending execution should be considered finished. */ DUCKDB_API bool duckdb_pending_execution_is_finished(duckdb_pending_state pending_state); @@ -1654,439 +1829,786 @@ DUCKDB_API bool duckdb_pending_execution_is_finished(duckdb_pending_state pendin /*! Destroys the value and de-allocates all memory allocated for that type. -* value: The value to destroy. +* @param value The value to destroy. */ DUCKDB_API void duckdb_destroy_value(duckdb_value *value); /*! Creates a value from a null-terminated string -* value: The null-terminated string -* returns: The value. This must be destroyed with `duckdb_destroy_value`. +* @param text The null-terminated string +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ DUCKDB_API duckdb_value duckdb_create_varchar(const char *text); /*! 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`. +* @param text The text +* @param length The length of the text +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ DUCKDB_API duckdb_value duckdb_create_varchar_length(const char *text, idx_t length); /*! -Creates a value from an int64 +Creates a value from a boolean -* value: The bigint value -* returns: The value. This must be destroyed with `duckdb_destroy_value`. +* @param input The boolean value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_value duckdb_create_int64(int64_t val); +DUCKDB_API duckdb_value duckdb_create_bool(bool input); /*! -Creates a struct value from a type and an array of values +Creates a value from a int8_t (a tinyint) -* type: The type of the struct -* values: The values for the struct fields -* returns: The value. This must be destroyed with `duckdb_destroy_value`. +* @param input The tinyint value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_value duckdb_create_struct_value(duckdb_logical_type type, duckdb_value *values); +DUCKDB_API duckdb_value duckdb_create_int8(int8_t input); /*! -Creates a list value from a type and an array of values of length `value_count` +Creates a value from a uint8_t (a utinyint) -* type: The type of the list -* values: The values for the list -* value_count: The number of values in the list -* returns: The value. This must be destroyed with `duckdb_destroy_value`. +* @param input The utinyint value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_value duckdb_create_list_value(duckdb_logical_type type, duckdb_value *values, idx_t value_count); +DUCKDB_API duckdb_value duckdb_create_uint8(uint8_t input); /*! -Creates a array value from a type and an array of values of length `value_count` +Creates a value from a int16_t (a smallint) -* type: The type of the array -* values: The values for the array -* value_count: The number of values in the array -* returns: The value. This must be destroyed with `duckdb_destroy_value`. +* @param input The smallint value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_value duckdb_create_array_value(duckdb_logical_type type, duckdb_value *values, idx_t value_count); +DUCKDB_API duckdb_value duckdb_create_int16(int16_t input); /*! -Obtains a string representation of the given value. -The result must be destroyed with `duckdb_free`. +Creates a value from a uint16_t (a usmallint) -* value: The value -* returns: The string value. This must be destroyed with `duckdb_free`. +* @param input The usmallint value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API char *duckdb_get_varchar(duckdb_value value); +DUCKDB_API duckdb_value duckdb_create_uint16(uint16_t input); /*! -Obtains an int64 of the given value. +Creates a value from a int32_t (an integer) -* value: The value -* returns: The int64 value, or 0 if no conversion is possible +* @param input The integer value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API int64_t duckdb_get_int64(duckdb_value value); - -//===--------------------------------------------------------------------===// -// Logical Type Interface -//===--------------------------------------------------------------------===// +DUCKDB_API duckdb_value duckdb_create_int32(int32_t input); /*! -Creates a `duckdb_logical_type` from a standard primitive type. -The resulting type should be destroyed with `duckdb_destroy_logical_type`. +Creates a value from a uint32_t (a uinteger) -This should not be used with `DUCKDB_TYPE_DECIMAL`. - -* type: The primitive type to create. -* returns: The logical type. +* @param input The uinteger value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_logical_type(duckdb_type type); +DUCKDB_API duckdb_value duckdb_create_uint32(uint32_t input); /*! -Returns the alias of a duckdb_logical_type, if one is set, else `NULL`. -The result must be destroyed with `duckdb_free`. +Creates a value from a uint64_t (a ubigint) -* type: The logical type to return the alias of -* returns: The alias or `NULL` - */ -DUCKDB_API char *duckdb_logical_type_get_alias(duckdb_logical_type type); +* @param input The ubigint value +* @return The value. This must be destroyed with `duckdb_destroy_value`. +*/ +DUCKDB_API duckdb_value duckdb_create_uint64(uint64_t input); /*! -Creates a list type from its child type. -The resulting type should be destroyed with `duckdb_destroy_logical_type`. +Creates a value from an int64 -* type: The child type of list type to create. -* returns: The logical type. +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_list_type(duckdb_logical_type type); +DUCKDB_API duckdb_value duckdb_create_int64(int64_t val); /*! -Creates a array type from its child type. -The resulting type should be destroyed with `duckdb_destroy_logical_type`. +Creates a value from a hugeint -* type: The child type of array type to create. -* array_size: The number of elements in the array. -* returns: The logical type. +* @param input The hugeint value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_array_type(duckdb_logical_type type, idx_t array_size); +DUCKDB_API duckdb_value duckdb_create_hugeint(duckdb_hugeint input); /*! -Creates a map type from its key type and value type. -The resulting type should be destroyed with `duckdb_destroy_logical_type`. +Creates a value from a uhugeint -* type: The key type and value type of map type to create. -* returns: The logical type. +* @param input The uhugeint value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_map_type(duckdb_logical_type key_type, duckdb_logical_type value_type); +DUCKDB_API duckdb_value duckdb_create_uhugeint(duckdb_uhugeint input); /*! -Creates a UNION type from the passed types array. -The resulting type should be destroyed with `duckdb_destroy_logical_type`. +Creates a value from a float -* types: The array of types that the union should consist of. -* type_amount: The size of the types array. -* returns: The logical type. +* @param input The float value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_union_type(duckdb_logical_type *member_types, const char **member_names, - idx_t member_count); +DUCKDB_API duckdb_value duckdb_create_float(float input); /*! -Creates a STRUCT type from the passed member name and type arrays. -The resulting type should be destroyed with `duckdb_destroy_logical_type`. +Creates a value from a double -* member_types: The array of types that the struct should consist of. -* member_names: The array of names that the struct should consist of. -* member_count: The number of members that were specified for both arrays. -* returns: The logical type. +* @param input The double value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_struct_type(duckdb_logical_type *member_types, const char **member_names, - idx_t member_count); +DUCKDB_API duckdb_value duckdb_create_double(double input); /*! -Creates an ENUM type from the passed member name array. -The resulting type should be destroyed with `duckdb_destroy_logical_type`. +Creates a value from a date -* enum_name: The name of the enum. -* member_names: The array of names that the enum should consist of. -* member_count: The number of elements that were specified in the array. -* returns: The logical type. +* @param input The date value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_enum_type(const char **member_names, idx_t member_count); +DUCKDB_API duckdb_value duckdb_create_date(duckdb_date input); /*! -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`. +Creates a value from a time -* width: The width of the decimal type -* scale: The scale of the decimal type -* returns: The logical type. +* @param input The time value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_logical_type duckdb_create_decimal_type(uint8_t width, uint8_t scale); +DUCKDB_API duckdb_value duckdb_create_time(duckdb_time input); /*! -Retrieves the enum type class of a `duckdb_logical_type`. +Creates a value from a time_tz. +Not to be confused with `duckdb_create_time_tz`, which creates a duckdb_time_tz_t. -* type: The logical type object -* returns: The type id +* @param value The time_tz value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_type duckdb_get_type_id(duckdb_logical_type type); +DUCKDB_API duckdb_value duckdb_create_time_tz_value(duckdb_time_tz value); /*! -Retrieves the width of a decimal type. +Creates a value from a timestamp -* type: The logical type object -* returns: The width of the decimal type +* @param input The timestamp value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API uint8_t duckdb_decimal_width(duckdb_logical_type type); +DUCKDB_API duckdb_value duckdb_create_timestamp(duckdb_timestamp input); /*! -Retrieves the scale of a decimal type. +Creates a value from an interval -* type: The logical type object -* returns: The scale of the decimal type +* @param input The interval value +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API uint8_t duckdb_decimal_scale(duckdb_logical_type type); +DUCKDB_API duckdb_value duckdb_create_interval(duckdb_interval input); /*! -Retrieves the internal storage type of a decimal type. +Creates a value from a blob -* type: The logical type object -* returns: The internal type of the decimal type +* @param data The blob data +* @param length The length of the blob data +* @return The value. This must be destroyed with `duckdb_destroy_value`. */ -DUCKDB_API duckdb_type duckdb_decimal_internal_type(duckdb_logical_type type); +DUCKDB_API duckdb_value duckdb_create_blob(const uint8_t *data, idx_t length); /*! -Retrieves the internal storage type of an enum type. +Returns the boolean value of the given value. -* type: The logical type object -* returns: The internal type of the enum type +* @param val A duckdb_value containing a boolean +* @return A boolean, or false if the value cannot be converted */ -DUCKDB_API duckdb_type duckdb_enum_internal_type(duckdb_logical_type type); +DUCKDB_API bool duckdb_get_bool(duckdb_value val); /*! -Retrieves the dictionary size of the enum type. +Returns the int8_t value of the given value. -* type: The logical type object -* returns: The dictionary size of the enum type +* @param val A duckdb_value containing a tinyint +* @return A int8_t, or MinValue if the value cannot be converted */ -DUCKDB_API uint32_t duckdb_enum_dictionary_size(duckdb_logical_type type); +DUCKDB_API int8_t duckdb_get_int8(duckdb_value val); /*! -Retrieves the dictionary value at the specified position from the enum. - -The result must be freed with `duckdb_free`. +Returns the uint8_t value of the given value. -* 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`. +* @param val A duckdb_value containing a utinyint +* @return A uint8_t, or MinValue if the value cannot be converted */ -DUCKDB_API char *duckdb_enum_dictionary_value(duckdb_logical_type type, idx_t index); +DUCKDB_API uint8_t duckdb_get_uint8(duckdb_value val); /*! -Retrieves the child type of the given list type. - -The result must be freed with `duckdb_destroy_logical_type`. +Returns the int16_t value of the given value. -* type: The logical type object -* returns: The child type of the list type. Must be destroyed with `duckdb_destroy_logical_type`. +* @param val A duckdb_value containing a smallint +* @return A int16_t, or MinValue if the value cannot be converted */ -DUCKDB_API duckdb_logical_type duckdb_list_type_child_type(duckdb_logical_type type); +DUCKDB_API int16_t duckdb_get_int16(duckdb_value val); /*! -Retrieves the child type of the given array type. +Returns the uint16_t value of the given value. -The result must be freed with `duckdb_destroy_logical_type`. - -* type: The logical type object -* returns: The child type of the array type. Must be destroyed with `duckdb_destroy_logical_type`. +* @param val A duckdb_value containing a usmallint +* @return A uint16_t, or MinValue if the value cannot be converted */ -DUCKDB_API duckdb_logical_type duckdb_array_type_child_type(duckdb_logical_type type); +DUCKDB_API uint16_t duckdb_get_uint16(duckdb_value val); /*! -Retrieves the array size of the given array type. +Returns the int32_t value of the given value. -* type: The logical type object -* returns: The fixed number of elements the values of this array type can store. +* @param val A duckdb_value containing a integer +* @return A int32_t, or MinValue if the value cannot be converted */ -DUCKDB_API idx_t duckdb_array_type_array_size(duckdb_logical_type type); +DUCKDB_API int32_t duckdb_get_int32(duckdb_value val); /*! -Retrieves the key type of the given map type. - -The result must be freed with `duckdb_destroy_logical_type`. +Returns the uint32_t value of the given value. -* type: The logical type object -* returns: The key type of the map type. Must be destroyed with `duckdb_destroy_logical_type`. +* @param val A duckdb_value containing a uinteger +* @return A uint32_t, or MinValue if the value cannot be converted */ -DUCKDB_API duckdb_logical_type duckdb_map_type_key_type(duckdb_logical_type type); +DUCKDB_API uint32_t duckdb_get_uint32(duckdb_value val); /*! -Retrieves the value type of the given map type. - -The result must be freed with `duckdb_destroy_logical_type`. +Returns the int64_t value of the given value. -* type: The logical type object -* returns: The value type of the map type. Must be destroyed with `duckdb_destroy_logical_type`. +* @param val A duckdb_value containing a bigint +* @return A int64_t, or MinValue if the value cannot be converted */ -DUCKDB_API duckdb_logical_type duckdb_map_type_value_type(duckdb_logical_type type); +DUCKDB_API int64_t duckdb_get_int64(duckdb_value val); /*! -Returns the number of children of a struct type. +Returns the uint64_t value of the given value. -* type: The logical type object -* returns: The number of children of a struct type. +* @param val A duckdb_value containing a ubigint +* @return A uint64_t, or MinValue if the value cannot be converted */ -DUCKDB_API idx_t duckdb_struct_type_child_count(duckdb_logical_type type); +DUCKDB_API uint64_t duckdb_get_uint64(duckdb_value val); /*! -Retrieves the name of the struct child. +Returns the hugeint value of the given value. -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`. +* @param val A duckdb_value containing a hugeint +* @return A duckdb_hugeint, or MinValue if the value cannot be converted */ -DUCKDB_API char *duckdb_struct_type_child_name(duckdb_logical_type type, idx_t index); +DUCKDB_API duckdb_hugeint duckdb_get_hugeint(duckdb_value val); /*! -Retrieves the child type of the given struct type at the specified index. +Returns the uhugeint value of the given value. -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`. +* @param val A duckdb_value containing a uhugeint +* @return A duckdb_uhugeint, or MinValue if the value cannot be converted */ -DUCKDB_API duckdb_logical_type duckdb_struct_type_child_type(duckdb_logical_type type, idx_t index); +DUCKDB_API duckdb_uhugeint duckdb_get_uhugeint(duckdb_value val); /*! -Returns the number of members that the union type has. +Returns the float value of the given value. -* type: The logical type (union) object -* returns: The number of members of a union type. +* @param val A duckdb_value containing a float +* @return A float, or NAN if the value cannot be converted */ -DUCKDB_API idx_t duckdb_union_type_member_count(duckdb_logical_type type); +DUCKDB_API float duckdb_get_float(duckdb_value val); /*! -Retrieves the name of the union member. +Returns the double value of the given value. -The result must be freed with `duckdb_free`. +* @param val A duckdb_value containing a double +* @return A double, or NAN if the value cannot be converted +*/ +DUCKDB_API double duckdb_get_double(duckdb_value val); -* type: The logical type object -* index: The child index -* returns: The name of the union member. Must be freed with `duckdb_free`. +/*! +Returns the date value of the given value. + +* @param val A duckdb_value containing a date +* @return A duckdb_date, or MinValue if the value cannot be converted */ -DUCKDB_API char *duckdb_union_type_member_name(duckdb_logical_type type, idx_t index); +DUCKDB_API duckdb_date duckdb_get_date(duckdb_value val); /*! -Retrieves the child type of the given union member at the specified index. +Returns the time value of the given value. -The result must be freed with `duckdb_destroy_logical_type`. +* @param val A duckdb_value containing a time +* @return A duckdb_time, or MinValue