From 6a0e7f160fdbf86ccfd58e5f4db40674b7812a03 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Sat, 31 Oct 2026 11:53:13 +0700 Subject: [PATCH 1/8] build(libs): publish libs-6 --- apple/Libs/checksums.sha256 | 8 ++++---- apple/Libs/ios/checksums.sha256 | 12 +++++++----- apple/Libs/release | 2 +- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/apple/Libs/checksums.sha256 b/apple/Libs/checksums.sha256 index 58559a0baf..228b6a3f62 100644 --- a/apple/Libs/checksums.sha256 +++ b/apple/Libs/checksums.sha256 @@ -10,10 +10,10 @@ c47c8406cdb817e121a89ad5171f6931fd73c4bce6c73c3809e626257afd7374 Libs/libcrypto e274f77ed3feaee3d4f8f6ac297376d56a1369388f037599a90ea440390349b4 Libs/libcrypto_universal.a ec04bc233ea917de16a48b130d1467c68f5b95d469f423b7b9054d0e45bb4e16 Libs/libcrypto_x86_64.a e274f77ed3feaee3d4f8f6ac297376d56a1369388f037599a90ea440390349b4 Libs/libcrypto.a -f833d1edba062e03a5a7f7b5e40fbfe0f015c081158b8dd455d6129bf4515c12 Libs/libduckdb_arm64.a -c1aef28aa225d34bb4d8be853000f4d2640a77366ff4b2cfa61f53648290c357 Libs/libduckdb_universal.a -e971a4c84689626699482ba5e2f148345b50e53fc1aed57b6e37fbb90c85db9c Libs/libduckdb_x86_64.a -c1aef28aa225d34bb4d8be853000f4d2640a77366ff4b2cfa61f53648290c357 Libs/libduckdb.a +09b2deb312d03840dda422a6931a9918ad81c308941c774556adb1386d6ab589 Libs/libduckdb_arm64.a +9749f1be288f03cc4362b15fbc0137edd8aee75542f52f7d7ca8d563586a1e77 Libs/libduckdb_universal.a +3183445676921ea6e4ea4cb7f0689703fb3ceba3d1699b21e88a2e36f12e0e2e Libs/libduckdb_x86_64.a +9749f1be288f03cc4362b15fbc0137edd8aee75542f52f7d7ca8d563586a1e77 Libs/libduckdb.a 5017c3fecadf4955fad1db923a8358fc9943fa17e8a5d54288db6a28fc5a3aa8 Libs/libhiredis_arm64.a 58974eb81d5fefca9fb6732bd15921f1cf12a23f9a2402b1b099ec6c089f1e35 Libs/libhiredis_ssl_arm64.a 09c8cb4acb62a54c09c4f2605bbc464b93d9e2ea5b2ae89a1d2165f8adaa9b9c Libs/libhiredis_ssl_universal.a diff --git a/apple/Libs/ios/checksums.sha256 b/apple/Libs/ios/checksums.sha256 index bd457322f7..f6e64e4c7a 100644 --- a/apple/Libs/ios/checksums.sha256 +++ b/apple/Libs/ios/checksums.sha256 @@ -1,8 +1,10 @@ -840741c66e9ee257f97eb7cc16407c37960aa49faa4b110e56ccc0f8dc3a6db2 ./DuckDB.xcframework/Info.plist -c8dd688cf14559c744255d1bb3879330d6ae3523268e8904fa7b885e140030aa ./DuckDB.xcframework/ios-arm64/Headers/duckdb.h -f4073989393e739b0b5ad68c7f47f7750715d2d46e46141e81b1bc49cf782620 ./DuckDB.xcframework/ios-arm64/libduckdb-device.a -c8dd688cf14559c744255d1bb3879330d6ae3523268e8904fa7b885e140030aa ./DuckDB.xcframework/ios-arm64_x86_64-simulator/Headers/duckdb.h -75523877523153f63249a39eb4ec0d7f1bb05db3a4dbb5e6c35ee848b09afb71 ./DuckDB.xcframework/ios-arm64_x86_64-simulator/libduckdb-sim.a +fcfb2160ac0c32d40fd3241bb0ec0ec157238a5db6ef68a5d98e93a616956cf6 ./DuckDB.xcframework/Info.plist +8dbc9c71a10f0a75fcacc1a3f4f7c76093a84d232fc152222ee5b6e512ab4560 ./DuckDB.xcframework/ios-arm64-simulator/Headers/duckdb.h +a90f28cbe2662c69fc73f726832479ae7b5d043566b83eb1ac95a8ab35d3e37d ./DuckDB.xcframework/ios-arm64-simulator/Headers/duckdb_static_extensions.h +842bd80d7f54472c4161434474af155675e0d7b19c7751e1d1046d8e144a19b6 ./DuckDB.xcframework/ios-arm64-simulator/libduckdb-sim.a +8dbc9c71a10f0a75fcacc1a3f4f7c76093a84d232fc152222ee5b6e512ab4560 ./DuckDB.xcframework/ios-arm64/Headers/duckdb.h +a90f28cbe2662c69fc73f726832479ae7b5d043566b83eb1ac95a8ab35d3e37d ./DuckDB.xcframework/ios-arm64/Headers/duckdb_static_extensions.h +c667055fe35aa1e47ca8f2dd36b8328743429872022a0bb25701b593d9a7d1f0 ./DuckDB.xcframework/ios-arm64/libduckdb-device.a 0481f79db3949ba16425ffd8e15e640757a208ca05728d98cdbfb4bc617e06c3 ./FreeTDS.xcframework/Info.plist 734d8502be13513e974a621557b1a4776d9f605b5a48039e28a3597f27f704ce ./FreeTDS.xcframework/ios-arm64-simulator/Headers/sybdb.h eaa21732fa7cfb538b3bb9bcca7342b99b407d2e838c09e5f3d07398c21406a3 ./FreeTDS.xcframework/ios-arm64-simulator/Headers/sybfront.h diff --git a/apple/Libs/release b/apple/Libs/release index edf700ee23..f05581e49b 100644 --- a/apple/Libs/release +++ b/apple/Libs/release @@ -1 +1 @@ -libs-5 +libs-6 From f2339f668e8591f4ee36cd574e3ad270a13b87f2 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Sat, 31 Oct 2026 11:53:14 +0700 Subject: [PATCH 2/8] build(duckdb): bump libduckdb to 2.0.0 --- .../CDuckDB/include/duckdb.h | 13971 ++++++++++------ .../DuckDBDriverPlugin/DuckDBConnection.swift | 22 +- .../DuckDBStorageCompatibility.swift | 13 + .../Core/Database/NativeDumpRegistry.swift | 7 +- .../TablePro/Resources/Localizable.xcstrings | 8 + .../Resources/ThirdPartyLicenses/licenses.yml | 21 +- .../ThirdPartyLicenses/texts/duckdb.txt | 2 +- .../Acknowledgements/Acknowledgements.json | 4 +- .../TableProMobile/CBridges/CDuckDB/CDuckDB.h | 1 + .../TableProMobile/Drivers/DuckDBDriver.swift | 25 +- .../Drivers/DuckDBDriverTests.swift | 30 +- apple/scripts/build-duckdb-ios.sh | 234 +- apple/scripts/build-duckdb.sh | 196 +- apple/scripts/duckdb-ios-extensions.cmake | 29 +- .../probes/check-column-type-corpus.sh | 2 +- .../probes/check-duckdb-access-mode.sh | 2 +- .../scripts/probes/check-duckdb-extensions.sh | 2 +- .../probes/check-duckdb-storage-version.sh | 112 + .../scripts/probes/check-duckdb-value-api.sh | 2 +- linux/Cargo.lock | 184 +- linux/Cargo.toml | 8 +- linux/README.md | 2 +- .../about/bundled/libduckdb-sys/duckdb.txt | 2 +- .../bundled/libduckdb-sys/libpg_query.txt | 28 - .../about/bundled/libduckdb-sys/manifest.json | 5 +- linux/build-aux/debian/copyright | 175 +- .../crates/drivers/duckdb/src/create_file.rs | 4 +- linux/crates/drivers/duckdb/src/instance.rs | 7 +- .../tests/integration/open_semantics.rs | 34 + linux/data/licenses/NOTICE | 8 +- linux/data/licenses/THIRD-PARTY-NOTICE.md | 408 +- linux/data/licenses/third-party.json | 162 +- linux/docs/adding-drivers.md | 2 +- linux/docs/decisions/0025-bundled-duckdb.md | 2 +- linux/docs/decisions/0031-duckdb-2.md | 32 + linux/docs/decisions/README.md | 3 +- linux/docs/drivers/duckdb.md | 3 +- 37 files changed, 10228 insertions(+), 5524 deletions(-) create mode 100644 apple/Plugins/DuckDBDriverPlugin/DuckDBStorageCompatibility.swift create mode 100755 apple/scripts/probes/check-duckdb-storage-version.sh delete mode 100644 linux/build-aux/about/bundled/libduckdb-sys/libpg_query.txt create mode 100644 linux/docs/decisions/0031-duckdb-2.md diff --git a/apple/Plugins/DuckDBDriverPlugin/CDuckDB/include/duckdb.h b/apple/Plugins/DuckDBDriverPlugin/CDuckDB/include/duckdb.h index 56ee87b782..517bb60b16 100644 --- a/apple/Plugins/DuckDBDriverPlugin/CDuckDB/include/duckdb.h +++ b/apple/Plugins/DuckDBDriverPlugin/CDuckDB/include/duckdb.h @@ -2,34 +2,41 @@ // // DuckDB // -// duckdb.h -// // //===----------------------------------------------------------------------===// // // !!!!!!! -// WARNING: this file is autogenerated by scripts/generate_c_api.py, manual changes will be overwritten +// WARNING: this file is autogenerated, manual changes will be overwritten // !!!!!!! #pragma once +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + #ifndef DUCKDB_C_API #ifdef _WIN32 #ifdef DUCKDB_STATIC_BUILD #define DUCKDB_C_API -#else -#if defined(DUCKDB_BUILD_LIBRARY) && !defined(DUCKDB_BUILD_LOADABLE_EXTENSION) +#elif defined(DUCKDB_BUILD_LIBRARY) && !defined(DUCKDB_BUILD_LOADABLE_EXTENSION) #define DUCKDB_C_API __declspec(dllexport) #else #define DUCKDB_C_API __declspec(dllimport) #endif -#endif +#else +#if defined(__GNUC__) || defined(__clang__) +#define DUCKDB_C_API __attribute__((visibility("default"))) #else #define DUCKDB_C_API #endif #endif +#endif -//! duplicate of duckdb/main/winapi.hpp #ifndef DUCKDB_EXTENSION_API #ifdef _WIN32 #ifdef DUCKDB_STATIC_BUILD @@ -38,122 +45,267 @@ #define DUCKDB_EXTENSION_API __declspec(dllexport) #endif #else +#if defined(__GNUC__) || defined(__clang__) #define DUCKDB_EXTENSION_API __attribute__((visibility("default"))) +#else +#define DUCKDB_EXTENSION_API +#endif #endif #endif -#include -#include -#include +#if defined(__GNUC__) || defined(__clang__) +#define DUCKDB_DEPRECATED \ + __attribute__((deprecated("This function is deprecated and will be removed in a future version."))) +#elif defined(_MSC_VER) +#define DUCKDB_DEPRECATED __declspec(deprecated("This function is deprecated and will be removed in a future version.")) +#else +#define DUCKDB_DEPRECATED +#endif -#ifdef __cplusplus -extern "C" { +//===--------------------------------------------------------------------===// +// API version +//===--------------------------------------------------------------------===// +//! The API version this translation unit targets. Define all three to compile against an +//! older surface than the one this header describes. +#if !defined(DUCKDB_API_VERSION_MAJOR) && !defined(DUCKDB_API_VERSION_MINOR) && !defined(DUCKDB_API_VERSION_PATCH) +#define DUCKDB_API_VERSION_MAJOR 1 +#define DUCKDB_API_VERSION_MINOR 5 +#define DUCKDB_API_VERSION_PATCH 6 +#elif !(defined(DUCKDB_API_VERSION_MAJOR) && defined(DUCKDB_API_VERSION_MINOR) && defined(DUCKDB_API_VERSION_PATCH)) +#error "define all or none of the DUCKDB_API_VERSION_MAJOR / _MINOR / _PATCH macros" +#endif + +//! True when the targeted version is x.y.z or newer. +#define DUCKDB_API_VERSION_AT_LEAST(x, y, z) \ + (DUCKDB_API_VERSION_MAJOR > (x) || \ + (DUCKDB_API_VERSION_MAJOR == (x) && \ + (DUCKDB_API_VERSION_MINOR > (y) || (DUCKDB_API_VERSION_MINOR == (y) && DUCKDB_API_VERSION_PATCH >= (z))))) + +//! True when the targeted version is older than x.y.z. +#define DUCKDB_API_VERSION_BELOW(x, y, z) (!DUCKDB_API_VERSION_AT_LEAST((x), (y), (z))) + +//===--------------------------------------------------------------------===// +// Surface switches +//===--------------------------------------------------------------------===// +//! Set to 1 to compile the deprecated surface, 0 to omit it. Defaults from the +//! older DUCKDB_API_NO_DEPRECATED macro when that is what the consumer defines. +#if !defined(DUCKDB_API_ALLOW_DEPRECATED) +#ifdef DUCKDB_API_NO_DEPRECATED +#define DUCKDB_API_ALLOW_DEPRECATED 0 +#else +#define DUCKDB_API_ALLOW_DEPRECATED 1 +#endif +#endif + +//! Set to 1 to compile the unstable surface, 0 to omit it. Defaults from the +//! older DUCKDB_EXTENSION_API_VERSION_UNSTABLE macro when that is what the consumer defines. +#if !defined(DUCKDB_API_ALLOW_UNSTABLE) +#ifdef DUCKDB_EXTENSION_API_VERSION_UNSTABLE +#define DUCKDB_API_ALLOW_UNSTABLE 1 +#else +#define DUCKDB_API_ALLOW_UNSTABLE 0 +#endif +#endif + +//! The unstable surface is not a promise, so it is not part of any released +//! version: its constructs may change shape or vanish. Targeting an older version +//! while opting into it would hand back today's shapes under names that version +//! never promised, so the two are mutually exclusive. +#if DUCKDB_API_ALLOW_UNSTABLE && !DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +#error "the unstable surface requires targeting the newest API version" #endif //===--------------------------------------------------------------------===// -// Enums +// General type definitions //===--------------------------------------------------------------------===// -//! WARNING: The numbers of these enums should not be changed, as changing the numbers breaks ABI compatibility. -//! Always add enums at the END of the enum +//! The internal representation of a VARCHAR (string_t). If the VARCHAR does not +//! exceed 12 characters, then we inline it. Otherwise, we inline a four-byte prefix for faster +//! string comparisons and store a pointer to the remaining characters. This is a non- +//! owning structure, i.e., it does not have to be freed. +typedef struct { + union { + struct { + uint32_t length; + char prefix[4]; + char *ptr; + } pointer; + struct { + uint32_t length; + char inlined[12]; + } inlined; + } value; +} duckdb_string_t; + +//! The returned state of different functions. Legacy naming: values use DuckDB prefix without underscore. +typedef enum duckdb_state { DuckDBSuccess = 0, DuckDBError = 1 } duckdb_state; + +struct ArrowSchema; +struct ArrowArray; + +typedef uint64_t idx_t; + +/* ============================================================================ + * MODULE: common_enums + * ============================================================================ */ + +/* --- Enums for common_enums --- */ -//! An enum over DuckDB's internal types. +/*! + * An enum over DuckDB's internal types. + * + * history: + * - stable: v0.1.0 + */ typedef enum DUCKDB_TYPE { DUCKDB_TYPE_INVALID = 0, - // bool + + //! bool DUCKDB_TYPE_BOOLEAN = 1, - // int8_t + + //! int8_t DUCKDB_TYPE_TINYINT = 2, - // int16_t + + //! int16_t DUCKDB_TYPE_SMALLINT = 3, - // int32_t + + //! int32_t DUCKDB_TYPE_INTEGER = 4, - // int64_t + + //! int64_t DUCKDB_TYPE_BIGINT = 5, - // uint8_t + + //! uint8_t DUCKDB_TYPE_UTINYINT = 6, - // uint16_t + + //! uint16_t DUCKDB_TYPE_USMALLINT = 7, - // uint32_t + + //! uint32_t DUCKDB_TYPE_UINTEGER = 8, - // uint64_t + + //! uint64_t DUCKDB_TYPE_UBIGINT = 9, - // float + + //! float DUCKDB_TYPE_FLOAT = 10, - // double + + //! double DUCKDB_TYPE_DOUBLE = 11, - // duckdb_timestamp (microseconds) + + //! duckdb_timestamp (microseconds) DUCKDB_TYPE_TIMESTAMP = 12, - // duckdb_date + + //! duckdb_date DUCKDB_TYPE_DATE = 13, - // duckdb_time + + //! duckdb_time DUCKDB_TYPE_TIME = 14, - // duckdb_interval + + //! duckdb_interval DUCKDB_TYPE_INTERVAL = 15, - // duckdb_hugeint + + //! duckdb_hugeint DUCKDB_TYPE_HUGEINT = 16, - // duckdb_uhugeint - DUCKDB_TYPE_UHUGEINT = 32, - // const char* + + //! const char* DUCKDB_TYPE_VARCHAR = 17, - // duckdb_blob + + //! duckdb_blob DUCKDB_TYPE_BLOB = 18, - // duckdb_decimal + + //! duckdb_decimal DUCKDB_TYPE_DECIMAL = 19, - // duckdb_timestamp_s (seconds) + + //! duckdb_timestamp_s (seconds) DUCKDB_TYPE_TIMESTAMP_S = 20, - // duckdb_timestamp_ms (milliseconds) + + //! duckdb_timestamp_ms (milliseconds) DUCKDB_TYPE_TIMESTAMP_MS = 21, - // duckdb_timestamp_ns (nanoseconds) + + //! duckdb_timestamp_ns (nanoseconds) DUCKDB_TYPE_TIMESTAMP_NS = 22, - // enum type, only useful as logical type + + //! enum type, only useful as logical type DUCKDB_TYPE_ENUM = 23, - // list type, only useful as logical type + + //! list type, only useful as logical type DUCKDB_TYPE_LIST = 24, - // struct type, only useful as logical type + + //! struct type, only useful as logical type DUCKDB_TYPE_STRUCT = 25, - // map type, only useful as logical type + + //! map type, only useful as logical type DUCKDB_TYPE_MAP = 26, - // duckdb_array, only useful as logical type - DUCKDB_TYPE_ARRAY = 33, - // duckdb_hugeint + + //! duckdb_hugeint DUCKDB_TYPE_UUID = 27, - // union type, only useful as logical type + + //! union type, only useful as logical type DUCKDB_TYPE_UNION = 28, - // duckdb_bit + + //! duckdb_bit DUCKDB_TYPE_BIT = 29, - // duckdb_time_tz + + //! duckdb_time_tz DUCKDB_TYPE_TIME_TZ = 30, - // duckdb_timestamp (microseconds) + + //! duckdb_timestamp (microseconds) DUCKDB_TYPE_TIMESTAMP_TZ = 31, - // enum type, only useful as logical type + + //! duckdb_uhugeint + DUCKDB_TYPE_UHUGEINT = 32, + + //! duckdb_array, only useful as logical type + DUCKDB_TYPE_ARRAY = 33, + + //! enum type, only useful as logical type DUCKDB_TYPE_ANY = 34, - // duckdb_bignum + + //! duckdb_bignum DUCKDB_TYPE_BIGNUM = 35, - // enum type, only useful as logical type + + //! enum type, only useful as logical type DUCKDB_TYPE_SQLNULL = 36, - // enum type, only useful as logical type + + //! enum type, only useful as logical type DUCKDB_TYPE_STRING_LITERAL = 37, - // enum type, only useful as logical type + + //! enum type, only useful as logical type DUCKDB_TYPE_INTEGER_LITERAL = 38, - // duckdb_time_ns (nanoseconds) + + //! duckdb_time_ns (nanoseconds) DUCKDB_TYPE_TIME_NS = 39, - // GEOMETRY type, WKB blob + + //! GEOMETRY type, WKB blob DUCKDB_TYPE_GEOMETRY = 40, -} duckdb_type; -//! An enum over the returned state of different functions. -typedef enum duckdb_state { DuckDBSuccess = 0, DuckDBError = 1 } duckdb_state; + //! VARIANT type + DUCKDB_TYPE_VARIANT = 41, -//! An enum over the pending state of a pending query result. + //! duckdb_timestamp (nanoseconds) + DUCKDB_TYPE_TIMESTAMP_TZ_NS = 42, +} DUCKDB_TYPE; + +/*! + * An enum over the pending state of a pending query result. + * + * history: + * - stable: v0.5.0 + */ 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_NO_TASKS_AVAILABLE = 3, } duckdb_pending_state; -//! An enum over DuckDB's different result types. +/*! + * An enum over DuckDB's different result types. + * + * history: + * - stable: v0.10.0 + */ typedef enum duckdb_result_type { DUCKDB_RESULT_TYPE_INVALID = 0, DUCKDB_RESULT_TYPE_CHANGED_ROWS = 1, @@ -161,7 +313,12 @@ typedef enum duckdb_result_type { DUCKDB_RESULT_TYPE_QUERY_RESULT = 3, } duckdb_result_type; -//! An enum over DuckDB's different statement types. +/*! + * An enum over DuckDB's different statement types. + * + * history: + * - stable: v0.10.0 + */ typedef enum duckdb_statement_type { DUCKDB_STATEMENT_TYPE_INVALID = 0, DUCKDB_STATEMENT_TYPE_SELECT = 1, @@ -191,9 +348,17 @@ typedef enum duckdb_statement_type { DUCKDB_STATEMENT_TYPE_ATTACH = 25, DUCKDB_STATEMENT_TYPE_DETACH = 26, DUCKDB_STATEMENT_TYPE_MULTI = 27, + DUCKDB_STATEMENT_TYPE_COPY_DATABASE = 28, + DUCKDB_STATEMENT_TYPE_UPDATE_EXTENSIONS = 29, + DUCKDB_STATEMENT_TYPE_MERGE_INTO = 30, } duckdb_statement_type; -//! An enum over DuckDB's different error types. +/*! + * An enum over DuckDB's different error types. + * + * history: + * - stable: v1.1.0 + */ typedef enum duckdb_error_type { DUCKDB_ERROR_INVALID = 0, DUCKDB_ERROR_OUT_OF_RANGE = 1, @@ -237,42 +402,75 @@ typedef enum duckdb_error_type { DUCKDB_ERROR_MISSING_EXTENSION = 39, DUCKDB_ERROR_AUTOLOAD = 40, DUCKDB_ERROR_SEQUENCE = 41, - DUCKDB_INVALID_CONFIGURATION = 42 + DUCKDB_ERROR_DATA_CORRUPTION = 43, + DUCKDB_INVALID_CONFIGURATION = 42, + DUCKDB_ERROR_RESOURCE_IN_USE = 44, } 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; +/*! + * An enum over DuckDB's different cast modes. + * + * history: + * - stable: v1.1.0 + */ +typedef enum duckdb_cast_mode { + DUCKDB_CAST_NORMAL = 0, + DUCKDB_CAST_TRY = 1, +} duckdb_cast_mode; +/*! + * Flags for opening files. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef enum duckdb_file_flag { DUCKDB_FILE_FLAG_INVALID = 0, - // Open the file with "read" capabilities. + + //! Open the file with read capabilities. DUCKDB_FILE_FLAG_READ = 1, - // Open the file with "write" capabilities. + + //! Open the file with write capabilities. DUCKDB_FILE_FLAG_WRITE = 2, - // Create a new file, or open if it already exists. + + //! Create a new file, or open if it already exists. DUCKDB_FILE_FLAG_CREATE = 3, - // Create a new file, or fail if it already exists. + + //! Create a new file, or fail if it already exists. DUCKDB_FILE_FLAG_CREATE_NEW = 4, - // Open the file in "append" mode. + + //! Open the file in append mode. DUCKDB_FILE_FLAG_APPEND = 5, } duckdb_file_flag; -//! An enum over DuckDB's configuration option scopes. -//! This enum can be used to specify the default scope when creating a custom configuration option, -//! but it is also be used to determine the scope in which a configuration option is set when it is -//! changed or retrieved. +/*! + * An enum over DuckDB's configuration option scopes. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef enum duckdb_config_option_scope { DUCKDB_CONFIG_OPTION_SCOPE_INVALID = 0, - // The option is set for the duration of the current transaction only. - // !! CURRENTLY NOT IMPLEMENTED !! + + //! The option is set for the duration of the current transaction only. CURRENTLY NOT IMPLEMENTED. DUCKDB_CONFIG_OPTION_SCOPE_LOCAL = 1, - // The option is set for the current session/connection only. + + //! The option is set for the current session/connection only. DUCKDB_CONFIG_OPTION_SCOPE_SESSION = 2, - // Set the option globally for all sessions/connections. + + //! Set the option globally for all sessions/connections. DUCKDB_CONFIG_OPTION_SCOPE_GLOBAL = 3, } duckdb_config_option_scope; -//! An enum over DuckDB's catalog entry types. +/*! + * An enum over DuckDB's catalog entry types. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef enum duckdb_catalog_entry_type { DUCKDB_CATALOG_ENTRY_TYPE_INVALID = 0, DUCKDB_CATALOG_ENTRY_TYPE_TABLE = 1, @@ -286,5993 +484,9906 @@ typedef enum duckdb_catalog_entry_type { DUCKDB_CATALOG_ENTRY_TYPE_DATABASE = 9, } duckdb_catalog_entry_type; -//===--------------------------------------------------------------------===// -// General type definitions -//===--------------------------------------------------------------------===// +/* --- Struct forward declarations for common_enums --- */ -//! DuckDB's index type. -typedef uint64_t idx_t; +/* --- Types for common_enums --- */ -//! Type definition for the data pointers of selection vectors. -typedef uint32_t sel_t; +/*! + * Alias for the DUCKDB_TYPE enum. + * + * history: + * - stable: v0.1.0 + */ +typedef DUCKDB_TYPE duckdb_type; -//! The callback to destroy data, e.g., -//! bind data (if any), init data (if any), extra data for replacement scans (if any), etc. -typedef void (*duckdb_delete_callback_t)(void *data); +/* --- Constants for common_enums --- */ -//! The callback to copy data, e.g., bind data (if any). -typedef void *(*duckdb_copy_callback_t)(void *data); +/* --- Function pointer typedefs for common_enums --- */ -//! Used for threading, contains a task state. -//! Must be destroyed with `duckdb_destroy_task_state`. -typedef void *duckdb_task_state; +/* --- Functions for common_enums --- */ -//===--------------------------------------------------------------------===// -// Types (no explicit freeing) -//===--------------------------------------------------------------------===// +/* --- Struct definitions for common_enums --- */ -//! DATE is stored as days since 1970-01-01. -//! Use the `duckdb_from_date` and `duckdb_to_date` functions to extract individual information. -typedef struct { +/* ============================================================================ + * MODULE: common_types + * ============================================================================ */ + +/* --- Enums for common_types --- */ + +/* --- Struct forward declarations for common_types --- */ + +typedef struct duckdb_date duckdb_date; + +typedef struct duckdb_date_struct duckdb_date_struct; + +typedef struct duckdb_time duckdb_time; + +typedef struct duckdb_time_struct duckdb_time_struct; + +typedef struct duckdb_time_ns duckdb_time_ns; + +typedef struct duckdb_time_tz duckdb_time_tz; + +typedef struct duckdb_time_tz_struct duckdb_time_tz_struct; + +typedef struct duckdb_timestamp duckdb_timestamp; + +typedef struct duckdb_timestamp_struct duckdb_timestamp_struct; + +typedef struct duckdb_timestamp_s duckdb_timestamp_s; + +typedef struct duckdb_timestamp_ms duckdb_timestamp_ms; + +typedef struct duckdb_timestamp_ns duckdb_timestamp_ns; + +typedef struct duckdb_interval duckdb_interval; + +typedef struct duckdb_hugeint duckdb_hugeint; + +typedef struct duckdb_uhugeint duckdb_uhugeint; + +typedef struct duckdb_decimal duckdb_decimal; + +typedef struct duckdb_query_progress_type duckdb_query_progress_type; + +typedef struct duckdb_list_entry duckdb_list_entry; + +typedef struct duckdb_column duckdb_column; + +typedef struct duckdb_string duckdb_string; + +typedef struct duckdb_blob duckdb_blob; + +typedef struct duckdb_bit duckdb_bit; + +typedef struct duckdb_bignum duckdb_bignum; + +typedef struct duckdb_result duckdb_result; + +/* --- Types for common_types --- */ + +/* --- Constants for common_types --- */ + +/* --- Function pointer typedefs for common_types --- */ + +/* --- Functions for common_types --- */ + +/* --- Struct definitions for common_types --- */ + +/*! + * DATE is stored as days since 1970-01-01. + * + * history: + * - stable: v0.1.0 + */ +struct duckdb_date { int32_t days; -} duckdb_date; +}; -typedef struct { +/*! + * Decomposed date components. + * + * history: + * - stable: v0.2.9 + */ +struct duckdb_date_struct { int32_t year; int8_t month; int8_t day; -} duckdb_date_struct; +}; -//! TIME is stored as microseconds since 00:00:00. -//! Use the `duckdb_from_time` and `duckdb_to_time` functions to extract individual information. -typedef struct { +/*! + * TIME is stored as microseconds since 00:00:00. + * + * history: + * - stable: v0.1.0 + */ +struct duckdb_time { int64_t micros; -} duckdb_time; +}; -typedef struct { +/*! + * Decomposed time components. + * + * history: + * - stable: v0.2.9 + */ +struct duckdb_time_struct { int8_t hour; int8_t min; int8_t sec; int32_t micros; -} duckdb_time_struct; +}; -//! TIME_NS is stored as nanoseconds since 00:00:00. -typedef struct { +/*! + * TIME_NS is stored as nanoseconds since 00:00:00. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + */ +struct duckdb_time_ns { int64_t nanos; -} duckdb_time_ns; +}; -//! TIME_TZ is stored as 40 bits for the int64_t microseconds, and 24 bits for the int32_t offset. -//! Use the `duckdb_from_time_tz` function to extract individual information. -typedef struct { +/*! + * TIME_TZ stored as 40 bits for microseconds and 24 bits for offset. + * + * history: + * - stable: v0.10.0 + */ +struct duckdb_time_tz { uint64_t bits; -} duckdb_time_tz; +}; -typedef struct { +/*! + * Decomposed TIME_TZ components. + * + * history: + * - stable: v0.10.0 + */ +struct duckdb_time_tz_struct { duckdb_time_struct time; int32_t offset; -} duckdb_time_tz_struct; +}; -//! TIMESTAMP is stored as microseconds since 1970-01-01. -//! Use the `duckdb_from_timestamp` and `duckdb_to_timestamp` functions to extract individual information. -typedef struct { +/*! + * TIMESTAMP is stored as microseconds since 1970-01-01. + * + * history: + * - stable: v0.1.0 + */ +struct duckdb_timestamp { int64_t micros; -} duckdb_timestamp; +}; -typedef struct { +/*! + * Decomposed timestamp components. + * + * history: + * - stable: v0.2.9 + */ +struct duckdb_timestamp_struct { duckdb_date_struct date; duckdb_time_struct time; -} duckdb_timestamp_struct; +}; -//! TIMESTAMP_S is stored as seconds since 1970-01-01. -typedef struct { +/*! + * TIMESTAMP_S is stored as seconds since 1970-01-01. + * + * history: + * - stable: v1.2.0 + */ +struct duckdb_timestamp_s { int64_t seconds; -} duckdb_timestamp_s; +}; -//! TIMESTAMP_MS is stored as milliseconds since 1970-01-01. -typedef struct { +/*! + * TIMESTAMP_MS is stored as milliseconds since 1970-01-01. + * + * history: + * - stable: v1.2.0 + */ +struct duckdb_timestamp_ms { int64_t millis; -} duckdb_timestamp_ms; +}; -//! TIMESTAMP_NS is stored as nanoseconds since 1970-01-01. -typedef struct { +/*! + * TIMESTAMP_NS is stored as nanoseconds since 1970-01-01. + * + * history: + * - stable: v1.2.0 + */ +struct duckdb_timestamp_ns { int64_t nanos; -} duckdb_timestamp_ns; +}; -//! INTERVAL is stored in months, days, and micros. -typedef struct { +/*! + * INTERVAL is stored in months, days, and micros. + * + * history: + * - stable: v0.2.1 + */ +struct duckdb_interval { int32_t months; int32_t days; int64_t micros; -} duckdb_interval; +}; -//! HUGEINT is composed of a lower and upper component. -//! Its value is upper * 2^64 + lower. -//! For simplified usage, use `duckdb_hugeint_to_double` and `duckdb_double_to_hugeint`. -typedef struct { +/*! + * HUGEINT is composed of a lower and upper component. Value is upper * 2^64 + lower. + * + * history: + * - stable: v0.2.1 + */ +struct duckdb_hugeint { uint64_t lower; int64_t upper; -} duckdb_hugeint; +}; -//! UHUGEINT is composed of a lower and upper component. -//! Its value is upper * 2^64 + lower. -//! For simplified usage, use `duckdb_uhugeint_to_double` and `duckdb_double_to_uhugeint`. -typedef struct { +/*! + * UHUGEINT is composed of a lower and upper component. Value is upper * 2^64 + lower. + * + * history: + * - stable: v0.10.0 + */ +struct duckdb_uhugeint { uint64_t lower; uint64_t upper; -} duckdb_uhugeint; +}; -//! DECIMAL is composed of a width and a scale. -//! Their value is stored in a HUGEINT. -typedef struct { +/*! + * DECIMAL is composed of a width and a scale. Value is stored in a HUGEINT. + * + * history: + * - stable: v0.3.3 + */ +struct duckdb_decimal { uint8_t width; uint8_t scale; duckdb_hugeint value; -} duckdb_decimal; +}; -//! A type holding information about the query execution progress. -typedef struct { +/*! + * A type holding information about the query execution progress. + * + * history: + * - stable: v0.10.0 + */ +struct duckdb_query_progress_type { double percentage; uint64_t rows_processed; uint64_t total_rows_to_process; -} duckdb_query_progress_type; - -//! The internal representation of a VARCHAR (string_t). If the VARCHAR does not -//! exceed 12 characters, then we inline it. Otherwise, we inline a four-byte prefix for faster -//! string comparisons and store a pointer to the remaining characters. This is a non- -//! owning structure, i.e., it does not have to be freed. -typedef struct { - union { - struct { - uint32_t length; - char prefix[4]; - char *ptr; - } pointer; - struct { - uint32_t length; - char inlined[12]; - } inlined; - } value; -} duckdb_string_t; +}; -//! DuckDB's LISTs are composed of a 'parent' vector holding metadata of each list, -//! and a child vector holding the entries of the lists. -//! The `duckdb_list_entry` struct contains the internal representation of a LIST metadata entry. -//! A metadata entry contains the length of the list, and its offset in the child vector. -typedef struct { +/*! + * Internal representation of a LIST metadata entry. + * + * history: + * - stable: v0.7.0 + */ +struct duckdb_list_entry { uint64_t offset; uint64_t length; -} duckdb_list_entry; +}; -//! A column consists of a pointer to its internal data. Don't operate on this type directly. -//! Instead, use functions such as `duckdb_column_data`, `duckdb_nullmask_data`, -//! `duckdb_column_type`, and `duckdb_column_name`. -typedef struct { - // Deprecated, use `duckdb_column_data`. +/*! + * A column in a result. Use accessor functions rather than accessing fields directly. + * + * history: + * - stable: v0.1.0 + */ +struct duckdb_column { void *deprecated_data; - // Deprecated, use `duckdb_nullmask_data`. bool *deprecated_nullmask; - // Deprecated, use `duckdb_column_type`. duckdb_type deprecated_type; - // Deprecated, use `duckdb_column_name`. char *deprecated_name; void *internal_data; -} duckdb_column; +}; -//! 1. A standalone vector that must be destroyed, or -//! 2. A vector to a column in a data chunk that lives as long as the data chunk lives. -typedef struct _duckdb_vector { - void *internal_ptr; -} * duckdb_vector; +/*! + * A DuckDB string (char* + size). Free data with duckdb_free. + * + * history: + * - stable: v0.6.0 + */ +struct duckdb_string { + char *data; + idx_t size; +}; -//! A selection vector is a vector of indices, which usually refer to values in a vector. -//! Can be used to slice vectors, changing their length and the order of their entries. -//! Standalone selection vectors must be destroyed. -typedef struct _duckdb_selection_vector { - void *internal_ptr; -} * duckdb_selection_vector; - -//===--------------------------------------------------------------------===// -// Types (explicit freeing/destroying) -//===--------------------------------------------------------------------===// - -//! Strings are composed of a `char` pointer and a size. -//! You must free `string.data` with `duckdb_free`. -typedef struct { - char *data; - idx_t size; -} duckdb_string; - -//! BLOBs are composed of a byte pointer and a size. -//! You must free `blob.data` with `duckdb_free`. -typedef struct { +/*! + * A DuckDB BLOB (void* + size). Free data with duckdb_free. + * + * history: + * - stable: v0.2.5 + */ +struct duckdb_blob { void *data; idx_t size; -} duckdb_blob; +}; -//! BITs are composed of a byte pointer and a size. -//! BIT byte data has 0 to 7 bits of padding. -//! The first byte contains the number of padding bits. -//! The padding bits of the second byte are set to 1, starting from the MSB. -//! You must free `data` with `duckdb_free`. -typedef struct { +/*! + * A DuckDB BIT (uint8_t* + size). Free data with duckdb_free. + * + * history: + * - stable: v1.2.0 + */ +struct duckdb_bit { uint8_t *data; idx_t size; -} duckdb_bit; +}; -//! BIGNUMs are composed of a byte pointer, a size, and an `is_negative` bool. -//! The absolute value of the number is stored in `data` in little endian format. -//! You must free `data` with `duckdb_free`. -typedef struct { +/*! + * A DuckDB BIGNUM (uint8_t* + size + is_negative). The absolute value is stored in data in big endian format. Free data + * with duckdb_free. + * + * history: + * - stable: v1.2.0 + */ +struct duckdb_bignum { uint8_t *data; idx_t size; bool is_negative; -} duckdb_bignum; +}; -//! A query result consists of a pointer to its internal data. -//! Must be freed with 'duckdb_destroy_result'. -typedef struct { - // Deprecated, use `duckdb_column_count`. +/*! + * A query result. Must be freed with duckdb_destroy_result. + * + * history: + * - stable: v0.1.0 + */ +struct duckdb_result { idx_t deprecated_column_count; - // Deprecated, use `duckdb_row_count`. idx_t deprecated_row_count; - // Deprecated, use `duckdb_rows_changed`. idx_t deprecated_rows_changed; - // Deprecated, use `duckdb_column_*`-family of functions. duckdb_column *deprecated_columns; - // Deprecated, use `duckdb_result_error`. char *deprecated_error_message; void *internal_data; -} duckdb_result; +}; + +/* ============================================================================ + * MODULE: common_handles + * ============================================================================ */ + +/* --- Enums for common_handles --- */ + +/* --- Struct forward declarations for common_handles --- */ -//! A database instance cache object. Must be destroyed with `duckdb_destroy_instance_cache`. +/* --- Types for common_handles --- */ + +/*! + * A database instance cache. Must be destroyed with duckdb_destroy_instance_cache. + * + * history: + * - unstable: v1.2.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_instance_cache { void *internal_ptr; } * duckdb_instance_cache; -//! A database object. Must be closed with `duckdb_close`. +/*! + * A database object. Must be closed with duckdb_close. + * + * history: + * - stable: v0.1.0 + */ typedef struct _duckdb_database { void *internal_ptr; } * duckdb_database; -//! A connection to a duckdb database. Must be closed with `duckdb_disconnect`. +/*! + * A connection to a duckdb database. Must be closed with duckdb_disconnect. + * + * history: + * - stable: v0.1.0 + */ typedef struct _duckdb_connection { void *internal_ptr; } * duckdb_connection; -//! A client context of a duckdb connection. Must be destroyed with `duckdb_destroy_context`. +/*! + * A client context of a duckdb connection. Must be destroyed with duckdb_destroy_client_context. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_client_context { void *internal_ptr; } * duckdb_client_context; -//! A prepared statement is a parameterized query that allows you to bind parameters to it. -//! Must be destroyed with `duckdb_destroy_prepare`. +/*! + * A prepared statement. Must be destroyed with duckdb_destroy_prepare. + * + * history: + * - stable: v0.1.0 + */ typedef struct _duckdb_prepared_statement { void *internal_ptr; } * duckdb_prepared_statement; -//! Extracted statements. Must be destroyed with `duckdb_destroy_extracted`. +/*! + * Extracted statements. Must be destroyed with duckdb_destroy_extracted. + * + * history: + * - stable: v0.7.0 + */ typedef struct _duckdb_extracted_statements { 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`. +/*! + * A pending query result. Must be destroyed with duckdb_destroy_pending. + * + * history: + * - stable: v0.5.0 + */ typedef struct _duckdb_pending_result { void *internal_ptr; } * duckdb_pending_result; -//! The appender enables fast data loading into DuckDB. -//! Must be destroyed with `duckdb_appender_destroy`. +/*! + * The appender enables fast data loading into DuckDB. Must be destroyed with duckdb_appender_destroy. + * + * history: + * - stable: v0.2.5 + */ typedef struct _duckdb_appender { void *internal_ptr; } * duckdb_appender; -//! The table description allows querying information about the table. -//! Must be destroyed with `duckdb_table_description_destroy`. +/*! + * The table description allows querying information about the table. Must be destroyed with + * duckdb_table_description_destroy. + * + * history: + * - stable: v1.1.0 + */ typedef struct _duckdb_table_description { void *internal_ptr; } * duckdb_table_description; -//! The configuration can be used to provide start-up options for a database. -//! Must be destroyed with `duckdb_destroy_config`. +/*! + * The configuration for opening a database. Must be destroyed with duckdb_destroy_config. + * + * history: + * - stable: v0.2.8 + */ typedef struct _duckdb_config { void *internal_ptr; } * duckdb_config; -//! A custom configuration option instance. Used to register custom options that can be set on a duckdb_config. -//! or by the user in SQL using `SET = `. +/*! + * A custom configuration option instance. Must be destroyed with duckdb_destroy_config_option. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_config_option { void *internal_ptr; } * duckdb_config_option; -//! A logical type. -//! Must be destroyed with `duckdb_destroy_logical_type`. +/*! + * A logical type. Must be destroyed with duckdb_destroy_logical_type. + * + * history: + * - stable: v0.3.3 + */ typedef struct _duckdb_logical_type { void *internal_ptr; } * duckdb_logical_type; -//! Holds extra information to register a custom logical type. -//! Reserved for future use. +/*! + * Holds extra information to register a custom logical type. Reserved for future use. + * + * history: + * - stable: v1.1.0 + */ typedef struct _duckdb_create_type_info { void *internal_ptr; } * duckdb_create_type_info; -//! Contains a data chunk of a duckdb_result. -//! Must be destroyed with `duckdb_destroy_data_chunk`. +/*! + * Contains a data chunk of a duckdb_result. Must be destroyed with duckdb_destroy_data_chunk. + * + * history: + * - stable: v0.3.3 + */ typedef struct _duckdb_data_chunk { void *internal_ptr; } * duckdb_data_chunk; -//! A value of a logical type. -//! Must be destroyed with `duckdb_destroy_value`. +/*! + * A value of a logical type. Must be destroyed with duckdb_destroy_value. + * + * history: + * - stable: v0.3.3 + */ typedef struct _duckdb_value { void *internal_ptr; } * duckdb_value; -//! Holds a recursive tree containing profiling metrics. -//! The tree matches the query plan, and has a top-level node. +/*! + * Holds a recursive tree containing profiling metrics. + * + * history: + * - stable: v1.1.0 + */ typedef struct _duckdb_profiling_info { void *internal_ptr; } * duckdb_profiling_info; -//! Holds error data. -//! Must be destroyed with `duckdb_destroy_error_data`. +/*! + * Holds error data. Must be destroyed with duckdb_destroy_error_data. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_error_data { void *internal_ptr; } * duckdb_error_data; -//! Holds a bound expression. -//! Must be destroyed with `duckdb_destroy_expression`. +/*! + * Holds a bound expression. Must be destroyed with duckdb_destroy_expression. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_expression { void *internal_ptr; } * duckdb_expression; -//===--------------------------------------------------------------------===// -// C API extension information -//===--------------------------------------------------------------------===// +/*! + * A vector, either standalone or a column in a data chunk. + * + * history: + * - stable: v0.3.3 + */ +typedef struct _duckdb_vector { + void *internal_ptr; +} * duckdb_vector; -//! Holds the state of the C API extension initialization process. -typedef struct _duckdb_extension_info { +/*! + * A selection vector defining a selection on top of a vector. Must be destroyed with duckdb_destroy_selection_vector. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_selection_vector { void *internal_ptr; -} * duckdb_extension_info; +} * duckdb_selection_vector; -//===--------------------------------------------------------------------===// -// Function types -//===--------------------------------------------------------------------===// +/*! + * Arrow options for transforming DuckDB schema/chunks to Arrow. Must be destroyed with duckdb_destroy_arrow_options. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_arrow_options { + void *internal_ptr; +} * duckdb_arrow_options; -//! Additional function info. -//! When setting this info, it is necessary to pass a destroy-callback function. -typedef struct _duckdb_function_info { +/*! + * An arrow result set. Must be destroyed with duckdb_destroy_arrow. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.5.6 + */ +typedef struct _duckdb_arrow { void *internal_ptr; -} * duckdb_function_info; +} * duckdb_arrow; -//! The bind info of a function. -//! When setting this info, it is necessary to pass a destroy-callback function. -typedef struct _duckdb_bind_info { +/*! + * An arrow stream wrapper. Must be destroyed with duckdb_destroy_arrow_stream. + * + * history: + * - stable: v0.9.0 + * - deprecated: v1.5.6 + */ +typedef struct _duckdb_arrow_stream { void *internal_ptr; -} * duckdb_bind_info; +} * duckdb_arrow_stream; -//! Additional function initialization info. -//! When setting this info, it is necessary to pass a destroy-callback function. -typedef struct _duckdb_init_info { +/*! + * An arrow schema wrapper. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.5.6 + */ +typedef struct _duckdb_arrow_schema { void *internal_ptr; -} * duckdb_init_info; +} * duckdb_arrow_schema; -//===--------------------------------------------------------------------===// -// Scalar function types -//===--------------------------------------------------------------------===// +/*! + * An arrow array wrapper. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.5.6 + */ +typedef struct _duckdb_arrow_array { + void *internal_ptr; +} * duckdb_arrow_array; -//! A scalar function. Must be destroyed with `duckdb_destroy_scalar_function`. -typedef struct _duckdb_scalar_function { +/*! + * Holds a converted Arrow schema. Must be destroyed with duckdb_destroy_arrow_converted_schema. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_arrow_converted_schema { void *internal_ptr; -} * duckdb_scalar_function; +} * duckdb_arrow_converted_schema; -//! A scalar function set. Must be destroyed with `duckdb_destroy_scalar_function_set`. -typedef struct _duckdb_scalar_function_set { +/*! + * File open options. Must be destroyed with duckdb_destroy_file_open_options. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_file_open_options { void *internal_ptr; -} * duckdb_scalar_function_set; +} * duckdb_file_open_options; -//! The bind function callback of the scalar function. -typedef void (*duckdb_scalar_function_bind_t)(duckdb_bind_info info); +/*! + * A file system instance. Must be destroyed with duckdb_destroy_file_system. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_file_system { + void *internal_ptr; +} * duckdb_file_system; -//! The thread-local initialization function of the scalar function. -typedef void (*duckdb_scalar_function_init_t)(duckdb_init_info info); +/*! + * A file handle. Must be destroyed with duckdb_destroy_file_handle. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_file_handle { + void *internal_ptr; +} * duckdb_file_handle; -//! The function to execute the scalar function on an input chunk. -typedef void (*duckdb_scalar_function_t)(duckdb_function_info info, duckdb_data_chunk input, duckdb_vector output); +/*! + * A handle to a database catalog. Must be destroyed with duckdb_destroy_catalog. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_catalog { + void *internal_ptr; +} * duckdb_catalog; -//===--------------------------------------------------------------------===// -// Aggregate function types -//===--------------------------------------------------------------------===// +/*! + * A handle to a catalog entry. Must be destroyed with duckdb_destroy_catalog_entry. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_catalog_entry { + void *internal_ptr; +} * duckdb_catalog_entry; -//! An aggregate function. Must be destroyed with `duckdb_destroy_aggregate_function`. +/*! + * Used for threading, contains a task state. Must be destroyed with duckdb_destroy_task_state. + * + * history: + * - stable: v0.5.0 + */ +typedef void *duckdb_task_state; + +/*! + * A scalar function. Must be destroyed with duckdb_destroy_scalar_function. + * + * history: + * - stable: v1.1.0 + */ +typedef struct _duckdb_scalar_function { + void *internal_ptr; +} * duckdb_scalar_function; + +/*! + * A scalar function set. Must be destroyed with duckdb_destroy_scalar_function_set. + * + * history: + * - stable: v1.1.0 + */ +typedef struct _duckdb_scalar_function_set { + void *internal_ptr; +} * duckdb_scalar_function_set; + +/*! + * An aggregate function. Must be destroyed with duckdb_destroy_aggregate_function. + * + * history: + * - stable: v1.1.0 + */ typedef struct _duckdb_aggregate_function { void *internal_ptr; } * duckdb_aggregate_function; -//! A aggregate function set. Must be destroyed with `duckdb_destroy_aggregate_function_set`. +/*! + * An aggregate function set. Must be destroyed with duckdb_destroy_aggregate_function_set. + * + * history: + * - stable: v1.1.0 + */ typedef struct _duckdb_aggregate_function_set { void *internal_ptr; } * duckdb_aggregate_function_set; -//! The state of an aggregate function. +/*! + * The state of an aggregate function. + * + * history: + * - stable: v1.1.0 + */ typedef struct _duckdb_aggregate_state { void *internal_ptr; } * duckdb_aggregate_state; -//! A function to return the aggregate state's size. -typedef idx_t (*duckdb_aggregate_state_size)(duckdb_function_info info); - -//! A function to initialize an aggregate state. -typedef void (*duckdb_aggregate_init_t)(duckdb_function_info info, duckdb_aggregate_state state); - -//! An optional function to destroy an aggregate state. -typedef void (*duckdb_aggregate_destroy_t)(duckdb_aggregate_state *states, idx_t count); - -//! A function to 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); - -//! A function to combine aggregate states. -typedef void (*duckdb_aggregate_combine_t)(duckdb_function_info info, duckdb_aggregate_state *source, - duckdb_aggregate_state *target, idx_t count); - -//! A function to 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 -//===--------------------------------------------------------------------===// - -//! A table function. Must be destroyed with `duckdb_destroy_table_function`. +/*! + * A table function. Must be destroyed with duckdb_destroy_table_function. + * + * history: + * - stable: v0.3.3 + */ typedef struct _duckdb_table_function { void *internal_ptr; } * duckdb_table_function; -//! The bind function of the table function. -typedef void (*duckdb_table_function_bind_t)(duckdb_bind_info info); - -//! The possibly thread-local initialization function of the table function. -typedef void (*duckdb_table_function_init_t)(duckdb_init_info info); - -//! The function to generate an output chunk during table function execution. -typedef void (*duckdb_table_function_t)(duckdb_function_info info, duckdb_data_chunk output); - -//===--------------------------------------------------------------------===// -// Copy function types -//===--------------------------------------------------------------------===// +/*! + * A cast function. Must be destroyed with duckdb_destroy_cast_function. + * + * history: + * - stable: v1.1.0 + */ +typedef struct _duckdb_cast_function { + void *internal_ptr; +} * duckdb_cast_function; -//! A COPY function. Must be destroyed with `duckdb_destroy_copy_function`. +/*! + * A COPY function. Must be destroyed with duckdb_destroy_copy_function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_copy_function { void *internal_ptr; } * duckdb_copy_function; -//! Info for the bind function of a COPY function. +/*! + * Info for the bind function of a COPY function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_copy_function_bind_info { void *internal_ptr; } * duckdb_copy_function_bind_info; -//! Info for the global initialization function of a COPY function. +/*! + * Info for the global initialization function of a COPY function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_copy_function_global_init_info { void *internal_ptr; } * duckdb_copy_function_global_init_info; -//! Info for the sink function of a COPY function. +/*! + * Info for the sink function of a COPY function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_copy_function_sink_info { void *internal_ptr; } * duckdb_copy_function_sink_info; -//! Info for the finalize function of a COPY function. +/*! + * Info for the finalize function of a COPY function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef struct _duckdb_copy_function_finalize_info { void *internal_ptr; } * duckdb_copy_function_finalize_info; -//! The bind function to use when binding a COPY ... TO function. -typedef void (*duckdb_copy_function_bind_t)(duckdb_copy_function_bind_info info); - -//! The initialization function to use when initializing a COPY ... TO function. -typedef void (*duckdb_copy_function_global_init_t)(duckdb_copy_function_global_init_info info); - -//! The function to sink an input chunk into during execution of a COPY ... TO function. -typedef void (*duckdb_copy_function_sink_t)(duckdb_copy_function_sink_info info, duckdb_data_chunk input); - -//! The function to finalize the COPY ... TO function execution. -typedef void (*duckdb_copy_function_finalize_t)(duckdb_copy_function_finalize_info info); - -//===--------------------------------------------------------------------===// -// Cast types -//===--------------------------------------------------------------------===// - -//! A cast function. Must be destroyed with `duckdb_destroy_cast_function`. -typedef struct _duckdb_cast_function { - void *internal_ptr; -} * duckdb_cast_function; - -//! The function to cast from an input vector to an output vector. -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. +/*! + * Info passed to a replacement scan callback. + * + * history: + * - stable: v0.3.3 + */ typedef struct _duckdb_replacement_scan_info { void *internal_ptr; } * duckdb_replacement_scan_info; -//! A replacement scan function. -typedef void (*duckdb_replacement_callback_t)(duckdb_replacement_scan_info info, const char *table_name, void *data); - -//===--------------------------------------------------------------------===// -// Arrow-related types -//===--------------------------------------------------------------------===// - -//! Forward declare Arrow structs -//! It is important to notice that these structs are not defined by DuckDB but are actually Arrow external objects. -//! They're defined by the C Data Interface Arrow spec: https://arrow.apache.org/docs/format/CDataInterface.html - -struct ArrowArray; - -struct ArrowSchema; - -//! Holds an arrow query result. Must be destroyed with `duckdb_destroy_arrow`. -typedef struct _duckdb_arrow { +/*! + * A log storage instance. Must be destroyed with duckdb_destroy_log_storage. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef struct _duckdb_log_storage { void *internal_ptr; -} * duckdb_arrow; +} * duckdb_log_storage; -//! Holds an arrow array stream. Must be destroyed with `duckdb_destroy_arrow_stream`. -typedef struct _duckdb_arrow_stream { +/*! + * Additional function info. + * + * history: + * - stable: v0.3.3 + */ +typedef struct _duckdb_function_info { void *internal_ptr; -} * duckdb_arrow_stream; +} * duckdb_function_info; -//! Holds an arrow schema. Remember to release the respective ArrowSchema object. -typedef struct _duckdb_arrow_schema { +/*! + * The bind info of a function. + * + * history: + * - stable: v0.3.3 + */ +typedef struct _duckdb_bind_info { void *internal_ptr; -} * duckdb_arrow_schema; +} * duckdb_bind_info; -//! Holds an arrow converted schema (i.e., duckdb::ArrowTableSchema). -//! In practice, this object holds the information necessary to do proper conversion between Arrow Types and DuckDB -//! Types. Check duckdb/function/table/arrow/arrow_duck_schema.hpp for more details! Must be destroyed with -//! `duckdb_destroy_arrow_converted_schema` -typedef struct _duckdb_arrow_converted_schema { +/*! + * Additional function initialization info. + * + * history: + * - stable: v0.3.3 + */ +typedef struct _duckdb_init_info { void *internal_ptr; -} * duckdb_arrow_converted_schema; +} * duckdb_init_info; -//! Holds an arrow array. Remember to release the respective ArrowSchema object. -typedef struct _duckdb_arrow_array { +/*! + * Holds the state of the C API extension initialization process. + * + * history: + * - stable: v1.1.0 + */ +typedef struct _duckdb_extension_info { void *internal_ptr; -} * duckdb_arrow_array; +} * duckdb_extension_info; -//! The arrow options used when transforming the DuckDB schema and datachunks into Arrow schema and arrays. -//! Used in `duckdb_to_arrow_schema` and `duckdb_data_chunk_to_arrow` -typedef struct _duckdb_arrow_options { - void *internal_ptr; -} * duckdb_arrow_options; +/*! + * Type definition for the data pointers of selection vectors. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + */ +#ifndef DUCKDB_TYPEDEF_SEL_T +#define DUCKDB_TYPEDEF_SEL_T +typedef uint32_t sel_t; +#endif -//===--------------------------------------------------------------------===// -// Virtual File System Access -//===--------------------------------------------------------------------===// +/* --- Constants for common_handles --- */ -typedef struct _duckdb_file_open_options { - void *internal_ptr; -} * duckdb_file_open_options; +/* --- Function pointer typedefs for common_handles --- */ -typedef struct _duckdb_file_system { - void *internal_ptr; -} * duckdb_file_system; +/*! + * The callback to destroy data. + * + * history: + * - stable: v0.3.3 + */ +typedef void (*duckdb_delete_callback_t)(void *data); -typedef struct _duckdb_file_handle { - void *internal_ptr; -} * duckdb_file_handle; +/*! + * The callback to copy data. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + */ +typedef void *(*duckdb_copy_callback_t)(void *data); -//===--------------------------------------------------------------------===// -// Catalog Interface -//===--------------------------------------------------------------------===// +/*! + * The bind function of a table function. + * + * history: + * - stable: v0.3.3 + */ +typedef void (*duckdb_table_function_bind_t)(duckdb_bind_info info); -//! A handle to a database catalog. -//! Must be destroyed with `duckdb_destroy_catalog`. -typedef struct _duckdb_catalog { - void *internal_ptr; -} * duckdb_catalog; +/*! + * The init function of a table function. + * + * history: + * - stable: v0.3.3 + */ +typedef void (*duckdb_table_function_init_t)(duckdb_init_info info); -//! A handle to a catalog entry (e.g., table, view, index, etc.). -//! Must be destroyed with `duckdb_destroy_catalog_entry`. -typedef struct _duckdb_catalog_entry { - void *internal_ptr; -} * duckdb_catalog_entry; +/*! + * The main function of a table function. + * + * history: + * - stable: v0.3.3 + */ +typedef void (*duckdb_table_function_t)(duckdb_function_info info, duckdb_data_chunk output); -//===--------------------------------------------------------------------===// -// Logging Types -//===--------------------------------------------------------------------===// - -//! Holds a log storage object. -typedef struct _duckdb_log_storage { - void *internal_ptr; -} * duckdb_log_storage; +/*! + * The callback function for replacement scans. + * + * history: + * - stable: v0.3.3 + */ +typedef void (*duckdb_replacement_callback_t)(duckdb_replacement_scan_info info, const char *table_name, void *data); -//! This function is missing the logging context, which will be added later. +/*! + * The callback to write a log entry. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ typedef void (*duckdb_logger_write_log_entry_t)(void *extra_data, duckdb_timestamp *timestamp, const char *level, const char *log_type, const char *log_message); -//===--------------------------------------------------------------------===// -// DuckDB extension access -//===--------------------------------------------------------------------===// - -//! Passed to C API extension as a parameter to the entrypoint. -struct duckdb_extension_access { - //! Indicate that an error has occurred. - void (*set_error)(duckdb_extension_info info, const char *error); - //! Fetch the database on which to register the extension. - duckdb_database *(*get_database)(duckdb_extension_info info); - //! Fetch the API struct pointer. - const void *(*get_api)(duckdb_extension_info info, const char *version); -}; - -#ifndef DUCKDB_API_EXCLUDE_FUNCTIONS - -//===--------------------------------------------------------------------===// -// Functions -//===--------------------------------------------------------------------===// - -//---------------------------------------------------------------------------------------------------------------------- -// Open Connect -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to operate on the instance cache, databases, connections, as well as some metadata functions. -//---------------------------------------------------------------------------------------------------------------------- - /*! -Creates a new database instance cache. -The instance cache is necessary if a client/program (re)opens multiple databases to the same file within the same -process. Must be destroyed with 'duckdb_destroy_instance_cache'. - -* @return The database instance cache. -*/ -DUCKDB_C_API duckdb_instance_cache duckdb_create_instance_cache(); - -/*! -Creates a new database instance in the instance cache, or retrieves an existing database instance. -Must be closed with 'duckdb_close'. - -* @param instance_cache The instance cache in which to create the database, or from which to take the database. -* @param path Path to the database file on disk. Both `nullptr` and `:memory:` open or retrieve an in-memory database. -* @param out_database The resulting cached database. -* @param config (Optional) configuration used to create the database. -* @param out_error If set and the function returns `DuckDBError`, this contains the error message. -Note that the error message must be freed using `duckdb_free`. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_get_or_create_from_cache(duckdb_instance_cache instance_cache, const char *path, - duckdb_database *out_database, duckdb_config config, - char **out_error); + * The sink function of a copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef void (*duckdb_copy_function_sink_t)(duckdb_copy_function_sink_info info, duckdb_data_chunk input); /*! -Destroys an existing database instance cache and de-allocates its memory. - -* @param instance_cache The instance cache to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_instance_cache(duckdb_instance_cache *instance_cache); + * The finalize function of a copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef void (*duckdb_copy_function_finalize_t)(duckdb_copy_function_finalize_info info); /*! -Creates a new database or opens an existing database file stored at the given path. -If no path is given a new in-memory database is created instead. -The database must be closed with 'duckdb_close'. - -* @param path Path to the database file on disk. Both `nullptr` and `:memory:` open an in-memory database. -* @param out_database The result database object. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_open(const char *path, duckdb_database *out_database); + * A function to get the size of an aggregate state. + * + * history: + * - stable: v1.1.0 + */ +typedef idx_t (*duckdb_aggregate_state_size)(duckdb_function_info info); /*! -Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the given path. -The database must be closed with 'duckdb_close'. - -* @param path Path to the database file on disk. Both `nullptr` and `:memory:` open an in-memory database. -* @param out_database The result database object. -* @param config (Optional) configuration used to start up the database. -* @param out_error If set and the function returns `DuckDBError`, this contains the error message. -Note that the error message must be freed using `duckdb_free`. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config, - char **out_error); + * A function to initialize an aggregate state. + * + * history: + * - stable: v1.1.0 + */ +typedef void (*duckdb_aggregate_init_t)(duckdb_function_info info, duckdb_aggregate_state state); /*! -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` or `duckdb_open_ext`. -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. - -* @param database The database object to shut down. -*/ -DUCKDB_C_API void duckdb_close(duckdb_database *database); + * An optional function to destroy an aggregate state. + * + * history: + * - stable: v1.1.0 + */ +typedef void (*duckdb_aggregate_destroy_t)(duckdb_aggregate_state *states, idx_t count); /*! -Opens a connection to a database. Connections are required to query the database, and store transactional state -associated with the connection. -The instantiated connection should be closed using 'duckdb_disconnect'. - -* @param database The database file to connect to. -* @param out_connection The result connection object. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection); + * A function to update a set of aggregate states with new values. + * + * history: + * - stable: v1.1.0 + */ +typedef void (*duckdb_aggregate_update_t)(duckdb_function_info info, duckdb_data_chunk input, + duckdb_aggregate_state *states); /*! -Interrupt running query - -* @param connection The connection to interrupt -*/ -DUCKDB_C_API void duckdb_interrupt(duckdb_connection connection); + * A function to combine aggregate states. + * + * history: + * - stable: v1.1.0 + */ +typedef void (*duckdb_aggregate_combine_t)(duckdb_function_info info, duckdb_aggregate_state *source, + duckdb_aggregate_state *target, idx_t count); /*! -Get the progress of the running query. - -* @param connection The connection running the query. -* @return The query progress type containing progress information. -*/ -DUCKDB_C_API duckdb_query_progress_type duckdb_query_progress(duckdb_connection connection); + * A function to finalize aggregate states into a result vector. + * + * history: + * - stable: v1.1.0 + */ +typedef void (*duckdb_aggregate_finalize_t)(duckdb_function_info info, duckdb_aggregate_state *source, + duckdb_vector result, idx_t count, idx_t offset); /*! -Closes the specified connection and de-allocates all memory allocated for that connection. - -* @param connection The connection to close. -*/ -DUCKDB_C_API void duckdb_disconnect(duckdb_connection *connection); + * The bind function of a scalar function. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + */ +typedef void (*duckdb_scalar_function_bind_t)(duckdb_bind_info info); /*! -Retrieves the client context of the connection. - -* @param connection The connection. -* @param out_context The client context of the connection. Must be destroyed with `duckdb_destroy_client_context`. -*/ -DUCKDB_C_API void duckdb_connection_get_client_context(duckdb_connection connection, - duckdb_client_context *out_context); + * The init function of a scalar function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef void (*duckdb_scalar_function_init_t)(duckdb_init_info info); /*! -Retrieves the arrow options of the connection. - -* @param connection The connection. -*/ -DUCKDB_C_API void duckdb_connection_get_arrow_options(duckdb_connection connection, - duckdb_arrow_options *out_arrow_options); + * The main function of a scalar function. + * + * history: + * - stable: v1.1.0 + */ +typedef void (*duckdb_scalar_function_t)(duckdb_function_info info, duckdb_data_chunk input, duckdb_vector output); /*! -Returns the connection id of the client context. - -* @param context The client context. -* @return The connection id of the client context. -*/ -DUCKDB_C_API idx_t duckdb_client_context_get_connection_id(duckdb_client_context context); + * The function to cast from an input vector to an output vector. + * + * history: + * - stable: v1.1.0 + */ +typedef bool (*duckdb_cast_function_t)(duckdb_function_info info, idx_t count, duckdb_vector input, + duckdb_vector output); /*! -Destroys the client context and deallocates its memory. - -* @param context The client context to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_client_context(duckdb_client_context *context); + * The bind function of a copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef void (*duckdb_copy_function_bind_t)(duckdb_copy_function_bind_info info); /*! -Destroys the arrow options and deallocates its memory. - -* @param arrow_options The arrow options to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_arrow_options(duckdb_arrow_options *arrow_options); + * The global initialization function of a copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + */ +typedef void (*duckdb_copy_function_global_init_t)(duckdb_copy_function_global_init_info info); -/*! -Returns the version of the linked DuckDB, with a version postfix for dev versions +/* --- Functions for common_handles --- */ -Usually used for developing C extensions that must return this for a compatibility check. -*/ -DUCKDB_C_API const char *duckdb_library_version(); +/* --- Struct definitions for common_handles --- */ -/*! -Get the list of (fully qualified) table names of the query. +/* ============================================================================ + * MODULE: datetime_helpers + * ============================================================================ */ -* @param connection The connection for which to get the table names. -* @param query The query for which to get the table names. -* @param qualified Returns fully qualified table names (catalog.schema.table), if set to true, else only the (not -escaped) table names. -* @return A duckdb_value of type VARCHAR[] containing the (fully qualified) table names of the query. Must be destroyed -with duckdb_destroy_value. -*/ -DUCKDB_C_API duckdb_value duckdb_get_table_names(duckdb_connection connection, const char *query, bool qualified); +/* --- Enums for datetime_helpers --- */ -//---------------------------------------------------------------------------------------------------------------------- -// Configuration -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to interact with a `duckdb_config`, which is the configuration parameter for opening a database. -//---------------------------------------------------------------------------------------------------------------------- +/* --- Struct forward declarations for datetime_helpers --- */ -/*! -Initializes an empty configuration object that can be used to provide start-up options for the DuckDB instance -through `duckdb_open_ext`. -The duckdb_config must be destroyed using 'duckdb_destroy_config' +/* --- Types for datetime_helpers --- */ -This will always succeed unless there is a malloc failure. +/* --- Constants for datetime_helpers --- */ -Note that `duckdb_destroy_config` should always be called on the resulting config, even if the function returns -`DuckDBError`. +/* --- Function pointer typedefs for datetime_helpers --- */ -* @param out_config The result configuration object. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_create_config(duckdb_config *out_config); +/* --- Functions for datetime_helpers --- */ +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) /*! -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. - -* @return The amount of config options available. -*/ -DUCKDB_C_API size_t duckdb_config_count(); + * Decompose a `duckdb_date` object into year, month and date (stored as `duckdb_date_struct`). + * + * history: + * - stable: v0.2.9 + * + * @param date The date object, as obtained from a `DUCKDB_TYPE_DATE` column. + * @return duckdb_date_struct + */ +DUCKDB_C_API duckdb_date_struct duckdb_from_date(duckdb_date date); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) /*! -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. - -* @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_C_API duckdb_state duckdb_get_config_flag(size_t index, const char **out_name, const char **out_description); + * Re-compose a `duckdb_date` from year, month and date (`duckdb_date_struct`). + * + * history: + * - stable: v0.2.9 + * + * @param date The year, month and date stored in a `duckdb_date_struct`. + * @return duckdb_date + */ +DUCKDB_C_API duckdb_date duckdb_to_date(duckdb_date_struct date); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) /*! -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. - -* @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_C_API duckdb_state duckdb_set_config(duckdb_config config, const char *name, const char *option); + * Test a `duckdb_date` to see if it is a finite value. + * + * history: + * - stable: v0.10.0 + * + * @param date The date object, as obtained from a `DUCKDB_TYPE_DATE` column. + * @return bool + */ +DUCKDB_C_API bool duckdb_is_finite_date(duckdb_date date); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) /*! -Destroys the specified configuration object and de-allocates all memory allocated for the object. + * Decompose a `duckdb_time` object into hour, minute, second and microsecond (stored as `duckdb_time_struct`). + * + * history: + * - stable: v0.2.9 + * + * @param time The time object, as obtained from a `DUCKDB_TYPE_TIME` column. + * @return duckdb_time_struct + */ +DUCKDB_C_API duckdb_time_struct duckdb_from_time(duckdb_time time); +#endif -* @param config The configuration object to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_config(duckdb_config *config); +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * Create a `duckdb_time_tz` object from micros and a timezone offset. + * + * history: + * - stable: v0.10.0 + * + * @param micros The microsecond component of the time. + * @param offset The timezone offset component of the time. + * @return duckdb_time_tz + */ +DUCKDB_C_API duckdb_time_tz duckdb_create_time_tz(int64_t micros, int32_t offset); +#endif -//---------------------------------------------------------------------------------------------------------------------- -// Error Data -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to operate on `duckdb_error_data`, which contains, for example, the error type and message. Please use this -// interface for all new C API functions, as it supersedes previous error handling approaches. -//---------------------------------------------------------------------------------------------------------------------- +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * 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. + * + * history: + * - stable: v0.10.0 + * + * @param micros The time object, as obtained from a `DUCKDB_TYPE_TIME_TZ` column. + * @return duckdb_time_tz_struct + */ +DUCKDB_C_API duckdb_time_tz_struct duckdb_from_time_tz(duckdb_time_tz micros); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) /*! -Creates duckdb_error_data. -Must be destroyed with `duckdb_destroy_error_data`. - -* @param type The error type. -* @param message The error message. -* @return The error data. -*/ -DUCKDB_C_API duckdb_error_data duckdb_create_error_data(duckdb_error_type type, const char *message); + * Re-compose a `duckdb_time` from hour, minute, second and microsecond (`duckdb_time_struct`). + * + * history: + * - stable: v0.2.9 + * + * @param time The hour, minute, second and microsecond in a `duckdb_time_struct`. + * @return duckdb_time + */ +DUCKDB_C_API duckdb_time duckdb_to_time(duckdb_time_struct time); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) /*! -Destroys the error data and deallocates its memory. - -* @param error_data The error data to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_error_data(duckdb_error_data *error_data); + * Decompose a `duckdb_timestamp` object into a `duckdb_timestamp_struct`. + * + * history: + * - stable: v0.2.9 + * + * @param ts The ts object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column. + * @return duckdb_timestamp_struct + */ +DUCKDB_C_API duckdb_timestamp_struct duckdb_from_timestamp(duckdb_timestamp ts); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) /*! -Returns the duckdb_error_type of the error data. - -* @param error_data The error data. -* @return The error type. -*/ -DUCKDB_C_API duckdb_error_type duckdb_error_data_error_type(duckdb_error_data error_data); + * Re-compose a `duckdb_timestamp` from a duckdb_timestamp_struct. + * + * history: + * - stable: v0.2.9 + * + * @param ts The de-composed elements in a `duckdb_timestamp_struct`. + * @return duckdb_timestamp + */ +DUCKDB_C_API duckdb_timestamp duckdb_to_timestamp(duckdb_timestamp_struct ts); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) /*! -Returns the error message of the error data. Must not be freed. - -* @param error_data The error data. -* @return The error message. -*/ -DUCKDB_C_API const char *duckdb_error_data_message(duckdb_error_data error_data); + * Test a `duckdb_timestamp` to see if it is a finite value. + * + * history: + * - stable: v0.10.0 + * + * @param ts The duckdb_timestamp object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column. + * @return bool + */ +DUCKDB_C_API bool duckdb_is_finite_timestamp(duckdb_timestamp ts); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 2, 0) /*! -Returns whether the error data contains an error or not. - -* @param error_data The error data. -* @return True, if the error data contains an exception, else false. -*/ -DUCKDB_C_API bool duckdb_error_data_has_error(duckdb_error_data error_data); - -//---------------------------------------------------------------------------------------------------------------------- -// Query Execution -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to obtain a `duckdb_result` and to retrieve metadata from it. -//---------------------------------------------------------------------------------------------------------------------- + * Test a `duckdb_timestamp_s` to see if it is a finite value. + * + * history: + * - stable: v1.2.0 + * + * @param ts The duckdb_timestamp_s object, as obtained from a `DUCKDB_TYPE_TIMESTAMP_S` column. + * @return bool + */ +DUCKDB_C_API bool duckdb_is_finite_timestamp_s(duckdb_timestamp_s ts); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 2, 0) /*! -Executes a SQL query within a connection and stores the full (materialized) result in the out_result pointer. -If the query fails to execute, DuckDBError is returned and the error message can be retrieved by calling -`duckdb_result_error`. - -Note that after running `duckdb_query`, `duckdb_destroy_result` must be called on the result object even if the -query fails, otherwise the error stored within the result will not be freed correctly. + * Test a `duckdb_timestamp_ms` to see if it is a finite value. + * + * history: + * - stable: v1.2.0 + * + * @param ts The duckdb_timestamp_ms object, as obtained from a `DUCKDB_TYPE_TIMESTAMP_MS` column. + * @return bool + */ +DUCKDB_C_API bool duckdb_is_finite_timestamp_ms(duckdb_timestamp_ms ts); +#endif -* @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_C_API duckdb_state duckdb_query(duckdb_connection connection, const char *query, duckdb_result *out_result); +#if DUCKDB_API_VERSION_AT_LEAST(1, 2, 0) +/*! + * Test a `duckdb_timestamp_ns` to see if it is a finite value. + * + * history: + * - stable: v1.2.0 + * + * @param ts The duckdb_timestamp_ns object, as obtained from a `DUCKDB_TYPE_TIMESTAMP_NS` column. + * @return bool + */ +DUCKDB_C_API bool duckdb_is_finite_timestamp_ns(duckdb_timestamp_ns ts); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) /*! -Closes the result and de-allocates all memory allocated for that result. + * Converts a duckdb_hugeint object (as obtained from a `DUCKDB_TYPE_HUGEINT` column) into a double. + * + * history: + * - stable: v0.2.9 + * + * @param val The hugeint value. + * @return double + */ +DUCKDB_C_API double duckdb_hugeint_to_double(duckdb_hugeint val); +#endif -* @param result The result to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_result(duckdb_result *result); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) +/*! + * 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. + * + * history: + * - stable: v0.2.9 + * + * @param val The double value. + * @return duckdb_hugeint + */ +DUCKDB_C_API duckdb_hugeint duckdb_double_to_hugeint(double val); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) /*! -Returns the column name of the specified column. The result should not need to be freed; the column names will -automatically be destroyed when the result is destroyed. + * Converts a duckdb_uhugeint object (as obtained from a `DUCKDB_TYPE_UHUGEINT` column) into a double. + * + * history: + * - stable: v0.10.0 + * + * @param val The uhugeint value. + * @return double + */ +DUCKDB_C_API double duckdb_uhugeint_to_double(duckdb_uhugeint val); +#endif -Returns `NULL` if the column is out of range. +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * 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. + * + * history: + * - stable: v0.10.0 + * + * @param val The double value. + * @return duckdb_uhugeint + */ +DUCKDB_C_API duckdb_uhugeint duckdb_double_to_uhugeint(double val); +#endif -* @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_C_API const char *duckdb_column_name(duckdb_result *result, idx_t col); +#if DUCKDB_API_VERSION_AT_LEAST(0, 6, 0) +/*! + * 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. + * + * history: + * - stable: v0.6.0 + * + * @param val The double value. + * @param width + * @param scale + * @return duckdb_decimal + */ +DUCKDB_C_API duckdb_decimal duckdb_double_to_decimal(double val, uint8_t width, uint8_t scale); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Returns the column type of the specified column. + * Converts a duckdb_decimal object (as obtained from a `DUCKDB_TYPE_DECIMAL` column) into a double. + * + * history: + * - stable: v0.3.3 + * + * @param val The decimal value. + * @return double + */ +DUCKDB_C_API double duckdb_decimal_to_double(duckdb_decimal val); +#endif -Returns `DUCKDB_TYPE_INVALID` if the column is out of range. +/* --- Struct definitions for datetime_helpers --- */ -* @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_C_API duckdb_type duckdb_column_type(duckdb_result *result, idx_t col); +/* ============================================================================ + * MODULE: aggregate_function + * ============================================================================ */ -/*! -Returns the statement type of the statement that was executed +/* --- Enums for aggregate_function --- */ -* @param result The result object to fetch the statement type from. -* @return duckdb_statement_type value or DUCKDB_STATEMENT_TYPE_INVALID -*/ -DUCKDB_C_API duckdb_statement_type duckdb_result_statement_type(duckdb_result result); +/* --- Struct forward declarations for aggregate_function --- */ -/*! -Returns the logical column type of the specified column. +/* --- Types for aggregate_function --- */ -The return type of this call should be destroyed with `duckdb_destroy_logical_type`. +/* --- Constants for aggregate_function --- */ -Returns `NULL` if the column is out of range. +/* --- Function pointer typedefs for aggregate_function --- */ -* @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_C_API duckdb_logical_type duckdb_column_logical_type(duckdb_result *result, idx_t col); +/* --- Functions for aggregate_function --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Returns the arrow options associated with the given result. These options are definitions of how the arrow arrays/schema -should be produced. -* @param result The result object to fetch arrow options from. -* @return The arrow options associated with the given result. This must be destroyed with -`duckdb_destroy_arrow_options`. -*/ -DUCKDB_C_API duckdb_arrow_options duckdb_result_get_arrow_options(duckdb_result *result); + * Creates a new empty aggregate function. + * + * The return value should be destroyed with `duckdb_destroy_aggregate_function`. + * + * history: + * - stable: v1.1.0 + * + * @return duckdb_aggregate_function + */ +DUCKDB_C_API duckdb_aggregate_function duckdb_create_aggregate_function(void); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Returns the number of columns present in a the result object. - -* @param result The result object. -* @return The number of columns present in the result object. -*/ -DUCKDB_C_API idx_t duckdb_column_count(duckdb_result *result); + * Destroys the given aggregate function object. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function + * @return void + */ +DUCKDB_C_API void duckdb_destroy_aggregate_function(duckdb_aggregate_function *aggregate_function); +#endif -#ifndef DUCKDB_API_NO_DEPRECATED -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the name of the given aggregate function. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function The aggregate function + * @param name The name of the aggregate function + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_set_name(duckdb_aggregate_function aggregate_function, const char *name); +#endif -Returns the number of rows present in the result object. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Adds a parameter to the aggregate function. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function The aggregate function. + * @param type The parameter type. Cannot contain INVALID. + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_add_parameter(duckdb_aggregate_function aggregate_function, + duckdb_logical_type type); +#endif -* @param result The result object. -* @return The number of rows present in the result object. -*/ -DUCKDB_C_API idx_t duckdb_row_count(duckdb_result *result); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the return type of the aggregate function. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function The aggregate function. + * @param type The return type. Cannot contain INVALID or ANY. + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_set_return_type(duckdb_aggregate_function aggregate_function, + duckdb_logical_type type); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the main functions of the aggregate function. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function The aggregate function + * @param state_size state size + * @param state_init state init function + * @param update update states + * @param combine combine states + * @param finalize finalize states + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_set_functions(duckdb_aggregate_function aggregate_function, + duckdb_aggregate_state_size state_size, + duckdb_aggregate_init_t state_init, + duckdb_aggregate_update_t update, + duckdb_aggregate_combine_t combine, + duckdb_aggregate_finalize_t finalize); #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. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the state destructor callback of the aggregate function (optional) + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function The aggregate function + * @param destroy state destroy callback + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_set_destructor(duckdb_aggregate_function aggregate_function, + duckdb_aggregate_destroy_t destroy); +#endif -* @param result The result object. -* @return The number of rows changed. -*/ -DUCKDB_C_API idx_t duckdb_rows_changed(duckdb_result *result); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Register the aggregate function object within the given connection. + * + * The function requires at least a name, functions and a return type. + * + * If the function is incomplete or a function with this name already exists DuckDBError is returned. + * + * history: + * - stable: v1.1.0 + * + * @param con The connection to register it in. + * @param aggregate_function + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_register_aggregate_function(duckdb_connection con, + duckdb_aggregate_function aggregate_function); +#endif -#ifndef DUCKDB_API_NO_DEPRECATED +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -**DEPRECATED**: Prefer using `duckdb_result_get_chunk` instead. + * Sets the NULL handling of the aggregate function to SPECIAL_HANDLING. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function The aggregate function + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_set_special_handling(duckdb_aggregate_function aggregate_function); +#endif -Returns the data of a specific column of a result in columnar format. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Assigns extra information to the scalar function that can be fetched during binding, etc. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function The aggregate function + * @param extra_info The extra information + * @param destroy The callback that will be called to destroy the extra information (if any) + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_set_extra_info(duckdb_aggregate_function aggregate_function, + void *extra_info, duckdb_delete_callback_t destroy); +#endif -The function returns a dense array which contains the result data. The exact type stored in the array depends on the -corresponding duckdb_type (as provided by `duckdb_column_type`). For the exact type by which the data should be -accessed, see the comments in [the types section](types) or the `DUCKDB_TYPE` enum. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Retrieves the extra info of the function as set in `duckdb_aggregate_function_set_extra_info`. + * + * history: + * - stable: v1.1.0 + * + * @param info The info object + * @return void* + */ +DUCKDB_C_API void *duckdb_aggregate_function_get_extra_info(duckdb_function_info info); +#endif -For example, for a column of type `DUCKDB_TYPE_INTEGER`, rows can be accessed in the following manner: -```c -int32_t *data = (int32_t *) duckdb_column_data(&result, 0); -printf("Data for row %d: %d\n", row, data[row]); -``` +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Report that an error has occurred while executing the aggregate function. + * + * history: + * - stable: v1.1.0 + * + * @param info The info object + * @param error The error message + * @return void + */ +DUCKDB_C_API void duckdb_aggregate_function_set_error(duckdb_function_info info, const char *error); +#endif -* @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_C_API void *duckdb_column_data(duckdb_result *result, idx_t col); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Creates a new empty aggregate function set. + * + * The return value should be destroyed with `duckdb_destroy_aggregate_function_set`. + * + * history: + * - stable: v1.1.0 + * + * @param name + * @return duckdb_aggregate_function_set + */ +DUCKDB_C_API duckdb_aggregate_function_set duckdb_create_aggregate_function_set(const char *name); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -**DEPRECATED**: Prefer using `duckdb_result_get_chunk` instead. + * Destroys the given aggregate function set object. + * + * history: + * - stable: v1.1.0 + * + * @param aggregate_function_set + * @return void + */ +DUCKDB_C_API void duckdb_destroy_aggregate_function_set(duckdb_aggregate_function_set *aggregate_function_set); +#endif -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. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Adds the aggregate function as a new overload to the aggregate function set. + * + * Returns DuckDBError if the function could not be added, for example if the overload already exists. + * + * history: + * - stable: v1.1.0 + * + * @param set The aggregate function set + * @param function The function to add + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_add_aggregate_function_to_set(duckdb_aggregate_function_set set, + duckdb_aggregate_function function); +#endif -```c -int32_t *data = (int32_t *) duckdb_column_data(&result, 0); -bool *nullmask = duckdb_nullmask_data(&result, 0); -if (nullmask[row]) { - printf("Data for row %d: NULL\n", row); -} else { - printf("Data for row %d: %d\n", row, data[row]); -} -``` +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Register the aggregate function set within the given connection. + * + * The set requires at least a single valid overload. + * + * If the set is incomplete or a function with this name already exists DuckDBError is returned. + * + * history: + * - stable: v1.1.0 + * + * @param con The connection to register it in. + * @param set The function set to register + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_register_aggregate_function_set(duckdb_connection con, + duckdb_aggregate_function_set set); +#endif -* @param result The result object to fetch the nullmask from. -* @param col The column index. -* @return The nullmask of the specified column. -*/ -DUCKDB_C_API bool *duckdb_nullmask_data(duckdb_result *result, idx_t col); +/* --- Struct definitions for aggregate_function --- */ -#endif +/* ============================================================================ + * MODULE: appender + * ============================================================================ */ -/*! -Returns the error message contained within the result. The error is only set if `duckdb_query` returns `DuckDBError`. +/* --- Enums for appender --- */ -The result of this function must not be freed. It will be cleaned up when `duckdb_destroy_result` is called. +/* --- Struct forward declarations for appender --- */ -* @param result The result object to fetch the error from. -* @return The error of the result. -*/ -DUCKDB_C_API const char *duckdb_result_error(duckdb_result *result); +/* --- Types for appender --- */ -/*! -Returns the result error type contained within the result. The error is only set if `duckdb_query` returns -`DuckDBError`. +/* --- Constants for appender --- */ -* @param result The result object to fetch the error from. -* @return The error type of the result. -*/ -DUCKDB_C_API duckdb_error_type duckdb_result_error_type(duckdb_result *result); +/* --- Function pointer typedefs for appender --- */ -#ifndef DUCKDB_API_NO_DEPRECATED +/* --- Functions for appender --- */ + +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) /*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * Creates an appender object. + * + * Note that the object must be destroyed with `duckdb_appender_destroy`. + * + * history: + * - stable: v0.2.5 + * + * @param connection The connection context to create the appender in. + * @param schema The schema of the table to append to, or `nullptr` for the default schema. + * @param table The table name to append to. + * @param out_appender The resulting appender object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table, + duckdb_appender *out_appender); +#endif -Fetches a data chunk from the duckdb_result. This function should be called repeatedly until the result is exhausted. +#if DUCKDB_API_VERSION_AT_LEAST(1, 2, 0) +/*! + * Creates an appender object. + * + * Note that the object must be destroyed with `duckdb_appender_destroy`. + * + * history: + * - stable: v1.2.0 + * + * @param connection The connection context to create the appender in. + * @param catalog The catalog of the table to append to, or `nullptr` for the default catalog. + * @param schema The schema of the table to append to, or `nullptr` for the default schema. + * @param table The table name to append to. + * @param out_appender The resulting appender object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_create_ext(duckdb_connection connection, const char *catalog, + const char *schema, const char *table, + duckdb_appender *out_appender); +#endif -The result must be destroyed with `duckdb_destroy_data_chunk`. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Creates an appender object that executes the given query with any data appended to it. + * + * Note that the object must be destroyed with `duckdb_appender_destroy`. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param connection The connection context to create the appender in. + * @param query The query to execute, can be an INSERT, DELETE, UPDATE or MERGE INTO statement. + * @param column_count The number of columns to append. + * @param types The types of the columns to append. + * @param table_name (optionally) the table name used to refer to the appended data, defaults to "appended_data". + * @param column_names (optionally) the list of column names, defaults to "col1", "col2", ... + * @param out_appender The resulting appender object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_create_query(duckdb_connection connection, const char *query, + idx_t column_count, duckdb_logical_type *types, + const char *table_name, const char **column_names, + duckdb_appender *out_appender); +#endif -This function supersedes all `duckdb_value` functions, as well as the `duckdb_column_data` and `duckdb_nullmask_data` -functions. It results in significantly better performance, and should be preferred in newer code-bases. +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * Returns the number of columns that belong to the appender. If there is no active column list, then this equals the + * table's physical columns. + * + * history: + * - stable: v0.10.0 + * + * @param appender The appender to get the column count from. + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_appender_column_count(duckdb_appender appender); +#endif -If this function is used, none of the other result functions can be used and vice versa (i.e. this function cannot be -mixed with the legacy result functions). +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * Returns the type of the column at the specified index. This is either a type in the active column list, or the same + * type as a column in the receiving table. + * + * Note: The resulting type must be destroyed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.10.0 + * + * @param appender The appender to get the column type from. + * @param col_idx The index of the column to get the type of. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_appender_column_type(duckdb_appender appender, idx_t col_idx); +#endif -Use `duckdb_result_chunk_count` to figure out how many chunks there are in the result. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Returns the error data associated with the appender. Must be destroyed with duckdb_destroy_error_data. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param appender The appender to get the error data from. + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_appender_error_data(duckdb_appender appender); +#endif -* @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_C_API duckdb_data_chunk duckdb_result_get_chunk(duckdb_result result, idx_t chunk_index); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Flush the appender to the table, forcing the cache of the appender to be cleared. Requires a connection with no open + * result. If flushing the data triggers a constraint violation or any other error, then all data is invalidated, and + * this function returns DuckDBError. It is not possible to append more values. Call duckdb_appender_error_data to + * obtain the error data followed by duckdb_appender_destroy to destroy the invalidated appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender The appender to flush. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_flush(duckdb_appender appender); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Clears all buffered data from the appender without flushing it to the table. This discards any data that has been + * appended but not yet written. The appender can continue to be used after clearing. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param appender The appender to clear. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_clear(duckdb_appender appender); +#endif -Checks if the type of the internal result is StreamQueryResult. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Closes the appender by flushing all intermediate states and closing it for further appends. If flushing the data + * triggers a constraint violation or any other error, then all data is invalidated, and this function returns + * DuckDBError. Call duckdb_appender_error_data to obtain the error data followed by duckdb_appender_destroy to destroy + * the invalidated appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender The appender to flush and close. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_close(duckdb_appender appender); +#endif -* @param result The result object to check. -* @return Whether or not the result object is of the type StreamQueryResult -*/ -DUCKDB_C_API bool duckdb_result_is_streaming(duckdb_result result); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Closes the appender by flushing all intermediate states to the table and destroying it. By destroying it, this + * function de-allocates all memory associated with the appender. If flushing the data triggers a constraint violation, + * then all data is invalidated, and this function returns DuckDBError. Due to the destruction of the appender, it is no + * longer possible to obtain the specific error message with duckdb_appender_error. Therefore, call + * duckdb_appender_close before destroying the appender, if you need insights into the specific error. + * + * history: + * - stable: v0.2.5 + * + * @param appender The appender to flush, close and destroy. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_destroy(duckdb_appender *appender); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(1, 2, 0) +/*! + * Appends a column to the active column list of the appender. Immediately flushes all previous data. + * + * The active column list specifies all columns that are expected when flushing the data. Any non-active columns are + * filled with their default values, or NULL. + * + * history: + * - stable: v1.2.0 + * + * @param appender The appender to add the column to. + * @param name + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_add_column(duckdb_appender appender, const char *name); +#endif -Returns the number of data chunks present in the result. +#if DUCKDB_API_VERSION_AT_LEAST(1, 2, 0) +/*! + * Removes all columns from the active column list of the appender, resetting the appender to treat all columns as + * active. Immediately flushes all previous data. + * + * history: + * - stable: v1.2.0 + * + * @param appender The appender to clear the columns from. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_clear_columns(duckdb_appender appender); +#endif -* @param result The result object -* @return Number of data chunks present in the result. -*/ -DUCKDB_C_API idx_t duckdb_result_chunk_count(duckdb_result result); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * A nop function, provided for backwards compatibility reasons. Does nothing. Only `duckdb_appender_end_row` is + * required. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_begin_row(duckdb_appender appender); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Finish the current row of appends. After end_row is called, the next row can be appended. + * + * history: + * - stable: v0.2.5 + * + * @param appender The appender. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_appender_end_row(duckdb_appender appender); #endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Returns the return_type of the given result, or DUCKDB_RETURN_TYPE_INVALID on error + * Append a DEFAULT value (NULL if DEFAULT not available for column) to the appender. + * + * history: + * - stable: v1.1.0 + * + * @param appender + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_default(duckdb_appender appender); +#endif -* @param result The result object -* @return The return_type -*/ -DUCKDB_C_API duckdb_result_type duckdb_result_return_type(duckdb_result result); - -//---------------------------------------------------------------------------------------------------------------------- -// Safe Fetch Functions -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Deprecated functions to interact with a `duckdb_result`. -// -// DEPRECATION NOTICE: -// This function group is deprecated and scheduled for removal. -// -// USE INSTEAD: -// To access the values in a result, use `duckdb_fetch_chunk` repeatedly. For each chunk, use the `duckdb_data_chunk` -// interface to access any columns and their values. -//---------------------------------------------------------------------------------------------------------------------- +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Append a DEFAULT value, at the specified row and column, (NULL if DEFAULT not available for column) to the chunk + * created from the specified appender. The default value of the column must be a constant value. Non-deterministic + * expressions like nextval('seq') or random() are not supported. + * + * history: + * - unstable: v1.2.0 + * - stable: v1.5.6 + * + * @param appender The appender to get the default value from. + * @param chunk The data chunk to append the default value to. + * @param col The chunk column index to append the default value to. + * @param row The chunk row index to append the default value to. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_default_to_chunk(duckdb_appender appender, duckdb_data_chunk chunk, idx_t col, + idx_t row); +#endif -#ifndef DUCKDB_API_NO_DEPRECATED -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a bool value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_bool(duckdb_appender appender, bool value); +#endif -* @return The boolean value at the specified location, or false if the value cannot be converted. -*/ -DUCKDB_C_API bool duckdb_value_boolean(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append an int8_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_int8(duckdb_appender appender, int8_t value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append an int16_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_int16(duckdb_appender appender, int16_t value); +#endif -* @return The int8_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API int8_t duckdb_value_int8(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append an int32_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_int32(duckdb_appender appender, int32_t value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append an int64_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_int64(duckdb_appender appender, int64_t value); +#endif -* @return The int16_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API int16_t duckdb_value_int16(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) +/*! + * Append a duckdb_hugeint value to the appender. + * + * history: + * - stable: v0.2.9 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_hugeint(duckdb_appender appender, duckdb_hugeint value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a uint8_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_uint8(duckdb_appender appender, uint8_t value); +#endif -* @return The int32_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API int32_t duckdb_value_int32(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a uint16_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_uint16(duckdb_appender appender, uint16_t value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a uint32_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_uint32(duckdb_appender appender, uint32_t value); +#endif -* @return The int64_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API int64_t duckdb_value_int64(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a uint64_t value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_uint64(duckdb_appender appender, uint64_t value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * Append a duckdb_uhugeint value to the appender. + * + * history: + * - stable: v0.10.0 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_uhugeint(duckdb_appender appender, duckdb_uhugeint value); +#endif -* @return The duckdb_hugeint value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API duckdb_hugeint duckdb_value_hugeint(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a float value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_float(duckdb_appender appender, float value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a double value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_double(duckdb_appender appender, double value); +#endif -* @return The duckdb_uhugeint value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API duckdb_uhugeint duckdb_value_uhugeint(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) +/*! + * Append a duckdb_date value to the appender. + * + * history: + * - stable: v0.2.9 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_date(duckdb_appender appender, duckdb_date value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) +/*! + * Append a duckdb_time value to the appender. + * + * history: + * - stable: v0.2.9 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_time(duckdb_appender appender, duckdb_time value); +#endif -* @return The duckdb_decimal value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API duckdb_decimal duckdb_value_decimal(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) +/*! + * Append a duckdb_timestamp value to the appender. + * + * history: + * - stable: v0.2.9 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_timestamp(duckdb_appender appender, duckdb_timestamp value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) +/*! + * Append a duckdb_interval value to the appender. + * + * history: + * - stable: v0.2.9 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_interval(duckdb_appender appender, duckdb_interval value); +#endif -* @return The uint8_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API uint8_t duckdb_value_uint8(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a varchar value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param val + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_varchar(duckdb_appender appender, const char *val); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a varchar value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param val + * @param length + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_varchar_length(duckdb_appender appender, const char *val, idx_t length); +#endif -* @return The uint16_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API uint16_t duckdb_value_uint16(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) +/*! + * Append a blob value to the appender. + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @param data + * @param length + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_blob(duckdb_appender appender, const void *data, idx_t length); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 5) /*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * Append a NULL value to the appender (of any type). + * + * history: + * - stable: v0.2.5 + * + * @param appender + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_null(duckdb_appender appender); +#endif -* @return The uint32_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API uint32_t duckdb_value_uint32(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(1, 2, 0) +/*! + * Append a duckdb_value to the appender. + * + * history: + * - stable: v1.2.0 + * + * @param appender + * @param value + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_value(duckdb_appender appender, duckdb_value value); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Appends a pre-filled data chunk to the specified appender. Attempts casting, if the data chunk types do not match the + * active appender types. + * + * history: + * - stable: v0.3.3 + * + * @param appender The appender to append to. + * @param chunk The data chunk to append. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_append_data_chunk(duckdb_appender appender, duckdb_data_chunk chunk); +#endif -* @return The uint64_t value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API uint64_t duckdb_value_uint64(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 9) && (DUCKDB_API_VERSION_BELOW(1, 4, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. Use duckdb_appender_error_data + * instead. + * + * Returns the error message associated with the 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. + * + * history: + * - stable: v0.2.9 + * - deprecated: v1.4.0 + * + * @param appender The appender to get the error from. + * @return const char* + */ +DUCKDB_C_API const char *duckdb_appender_error(duckdb_appender appender); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +/* --- Struct definitions for appender --- */ -* @return The float value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API float duckdb_value_float(duckdb_result *result, idx_t col, idx_t row); +/* ============================================================================ + * MODULE: arrow + * ============================================================================ */ -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +/* --- Enums for arrow --- */ -* @return The double value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API double duckdb_value_double(duckdb_result *result, idx_t col, idx_t row); +/* --- Struct forward declarations for arrow --- */ -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +/* --- Types for arrow --- */ -* @return The duckdb_date value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API duckdb_date duckdb_value_date(duckdb_result *result, idx_t col, idx_t row); +/* --- Constants for arrow --- */ -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +/* --- Function pointer typedefs for arrow --- */ -* @return The duckdb_time value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API duckdb_time duckdb_value_time(duckdb_result *result, idx_t col, idx_t row); +/* --- Functions for arrow --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. - -* @return The duckdb_timestamp value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API duckdb_timestamp duckdb_value_timestamp(duckdb_result *result, idx_t col, idx_t row); + * Transforms a DuckDB Schema into an Arrow Schema + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param arrow_options The Arrow settings used to produce arrow. + * @param types The DuckDB logical types for each column in the schema. + * @param names The names for each column in the schema. + * @param column_count The number of columns that exist in the schema. + * @param out_schema The resulting arrow schema. Must be destroyed with `out_schema->release(out_schema)`. + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_to_arrow_schema(duckdb_arrow_options arrow_options, duckdb_logical_type *types, + const char **names, idx_t column_count, + struct ArrowSchema *out_schema); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Transforms a DuckDB data chunk into an Arrow array. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param arrow_options The Arrow settings used to produce arrow. + * @param chunk The DuckDB data chunk to convert. + * @param out_arrow_array The output Arrow structure that will hold the converted data. Must be released with + * `out_arrow_array->release(out_arrow_array)` + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_data_chunk_to_arrow(duckdb_arrow_options arrow_options, duckdb_data_chunk chunk, + struct ArrowArray *out_arrow_array); +#endif -* @return The duckdb_interval value at the specified location, or 0 if the value cannot be converted. -*/ -DUCKDB_C_API duckdb_interval duckdb_value_interval(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Transforms an Arrow Schema into a DuckDB Schema. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param connection The connection to get the transformation settings from. + * @param schema The input Arrow schema. Must be released with `schema->release(schema)`. + * @param out_types The Arrow converted schema with extra information about the arrow types. Must be destroyed with + * `duckdb_destroy_arrow_converted_schema`. + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_schema_from_arrow(duckdb_connection connection, struct ArrowSchema *schema, + duckdb_arrow_converted_schema *out_types); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Transforms an Arrow array into a DuckDB data chunk. The data chunk will retain ownership of the underlying Arrow + * data. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param connection The connection to get the transformation settings from. + * @param arrow_array The input Arrow array. Data ownership is passed on to DuckDB's DataChunk, the underlying object + * does not need to be released and won't have ownership of the data. + * @param converted_schema The Arrow converted schema with extra information about the arrow types. + * @param out_chunk The resulting DuckDB data chunk. Must be destroyed by duckdb_destroy_data_chunk. + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_data_chunk_from_arrow(duckdb_connection connection, + struct ArrowArray *arrow_array, + duckdb_arrow_converted_schema converted_schema, + duckdb_data_chunk *out_chunk); +#endif -* @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_C_API char *duckdb_value_varchar(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the arrow converted schema and de-allocates all memory allocated for that arrow converted schema. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param arrow_converted_schema The arrow converted schema to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_arrow_converted_schema(duckdb_arrow_converted_schema *arrow_converted_schema); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Executes a SQL query within a connection and stores the full (materialized) result in an arrow structure. If the + * query fails to execute, DuckDBError is returned and the error message can be retrieved by calling + * `duckdb_query_arrow_error`. + * + * Note that after running `duckdb_query_arrow`, `duckdb_destroy_arrow` must be called on the result object even if the + * query fails, otherwise the error stored within the result will not be freed correctly. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param connection The connection to perform the query in. + * @param query The SQL query to run. + * @param out_result The query result. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_query_arrow(duckdb_connection connection, const char *query, duckdb_arrow *out_result); +#endif -* @return The string value at the specified location. Attempts to cast the result value to string. -*/ -DUCKDB_C_API duckdb_string duckdb_value_string(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Fetch the internal arrow schema from the arrow result. Remember to call release on the respective ArrowSchema object. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param result The result to fetch the schema from. + * @param out_schema The output schema. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_query_arrow_schema(duckdb_arrow result, duckdb_arrow_schema *out_schema); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 9, 0) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Fetch the internal arrow schema from the prepared statement. Remember to call release on the respective ArrowSchema + * object. + * + * history: + * - stable: v0.9.0 + * - deprecated: v1.0.0 + * + * @param prepared The prepared statement to fetch the schema from. + * @param out_schema The output schema. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_prepared_arrow_schema(duckdb_prepared_statement prepared, + duckdb_arrow_schema *out_schema); +#endif -* @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. +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Convert a data chunk into an arrow struct array. Remember to call release on the respective ArrowArray object. + * + * history: + * - stable: v0.10.0 + * - deprecated: v1.0.0 + * + * @param result The result object the data chunk have been fetched from. + * @param chunk The data chunk to convert. + * @param out_array The output array. + * @return void + */ +DUCKDB_C_API void duckdb_result_arrow_array(duckdb_result result, duckdb_data_chunk chunk, + duckdb_arrow_array *out_array); +#endif -The result must NOT be freed. -*/ -DUCKDB_C_API char *duckdb_value_varchar_internal(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Fetch an internal arrow struct array from the arrow result. Remember to call release on the respective ArrowArray + * object. + * + * This function can be called multiple time to get next chunks, which will free the previous out_array. So consume the + * out_array before calling this function again. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param result The result to fetch the array from. + * @param out_array The output array. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_query_arrow_array(duckdb_arrow result, duckdb_arrow_array *out_array); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Returns the number of columns present in the arrow result object. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param result The result object. + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_arrow_column_count(duckdb_arrow result); +#endif -* @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. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Returns the number of rows present in the arrow result object. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param result The result object. + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_arrow_row_count(duckdb_arrow result); +#endif -The result must NOT be freed. -*/ -DUCKDB_C_API duckdb_string duckdb_value_string_internal(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Returns the number of rows changed by the query stored in the arrow result. This is relevant only for + * INSERT/UPDATE/DELETE queries. For other queries the rows_changed will be 0. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param result The result object. + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_arrow_rows_changed(duckdb_arrow result); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Returns the error message contained within the result. The error is only set if `duckdb_query_arrow` returns + * `DuckDBError`. + * + * The error message should not be freed. It will be de-allocated when `duckdb_destroy_arrow` is called. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param result The result object to fetch the error from. + * @return const char* + */ +DUCKDB_C_API const char *duckdb_query_arrow_error(duckdb_arrow result); +#endif -* @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_C_API duckdb_blob duckdb_value_blob(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Closes the result and de-allocates all memory allocated for the arrow result. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param result The result to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_arrow(duckdb_arrow *result); +#endif -/*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Releases the arrow array stream and de-allocates its memory. + * + * history: + * - stable: v0.10.0 + * - deprecated: v1.0.0 + * + * @param stream_p The arrow array stream to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_arrow_stream(duckdb_arrow_stream *stream_p); +#endif -* @return Returns true if the value at the specified index is NULL, and false otherwise. -*/ -DUCKDB_C_API bool duckdb_value_is_null(duckdb_result *result, idx_t col, idx_t row); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Executes the prepared statement with the given bound parameters, and returns an arrow query result. Note that after + * running `duckdb_execute_prepared_arrow`, `duckdb_destroy_arrow` must be called on the result object. + * + * history: + * - stable: v0.2.8 + * - deprecated: v1.0.0 + * + * @param prepared_statement The prepared statement to execute. + * @param out_result The query result. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_execute_prepared_arrow(duckdb_prepared_statement prepared_statement, + duckdb_arrow *out_result); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 9, 0) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Scans the Arrow stream and creates a view with the given name. + * + * history: + * - stable: v0.9.0 + * - deprecated: v1.0.0 + * + * @param connection The connection on which to execute the scan. + * @param table_name Name of the temporary view to create. + * @param arrow Arrow stream wrapper. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_arrow_scan(duckdb_connection connection, const char *table_name, + duckdb_arrow_stream arrow); #endif -//---------------------------------------------------------------------------------------------------------------------- -// Helpers -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Generic and `duckdb_string_t` helper functions. -//---------------------------------------------------------------------------------------------------------------------- +#if DUCKDB_API_VERSION_AT_LEAST(0, 9, 0) && (DUCKDB_API_VERSION_BELOW(1, 0, 0) || DUCKDB_API_ALLOW_DEPRECATED) +/*! + * **DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * + * Scans the Arrow array and creates a view with the given name. Note that after running `duckdb_arrow_array_scan`, + * `duckdb_destroy_arrow_stream` must be called on the out stream. + * + * history: + * - stable: v0.9.0 + * - deprecated: v1.0.0 + * + * @param connection The connection on which to execute the scan. + * @param table_name Name of the temporary view to create. + * @param arrow_schema Arrow schema wrapper. + * @param arrow_array Arrow array wrapper. + * @param out_stream Output array stream that wraps around the passed schema, for releasing/deleting once done. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_arrow_array_scan(duckdb_connection connection, const char *table_name, + duckdb_arrow_schema arrow_schema, duckdb_arrow_array arrow_array, + duckdb_arrow_stream *out_stream); +#endif -/*! -Allocate `size` bytes of memory using the duckdb internal malloc function. Any memory allocated in this manner -should be freed using `duckdb_free`. +/* --- Struct definitions for arrow --- */ -* @param size The number of bytes to allocate. -* @return A pointer to the allocated memory region. -*/ -DUCKDB_C_API void *duckdb_malloc(size_t size); +/* ============================================================================ + * MODULE: cast_function + * ============================================================================ */ -/*! -Free a value returned from `duckdb_malloc`, `duckdb_value_varchar`, `duckdb_value_blob`, or -`duckdb_value_string`. +/* --- Enums for cast_function --- */ -* @param ptr The memory region to de-allocate. -*/ -DUCKDB_C_API void duckdb_free(void *ptr); +/* --- Struct forward declarations for cast_function --- */ -/*! -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`. +/* --- Types for cast_function --- */ -* @return The vector size. -*/ -DUCKDB_C_API idx_t duckdb_vector_size(); +/* --- Constants for cast_function --- */ -/*! -Whether or not the duckdb_string_t value is inlined. -This means that the data of the string does not have a separate allocation. +/* --- Function pointer typedefs for cast_function --- */ -*/ -DUCKDB_C_API bool duckdb_string_is_inlined(duckdb_string_t string); +/* --- Functions for cast_function --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Get the string length of a string_t - -* @param string The string to get the length of. -* @return The length. -*/ -DUCKDB_C_API uint32_t duckdb_string_t_length(duckdb_string_t string); + * Creates a new cast function object. + * + * history: + * - stable: v1.1.0 + * + * @return duckdb_cast_function + */ +DUCKDB_C_API duckdb_cast_function duckdb_create_cast_function(void); +#endif -/*! -Get a pointer to the string data of a string_t +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the source type of the cast function. + * + * history: + * - stable: v1.1.0 + * + * @param cast_function The cast function object. + * @param source_type The source type to set. + * @return void + */ +DUCKDB_C_API void duckdb_cast_function_set_source_type(duckdb_cast_function cast_function, + duckdb_logical_type source_type); +#endif -* @param string The string to get the pointer to. -* @return The pointer. -*/ -DUCKDB_C_API const char *duckdb_string_t_data(duckdb_string_t *string); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the target type of the cast function. + * + * history: + * - stable: v1.1.0 + * + * @param cast_function The cast function object. + * @param target_type The target type to set. + * @return void + */ +DUCKDB_C_API void duckdb_cast_function_set_target_type(duckdb_cast_function cast_function, + duckdb_logical_type target_type); +#endif -/*! -Checks if a string is valid UTF-8. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the "cost" of implicitly casting the source type to the target type using this function. + * + * history: + * - stable: v1.1.0 + * + * @param cast_function The cast function object. + * @param cost The cost to set. + * @return void + */ +DUCKDB_C_API void duckdb_cast_function_set_implicit_cast_cost(duckdb_cast_function cast_function, int64_t cost); +#endif -* @param str The string to check -* @param len The length of the string (in bytes) -* @return nullptr if the string is valid UTF-8. Otherwise, a duckdb_error_data containing error information. Must be -destroyed with `duckdb_destroy_error_data`. -*/ -DUCKDB_C_API duckdb_error_data duckdb_valid_utf8_check(const char *str, idx_t len); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the actual cast function to use. + * + * history: + * - stable: v1.1.0 + * + * @param cast_function The cast function object. + * @param function The function to set. + * @return void + */ +DUCKDB_C_API void duckdb_cast_function_set_function(duckdb_cast_function cast_function, + duckdb_cast_function_t function); +#endif -//---------------------------------------------------------------------------------------------------------------------- -// Date Time Timestamp Helpers -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to convert from and to `duckdb_[date, time, time_tz, timestamp]`. -// `duckdb_is_finite_timestamp[_s, _ms, _ns]` helper functions. -//---------------------------------------------------------------------------------------------------------------------- +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Assigns extra information to the cast function that can be fetched during execution, etc. + * + * history: + * - stable: v1.1.0 + * + * @param cast_function + * @param extra_info The extra information + * @param destroy The callback that will be called to destroy the extra information (if any) + * @return void + */ +DUCKDB_C_API void duckdb_cast_function_set_extra_info(duckdb_cast_function cast_function, void *extra_info, + duckdb_delete_callback_t destroy); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Decompose a `duckdb_date` object into year, month and date (stored as `duckdb_date_struct`). - -* @param date The date object, as obtained from a `DUCKDB_TYPE_DATE` column. -* @return The `duckdb_date_struct` with the decomposed elements. -*/ -DUCKDB_C_API duckdb_date_struct duckdb_from_date(duckdb_date date); + * Retrieves the extra info of the function as set in `duckdb_cast_function_set_extra_info`. + * + * history: + * - stable: v1.1.0 + * + * @param info The info object. + * @return void* + */ +DUCKDB_C_API void *duckdb_cast_function_get_extra_info(duckdb_function_info info); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Re-compose a `duckdb_date` from year, month and date (`duckdb_date_struct`). + * Get the cast execution mode from the given function info. + * + * history: + * - stable: v1.1.0 + * + * @param info The info object. + * @return duckdb_cast_mode + */ +DUCKDB_C_API duckdb_cast_mode duckdb_cast_function_get_cast_mode(duckdb_function_info info); +#endif -* @param date The year, month and date stored in a `duckdb_date_struct`. -* @return The `duckdb_date` element. -*/ -DUCKDB_C_API duckdb_date duckdb_to_date(duckdb_date_struct date); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Report that an error has occurred while executing the cast function. + * + * history: + * - stable: v1.1.0 + * + * @param info The info object. + * @param error The error message. + * @return void + */ +DUCKDB_C_API void duckdb_cast_function_set_error(duckdb_function_info info, const char *error); +#endif -/*! -Test a `duckdb_date` to see if it is a finite value. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Report that an error has occurred while executing the cast function, setting the corresponding output row to NULL. + * + * history: + * - stable: v1.1.0 + * + * @param info The info object. + * @param error The error message. + * @param row The index of the row within the output vector to set to NULL. + * @param output The output vector. + * @return void + */ +DUCKDB_C_API void duckdb_cast_function_set_row_error(duckdb_function_info info, const char *error, idx_t row, + duckdb_vector output); +#endif -* @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_C_API bool duckdb_is_finite_date(duckdb_date date); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Registers a cast function within the given connection. + * + * history: + * - stable: v1.1.0 + * + * @param con The connection to use. + * @param cast_function The cast function to register. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_register_cast_function(duckdb_connection con, duckdb_cast_function cast_function); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Decompose a `duckdb_time` object into hour, minute, second and microsecond (stored as `duckdb_time_struct`). + * Destroys the cast function object. + * + * history: + * - stable: v1.1.0 + * + * @param cast_function The cast function object. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_cast_function(duckdb_cast_function *cast_function); +#endif -* @param time The time object, as obtained from a `DUCKDB_TYPE_TIME` column. -* @return The `duckdb_time_struct` with the decomposed elements. -*/ -DUCKDB_C_API duckdb_time_struct duckdb_from_time(duckdb_time time); +/* --- Struct definitions for cast_function --- */ -/*! -Create a `duckdb_time_tz` object from micros and a timezone offset. +/* ============================================================================ + * MODULE: catalog + * ============================================================================ */ -* @param micros The microsecond component of the time. -* @param offset The timezone offset component of the time. -* @return The `duckdb_time_tz` element. -*/ -DUCKDB_C_API duckdb_time_tz duckdb_create_time_tz(int64_t micros, int32_t offset); +/* --- Enums for catalog --- */ -/*! -Decompose a TIME_TZ objects into micros and a timezone offset. +/* --- Struct forward declarations for catalog --- */ -Use `duckdb_from_time` to further decompose the micros into hour, minute, second and microsecond. +/* --- Types for catalog --- */ -* @param micros The time object, as obtained from a `DUCKDB_TYPE_TIME_TZ` column. -*/ -DUCKDB_C_API duckdb_time_tz_struct duckdb_from_time_tz(duckdb_time_tz micros); +/* --- Constants for catalog --- */ -/*! -Re-compose a `duckdb_time` from hour, minute, second and microsecond (`duckdb_time_struct`). +/* --- Function pointer typedefs for catalog --- */ -* @param time The hour, minute, second and microsecond in a `duckdb_time_struct`. -* @return The `duckdb_time` element. -*/ -DUCKDB_C_API duckdb_time duckdb_to_time(duckdb_time_struct time); +/* --- Functions for catalog --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -Decompose a `duckdb_timestamp` object into a `duckdb_timestamp_struct`. + * Retrieve a database catalog instance by name. This function can only be called from within the context of an active + * transaction, e.g. during execution of a registered function callback. Otherwise returns `nullptr`. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param context The client context. + * @param catalog_name The name of the catalog. + * @return duckdb_catalog + */ +DUCKDB_C_API duckdb_catalog duckdb_client_context_get_catalog(duckdb_client_context context, const char *catalog_name); +#endif -* @param ts The ts object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column. -* @return The `duckdb_timestamp_struct` with the decomposed elements. -*/ -DUCKDB_C_API duckdb_timestamp_struct duckdb_from_timestamp(duckdb_timestamp ts); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieve the "type name" of the given catalog. E.g. for a DuckDB database, this returns 'duckdb'. The returned string + * is owned by the catalog and remains valid until the catalog is destroyed. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param catalog The catalog. + * @return const char* + */ +DUCKDB_C_API const char *duckdb_catalog_get_type_name(duckdb_catalog catalog); +#endif -/*! -Re-compose a `duckdb_timestamp` from a duckdb_timestamp_struct. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieve a catalog entry from the given catalog by type, schema name and entry name. The returned catalog entry + * remains valid for the duration of the current transaction. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param catalog The catalog. + * @param context The client context. + * @param entry_type The type of the catalog entry to retrieve. + * @param schema_name The schema name of the catalog entry. + * @param entry_name The name of the catalog entry. + * @return duckdb_catalog_entry + */ +DUCKDB_C_API duckdb_catalog_entry duckdb_catalog_get_entry(duckdb_catalog catalog, duckdb_client_context context, + duckdb_catalog_entry_type entry_type, + const char *schema_name, const char *entry_name); +#endif -* @param ts The de-composed elements in a `duckdb_timestamp_struct`. -* @return The `duckdb_timestamp` element. -*/ -DUCKDB_C_API duckdb_timestamp duckdb_to_timestamp(duckdb_timestamp_struct ts); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the given catalog instance. + * + * Note that this does not actually "drop" the contents of the catalog; it merely frees the C API handle. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param catalog The catalog instance to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_catalog(duckdb_catalog *catalog); +#endif -/*! -Test a `duckdb_timestamp` to see if it is a finite value. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Get the type of the given catalog entry. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param entry The catalog entry. + * @return duckdb_catalog_entry_type + */ +DUCKDB_C_API duckdb_catalog_entry_type duckdb_catalog_entry_get_type(duckdb_catalog_entry entry); +#endif -* @param ts The duckdb_timestamp object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column. -* @return True if the timestamp is finite, false if it is ±infinity. -*/ -DUCKDB_C_API bool duckdb_is_finite_timestamp(duckdb_timestamp ts); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Get the name of the given catalog entry. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param entry The catalog entry. + * @return const char* + */ +DUCKDB_C_API const char *duckdb_catalog_entry_get_name(duckdb_catalog_entry entry); +#endif -/*! -Test a `duckdb_timestamp_s` to see if it is a finite value. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the given catalog entry instance. + * + * Note that this does not actually "drop" the catalog entry from the database catalog; it merely frees the C API + * handle. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param entry The catalog entry instance to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_catalog_entry(duckdb_catalog_entry *entry); +#endif -* @param ts The duckdb_timestamp_s object, as obtained from a `DUCKDB_TYPE_TIMESTAMP_S` column. -* @return True if the timestamp is finite, false if it is ±infinity. -*/ -DUCKDB_C_API bool duckdb_is_finite_timestamp_s(duckdb_timestamp_s ts); +/* --- Struct definitions for catalog --- */ -/*! -Test a `duckdb_timestamp_ms` to see if it is a finite value. +/* ============================================================================ + * MODULE: config_option + * ============================================================================ */ -* @param ts The duckdb_timestamp_ms object, as obtained from a `DUCKDB_TYPE_TIMESTAMP_MS` column. -* @return True if the timestamp is finite, false if it is ±infinity. -*/ -DUCKDB_C_API bool duckdb_is_finite_timestamp_ms(duckdb_timestamp_ms ts); +/* --- Enums for config_option --- */ -/*! -Test a `duckdb_timestamp_ns` to see if it is a finite value. +/* --- Struct forward declarations for config_option --- */ -* @param ts The duckdb_timestamp_ns object, as obtained from a `DUCKDB_TYPE_TIMESTAMP_NS` column. -* @return True if the timestamp is finite, false if it is ±infinity. -*/ -DUCKDB_C_API bool duckdb_is_finite_timestamp_ns(duckdb_timestamp_ns ts); +/* --- Types for config_option --- */ -//---------------------------------------------------------------------------------------------------------------------- -// Hugeint and Uhugeint Helpers -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to convert from and to `duckdb_[hugeint, uhugeint]`. -//---------------------------------------------------------------------------------------------------------------------- +/* --- Constants for config_option --- */ -/*! -Converts a duckdb_hugeint object (as obtained from a `DUCKDB_TYPE_HUGEINT` column) into a double. +/* --- Function pointer typedefs for config_option --- */ -* @param val The hugeint value. -* @return The converted `double` element. -*/ -DUCKDB_C_API double duckdb_hugeint_to_double(duckdb_hugeint val); +/* --- Functions for config_option --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -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. + * Creates a configuration option instance. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @return duckdb_config_option + */ +DUCKDB_C_API duckdb_config_option duckdb_create_config_option(void); +#endif -* @param val The double value. -* @return The converted `duckdb_hugeint` element. -*/ -DUCKDB_C_API duckdb_hugeint duckdb_double_to_hugeint(double val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the given configuration option instance. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param option The configuration option instance to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_config_option(duckdb_config_option *option); +#endif -/*! -Converts a duckdb_uhugeint object (as obtained from a `DUCKDB_TYPE_UHUGEINT` column) into a double. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the name of the configuration option. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param option The configuration option instance. + * @param name The name to set. + * @return void + */ +DUCKDB_C_API void duckdb_config_option_set_name(duckdb_config_option option, const char *name); +#endif -* @param val The uhugeint value. -* @return The converted `double` element. -*/ -DUCKDB_C_API double duckdb_uhugeint_to_double(duckdb_uhugeint val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the type of the configuration option. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param option The configuration option instance. + * @param type The type to set. + * @return void + */ +DUCKDB_C_API void duckdb_config_option_set_type(duckdb_config_option option, duckdb_logical_type type); +#endif -/*! -Converts a double value to a duckdb_uhugeint object. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the default value of the configuration option. If the type of this option has already been set with + * `duckdb_config_option_set_type`, the value is cast to the type. Otherwise, the type is inferred from the value. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param option The configuration option instance. + * @param default_value The default value to set. + * @return void + */ +DUCKDB_C_API void duckdb_config_option_set_default_value(duckdb_config_option option, duckdb_value default_value); +#endif -If the conversion fails because the double value is too big the result will be 0. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the default scope of the configuration option. If not set, this defaults to + * `DUCKDB_CONFIG_OPTION_SCOPE_SESSION`. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param option The configuration option instance. + * @param default_scope The default scope to set. + * @return void + */ +DUCKDB_C_API void duckdb_config_option_set_default_scope(duckdb_config_option option, + duckdb_config_option_scope default_scope); +#endif -* @param val The double value. -* @return The converted `duckdb_uhugeint` element. -*/ -DUCKDB_C_API duckdb_uhugeint duckdb_double_to_uhugeint(double val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the description of the configuration option. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param option The configuration option instance. + * @param description The description to set. + * @return void + */ +DUCKDB_C_API void duckdb_config_option_set_description(duckdb_config_option option, const char *description); +#endif -//---------------------------------------------------------------------------------------------------------------------- -// Decimal Helpers -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to convert from and to `duckdb_decimal`. -//---------------------------------------------------------------------------------------------------------------------- +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Registers the given configuration option on the specified connection. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param connection The connection to register the option on. + * @param option The configuration option instance to register. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_register_config_option(duckdb_connection connection, duckdb_config_option option); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the value of a configuration option by name from the given client context. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param context The client context. + * @param name The name of the configuration option to retrieve. + * @param out_scope Output parameter to optionally store the scope that the configuration option was retrieved from. If + * this is `nullptr`, the scope is not returned. If the requested option does not exist the scope is set to + * `DUCKDB_CONFIG_OPTION_SCOPE_INVALID`. + * @return duckdb_value + */ +DUCKDB_C_API duckdb_value duckdb_client_context_get_config_option(duckdb_client_context context, const char *name, + duckdb_config_option_scope *out_scope); +#endif + +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Converts a double value to a duckdb_decimal object. + * Returns the root node of the profiling information. Returns nullptr, if profiling is not enabled. + * + * history: + * - stable: v1.1.0 + * + * @param connection A connection object. + * @return duckdb_profiling_info + */ +DUCKDB_C_API duckdb_profiling_info duckdb_get_profiling_info(duckdb_connection connection); +#endif -If the conversion fails because the double value is too big, or the width/scale are invalid the result will be 0. +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Returns the value of the metric of the current profiling info node. Returns nullptr, if the metric does not exist or + * is not enabled. Currently, the value holds a string, and you can retrieve the string by calling the corresponding + * function: char *duckdb_get_varchar(duckdb_value value). + * + * history: + * - stable: v1.1.0 + * + * @param info A profiling information object. + * @param key The name of the requested metric. + * @return duckdb_value + */ +DUCKDB_C_API duckdb_value duckdb_profiling_info_get_value(duckdb_profiling_info info, const char *key); +#endif -* @param val The double value. -* @return The converted `duckdb_decimal` element. -*/ -DUCKDB_C_API duckdb_decimal duckdb_double_to_decimal(double val, uint8_t width, uint8_t scale); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Returns the key-value metric map of this profiling node as a MAP duckdb_value. The individual elements are accessible + * via the duckdb_value MAP functions. + * + * history: + * - stable: v1.1.0 + * + * @param info A profiling information object. + * @return duckdb_value + */ +DUCKDB_C_API duckdb_value duckdb_profiling_info_get_metrics(duckdb_profiling_info info); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) /*! -Converts a duckdb_decimal object (as obtained from a `DUCKDB_TYPE_DECIMAL` column) into a double. + * Returns the number of children in the current profiling info node. + * + * history: + * - stable: v1.1.0 + * + * @param info A profiling information object. + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_profiling_info_get_child_count(duckdb_profiling_info info); +#endif -* @param val The decimal value. -* @return The converted `double` element. -*/ -DUCKDB_C_API double duckdb_decimal_to_double(duckdb_decimal val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Returns the child node at the specified index. + * + * history: + * - stable: v1.1.0 + * + * @param info A profiling information object. + * @param index The index of the child node. + * @return duckdb_profiling_info + */ +DUCKDB_C_API duckdb_profiling_info duckdb_profiling_info_get_child(duckdb_profiling_info info, idx_t index); +#endif -//---------------------------------------------------------------------------------------------------------------------- -// Prepared Statements -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// A prepared statement is a parameterized query, and you can bind parameters to it. Prepared statements are commonly -// used to easily supply parameters to functions and avoid SQL injection attacks. They also speed up queries that are -// executed repeatedly with different parameters. That is because the query is only parsed, bound, optimized and planned -// once during the prepare stage, rather than once per execution, if it is possible to resolve all parameter types. -// -// For example: -// SELECT * FROM tbl WHERE id = ? -// Or a query with multiple parameters: -// SELECT * FROM tbl WHERE id = $1 OR name = $2 -//---------------------------------------------------------------------------------------------------------------------- +/* --- Struct definitions for config_option --- */ -/*! -Create a prepared statement object from a query. +/* ============================================================================ + * MODULE: connection + * ============================================================================ */ -Note that after calling `duckdb_prepare`, the prepared statement should always be destroyed using -`duckdb_destroy_prepare`, even if the prepare fails. +/* --- Enums for connection --- */ -If the prepare fails, `duckdb_prepare_error` can be called to obtain the reason why the prepare failed. +/* --- Struct forward declarations for connection --- */ -* @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_C_API duckdb_state duckdb_prepare(duckdb_connection connection, const char *query, - duckdb_prepared_statement *out_prepared_statement); +/* --- Types for connection --- */ -/*! -Closes the prepared statement and de-allocates all memory allocated for the statement. +/* --- Constants for connection --- */ -* @param prepared_statement The prepared statement to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement); +/* --- Function pointer typedefs for connection --- */ + +/* --- Functions for connection --- */ /*! -Returns the error message associated with the given prepared statement. -If the prepared statement has no error message, this returns `nullptr` instead. + * Opens a connection to a database. Connections are required to query the database, and store transactional state + * associated with the connection. The instantiated connection should be closed using 'duckdb_disconnect'. + * + * history: + * - stable: v0.1.0 + * + * @param database The database file to connect to. + * @param out_connection The result connection object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection); -The error message should not be freed. It will be de-allocated when `duckdb_destroy_prepare` is called. +#if DUCKDB_API_VERSION_AT_LEAST(0, 9, 0) +/*! + * Interrupt running query + * + * history: + * - stable: v0.9.0 + * + * @param connection The connection to interrupt + * @return void + */ +DUCKDB_C_API void duckdb_interrupt(duckdb_connection connection); +#endif -* @param prepared_statement The prepared statement to obtain the error from. -* @return The error message, or `nullptr` if there is none. -*/ -DUCKDB_C_API const char *duckdb_prepare_error(duckdb_prepared_statement prepared_statement); +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * Get the progress of the running query. + * + * history: + * - stable: v0.10.0 + * + * @param connection The connection running the query. + * @return duckdb_query_progress_type + */ +DUCKDB_C_API duckdb_query_progress_type duckdb_query_progress(duckdb_connection connection); +#endif /*! -Returns the number of parameters that can be provided to the given prepared statement. + * Closes the specified connection and de-allocates all memory allocated for that connection. + * + * history: + * - stable: v0.1.0 + * + * @param connection The connection to close. + * @return void + */ +DUCKDB_C_API void duckdb_disconnect(duckdb_connection *connection); -Returns 0 if the query was not successfully prepared. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the client context of the connection. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + * + * @param connection The connection. + * @param out_context The client context of the connection. Must be destroyed with `duckdb_destroy_client_context`. + * @return void + */ +DUCKDB_C_API void duckdb_connection_get_client_context(duckdb_connection connection, + duckdb_client_context *out_context); +#endif -* @param prepared_statement The prepared statement to obtain the number of parameters for. -*/ -DUCKDB_C_API idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the arrow options of the connection. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param connection The connection. + * @param out_arrow_options + * @return void + */ +DUCKDB_C_API void duckdb_connection_get_arrow_options(duckdb_connection connection, + duckdb_arrow_options *out_arrow_options); +#endif -/*! -Returns the name used to identify the parameter -The returned string should be freed using `duckdb_free`. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Returns the connection id of the client context. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + * + * @param context The client context. + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_client_context_get_connection_id(duckdb_client_context context); +#endif -Returns NULL if the index is out of range for the provided prepared statement. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the client context and deallocates its memory. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + * + * @param context The client context to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_client_context(duckdb_client_context *context); +#endif -* @param prepared_statement The prepared statement for which to get the parameter name from. -*/ -DUCKDB_C_API const char *duckdb_parameter_name(duckdb_prepared_statement prepared_statement, idx_t index); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the arrow options and deallocates its memory. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param arrow_options The arrow options to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_arrow_options(duckdb_arrow_options *arrow_options); +#endif -/*! -Returns the parameter type for the parameter at the given index. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Get the list of (fully qualified) table names of the query. + * + * history: + * - unstable: v1.3.0 + * - stable: v1.5.6 + * + * @param connection The connection for which to get the table names. + * @param query The query for which to get the table names. + * @param qualified Returns fully qualified table names (catalog.schema.table), if set to true, else only the (not + * escaped) table names. + * @return duckdb_value + */ +DUCKDB_C_API duckdb_value duckdb_get_table_names(duckdb_connection connection, const char *query, bool qualified); +#endif -Returns `DUCKDB_TYPE_INVALID` if the parameter index is out of range or the statement was not successfully prepared. +/* --- Struct definitions for connection --- */ -* @param prepared_statement The prepared statement. -* @param param_idx The parameter index. -* @return The parameter type -*/ -DUCKDB_C_API duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx); +/* ============================================================================ + * MODULE: copy_function + * ============================================================================ */ -/*! -Returns the logical type for the parameter at the given index. +/* --- Enums for copy_function --- */ -Returns `nullptr` if the parameter index is out of range or the statement was not successfully prepared. +/* --- Struct forward declarations for copy_function --- */ -The return type of this call should be destroyed with `duckdb_destroy_logical_type`. +/* --- Types for copy_function --- */ -* @param prepared_statement The prepared statement. -* @param param_idx The parameter index. -* @return The logical type of the parameter -*/ -DUCKDB_C_API duckdb_logical_type duckdb_param_logical_type(duckdb_prepared_statement prepared_statement, - idx_t param_idx); +/* --- Constants for copy_function --- */ -/*! -Clear the params bind to the prepared statement. -*/ -DUCKDB_C_API duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement); +/* --- Function pointer typedefs for copy_function --- */ +/* --- Functions for copy_function --- */ + +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -Returns the statement type of the statement to be executed + * Creates a new empty copy function. + * + * The return value must be destroyed with `duckdb_destroy_copy_function`. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @return duckdb_copy_function + */ +DUCKDB_C_API duckdb_copy_function duckdb_create_copy_function(void); +#endif -* @param statement The prepared statement. -* @return duckdb_statement_type value or DUCKDB_STATEMENT_TYPE_INVALID -*/ -DUCKDB_C_API duckdb_statement_type duckdb_prepared_statement_type(duckdb_prepared_statement statement); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the name of the copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function The copy function + * @param name The name to set + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_set_name(duckdb_copy_function copy_function, const char *name); +#endif -/*! -Returns the number of columns present in a the result of the prepared statement. If any of the column types are invalid, -the result will be 1. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the extra info pointer of the copy function, which can be used to store arbitrary data. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function The copy function + * @param extra_info The extra info pointer + * @param destructor A destructor function to call to destroy the extra info + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_set_extra_info(duckdb_copy_function copy_function, void *extra_info, + duckdb_delete_callback_t destructor); +#endif -* @param prepared_statement The prepared statement. -* @return The number of columns present in the result of the prepared statement. -*/ -DUCKDB_C_API idx_t duckdb_prepared_statement_column_count(duckdb_prepared_statement prepared_statement); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Registers the given copy function on the database connection under the specified name. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param connection The database connection + * @param copy_function The copy function to register + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_register_copy_function(duckdb_connection connection, + duckdb_copy_function copy_function); +#endif -/*! -Returns the name of the specified column of the result of the prepared_statement. -The returned string should be freed using `duckdb_free`. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the given copy function object. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function The copy function to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_copy_function(duckdb_copy_function *copy_function); +#endif -Returns `nullptr` if the column is out of range. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the bind function of the copy function, to use when binding `COPY ... TO`. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function + * @param bind The bind function + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_set_bind(duckdb_copy_function copy_function, duckdb_copy_function_bind_t bind); +#endif -* @param prepared_statement The prepared statement. -* @param col_idx The column index. -* @return The column name of the specified column. -*/ -DUCKDB_C_API const char *duckdb_prepared_statement_column_name(duckdb_prepared_statement prepared_statement, - idx_t col_idx); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Report that an error occurred during the binding-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The bind info provided to the bind function + * @param error The error message + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_bind_set_error(duckdb_copy_function_bind_info info, const char *error); +#endif -/*! -Returns the column type of the specified column of the result of the prepared_statement. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the extra info pointer of the copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The bind info provided to the bind function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_bind_get_extra_info(duckdb_copy_function_bind_info info); +#endif -Returns `DUCKDB_TYPE_INVALID` if the column is out of range. -The return type of this call should be destroyed with `duckdb_destroy_logical_type`. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the client context of the current connection binding the `COPY ... TO` function. + * + * Must be destroyed with `duckdb_destroy_client_context` + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The bind info provided to the bind function + * @return duckdb_client_context + */ +DUCKDB_C_API duckdb_client_context duckdb_copy_function_bind_get_client_context(duckdb_copy_function_bind_info info); +#endif -* @param prepared_statement The prepared statement to fetch the column type from. -* @param col_idx The column index. -* @return The logical type of the specified column. -*/ -DUCKDB_C_API duckdb_logical_type -duckdb_prepared_statement_column_logical_type(duckdb_prepared_statement prepared_statement, idx_t col_idx); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the number of columns that will be provided to the `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The bind info provided to the bind function + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_copy_function_bind_get_column_count(duckdb_copy_function_bind_info info); +#endif -/*! -Returns the column type of the specified column of the result of the prepared_statement. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the type of a column that will be provided to the `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The bind info provided to the bind function + * @param col_idx The index of the column to retrieve the type for + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_copy_function_bind_get_column_type(duckdb_copy_function_bind_info info, + idx_t col_idx); +#endif -Returns `DUCKDB_TYPE_INVALID` if the column is out of range. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves all values for the given options provided to the `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The bind info provided to the bind function + * @return duckdb_value + */ +DUCKDB_C_API duckdb_value duckdb_copy_function_bind_get_options(duckdb_copy_function_bind_info info); +#endif -* @param prepared_statement The prepared statement to fetch the column type from. -* @param col_idx The column index. -* @return The type of the specified column. -*/ -DUCKDB_C_API duckdb_type duckdb_prepared_statement_column_type(duckdb_prepared_statement prepared_statement, - idx_t col_idx); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the bind data of the copy function, to be provided to the init, sink and finalize functions. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The bind info provided to the bind function + * @param bind_data The bind data pointer + * @param destructor A destructor function to call to destroy the bind data + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_bind_set_bind_data(duckdb_copy_function_bind_info info, void *bind_data, + duckdb_delete_callback_t destructor); +#endif -//---------------------------------------------------------------------------------------------------------------------- -// Bind Values to Prepared Statements -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to bind values to prepared statements. Try to use `duckdb_bind_value` and the `duckdb_create_...` interface -// for all types. -//---------------------------------------------------------------------------------------------------------------------- +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the initialization function of the copy function, called right before executing `COPY ... TO`. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function + * @param init The init function + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_set_global_init(duckdb_copy_function copy_function, + duckdb_copy_function_global_init_t init); +#endif -/*! -Binds a value to the prepared statement at the specified index. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Report that an error occurred during the initialization-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The init info provided to the init function + * @param error The error message + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_global_init_set_error(duckdb_copy_function_global_init_info info, + const char *error); +#endif -Supersedes all type-specific bind functions (e.g., `duckdb_bind_varchar`, `duckdb_bind_int64`, etc.). -*/ -DUCKDB_C_API duckdb_state duckdb_bind_value(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the extra info pointer of the copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The init info provided to the init function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_global_init_get_extra_info(duckdb_copy_function_global_init_info info); +#endif -/*! -Retrieve the index of the parameter for the prepared statement, identified by name -*/ -DUCKDB_C_API duckdb_state duckdb_bind_parameter_index(duckdb_prepared_statement prepared_statement, - idx_t *param_idx_out, const char *name); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the client context of the current connection initializing the `COPY ... TO` function. + * + * Must be destroyed with `duckdb_destroy_client_context` + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The init info provided to the init function + * @return duckdb_client_context + */ +DUCKDB_C_API duckdb_client_context +duckdb_copy_function_global_init_get_client_context(duckdb_copy_function_global_init_info info); +#endif -/*! -Binds a bool value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the bind data provided during the binding-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The init info provided to the init function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_global_init_get_bind_data(duckdb_copy_function_global_init_info info); +#endif -/*! -Binds an int8_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the file path provided to the `COPY ... TO` function. + * + * Lives for the duration of the initialization callback, must not be destroyed. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The init info provided to the init function + * @return const char* + */ +DUCKDB_C_API const char *duckdb_copy_function_global_init_get_file_path(duckdb_copy_function_global_init_info info); +#endif -/*! -Binds an int16_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_int16(duckdb_prepared_statement prepared_statement, idx_t param_idx, int16_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the global state of the copy function, to be provided to all subsequent local init, sink and finalize functions. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The init info provided to the init function + * @param global_state The global state pointer + * @param destructor A destructor function to call to destroy the global state + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_global_init_set_global_state(duckdb_copy_function_global_init_info info, + void *global_state, + duckdb_delete_callback_t destructor); +#endif -/*! -Binds an int32_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_int32(duckdb_prepared_statement prepared_statement, idx_t param_idx, int32_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the sink function of the copy function, called during `COPY ... TO`. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function + * @param function The sink function + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_set_sink(duckdb_copy_function copy_function, + duckdb_copy_function_sink_t function); +#endif -/*! -Binds an int64_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_int64(duckdb_prepared_statement prepared_statement, idx_t param_idx, int64_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Report that an error occurred during the sink-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The sink info provided to the sink function + * @param error The error message + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_sink_set_error(duckdb_copy_function_sink_info info, const char *error); +#endif -/*! -Binds a duckdb_hugeint value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_hugeint(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_hugeint val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the extra info pointer of the copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The sink info provided to the sink function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_sink_get_extra_info(duckdb_copy_function_sink_info info); +#endif -/*! -Binds a duckdb_uhugeint value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_uhugeint(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_uhugeint val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the client context of the current connection during the sink-phase of the `COPY ... TO` function. + * + * Must be destroyed with `duckdb_destroy_client_context` + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The sink info provided to the sink function + * @return duckdb_client_context + */ +DUCKDB_C_API duckdb_client_context duckdb_copy_function_sink_get_client_context(duckdb_copy_function_sink_info info); +#endif -/*! -Binds a duckdb_decimal value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_decimal(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_decimal val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the bind data provided during the binding-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The sink info provided to the sink function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_sink_get_bind_data(duckdb_copy_function_sink_info info); +#endif -/*! -Binds a uint8_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_uint8(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint8_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the global state provided during the init-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The sink info provided to the sink function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_sink_get_global_state(duckdb_copy_function_sink_info info); +#endif -/*! -Binds a uint16_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_uint16(duckdb_prepared_statement prepared_statement, idx_t param_idx, - uint16_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the finalize function of the copy function, called at the end of `COPY ... TO`. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function + * @param finalize The finalize function + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_set_finalize(duckdb_copy_function copy_function, + duckdb_copy_function_finalize_t finalize); +#endif -/*! -Binds a uint32_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_uint32(duckdb_prepared_statement prepared_statement, idx_t param_idx, - uint32_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Report that an error occurred during the finalize-phase of a `COPY ... TO` function + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The finalize info provided to the finalize function + * @param error The error message + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_finalize_set_error(duckdb_copy_function_finalize_info info, const char *error); +#endif -/*! -Binds a uint64_t value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_uint64(duckdb_prepared_statement prepared_statement, idx_t param_idx, - uint64_t val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the extra info pointer of the copy function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The finalize info provided to the finalize function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_finalize_get_extra_info(duckdb_copy_function_finalize_info info); +#endif -/*! -Binds a float value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_float(duckdb_prepared_statement prepared_statement, idx_t param_idx, float val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the client context of the current connection during the finalize-phase of the `COPY ... TO` function. + * + * Must be destroyed with `duckdb_destroy_client_context` + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The finalize info provided to the finalize function + * @return duckdb_client_context + */ +DUCKDB_C_API duckdb_client_context +duckdb_copy_function_finalize_get_client_context(duckdb_copy_function_finalize_info info); +#endif -/*! -Binds a double value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_double(duckdb_prepared_statement prepared_statement, idx_t param_idx, double val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the bind data provided during the binding-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The finalize info provided to the finalize function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_finalize_get_bind_data(duckdb_copy_function_finalize_info info); +#endif -/*! -Binds a duckdb_date value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_date(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_date val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the global state provided during the init-phase of a `COPY ... TO` function. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param info The finalize info provided to the finalize function + * @return void* + */ +DUCKDB_C_API void *duckdb_copy_function_finalize_get_global_state(duckdb_copy_function_finalize_info info); +#endif -/*! -Binds a duckdb_time value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_time(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_time val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the table function to use when executing a `COPY ... FROM (...)` statement with this copy function. + * + * The table function must have a `duckdb_table_function_bind_t`, `duckdb_table_function_init_t` and + * `duckdb_table_function_t` set. + * + * The table function must take a single VARCHAR parameter (the file path). + * + * Options passed to the `COPY ... FROM (...)` statement are forwarded as named parameters to the table function. + * + * Since `COPY ... FROM` copies into an already existing table, the table function should not define its own result + * columns using `duckdb_bind_add_result_column` when binding . Instead use + * `duckdb_table_function_bind_get_result_column_count` and related functions in the bind callback of the table function + * to retrieve the schema of the target table of the `COPY ... FROM` statement. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param copy_function The copy function + * @param table_function The table function to use for `COPY ... FROM` + * @return void + */ +DUCKDB_C_API void duckdb_copy_function_set_copy_from_function(duckdb_copy_function copy_function, + duckdb_table_function table_function); +#endif -/*! -Binds a duckdb_timestamp value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_timestamp(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_timestamp val); +/* --- Struct definitions for copy_function --- */ -/*! -Binds a duckdb_timestamp value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_timestamp_tz(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_timestamp val); +/* ============================================================================ + * MODULE: data_chunk + * ============================================================================ */ -/*! -Binds a duckdb_interval value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_interval(duckdb_prepared_statement prepared_statement, idx_t param_idx, - duckdb_interval val); +/* --- Enums for data_chunk --- */ -/*! -Binds a null-terminated varchar value to the prepared statement at the specified index. +/* --- Struct forward declarations for data_chunk --- */ -Superseded by `duckdb_bind_value`. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_varchar(duckdb_prepared_statement prepared_statement, idx_t param_idx, - const char *val); +/* --- Types for data_chunk --- */ -/*! -Binds a varchar value to the prepared statement at the specified index. +/* --- Constants for data_chunk --- */ -Superseded by `duckdb_bind_value`. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_varchar_length(duckdb_prepared_statement prepared_statement, idx_t param_idx, - const char *val, idx_t length); +/* --- Function pointer typedefs for data_chunk --- */ -/*! -Binds a blob value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_blob(duckdb_prepared_statement prepared_statement, idx_t param_idx, - const void *data, idx_t length); +/* --- Functions for data_chunk --- */ +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Binds a NULL value to the prepared statement at the specified index. -*/ -DUCKDB_C_API duckdb_state duckdb_bind_null(duckdb_prepared_statement prepared_statement, idx_t param_idx); - -//---------------------------------------------------------------------------------------------------------------------- -// Execute Prepared Statements -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to execute a prepared statement. -//---------------------------------------------------------------------------------------------------------------------- + * Creates an empty data chunk with the specified column types. The result must be destroyed with + * `duckdb_destroy_data_chunk`. + * + * history: + * - stable: v0.3.3 + * + * @param types An array of column types. Column types can not contain ANY and INVALID types. + * @param column_count The number of columns. + * @return duckdb_data_chunk + */ +DUCKDB_C_API duckdb_data_chunk duckdb_create_data_chunk(duckdb_logical_type *types, idx_t column_count); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Executes the prepared statement with the given bound parameters, and returns a materialized query result. + * Destroys the data chunk and de-allocates all memory allocated for that chunk. + * + * history: + * - stable: v0.3.3 + * + * @param chunk The data chunk to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_data_chunk(duckdb_data_chunk *chunk); +#endif -This method can be called multiple times for each prepared statement, and the parameters can be modified -between calls to this function. +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Resets a data chunk, clearing the validity masks and setting the cardinality of the data chunk to 0. After calling + * this method, you must call `duckdb_vector_get_validity` and `duckdb_vector_get_data` to obtain current data and + * validity pointers + * + * history: + * - stable: v0.3.3 + * + * @param chunk The data chunk to reset. + * @return void + */ +DUCKDB_C_API void duckdb_data_chunk_reset(duckdb_data_chunk chunk); +#endif -Note that the result must be freed with `duckdb_destroy_result`. +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the number of columns in a data chunk. + * + * history: + * - stable: v0.3.3 + * + * @param chunk The data chunk to get the data from + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_data_chunk_get_column_count(duckdb_data_chunk chunk); +#endif -* @param prepared_statement The prepared statement to execute. -* @param out_result The query result. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_execute_prepared(duckdb_prepared_statement prepared_statement, - duckdb_result *out_result); +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the vector at the specified column index in the data chunk. + * + * The pointer to the vector is valid for as long as the chunk is alive. It does NOT need to be destroyed. + * + * history: + * - stable: v0.3.3 + * + * @param chunk The data chunk to get the data from + * @param col_idx + * @return duckdb_vector + */ +DUCKDB_C_API duckdb_vector duckdb_data_chunk_get_vector(duckdb_data_chunk chunk, idx_t col_idx); +#endif -#ifndef DUCKDB_API_NO_DEPRECATED +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + * Retrieves the current number of tuples in a data chunk. + * + * history: + * - stable: v0.3.3 + * + * @param chunk The data chunk to get the data from + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_data_chunk_get_size(duckdb_data_chunk chunk); +#endif -Executes the prepared statement with the given bound parameters, and returns an optionally-streaming query result. -To determine if the resulting query was in fact streamed, use `duckdb_result_is_streaming` +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Sets the current number of tuples in a data chunk. + * + * history: + * - stable: v0.3.3 + * + * @param chunk The data chunk to set the size in + * @param size The number of tuples in the data chunk + * @return void + */ +DUCKDB_C_API void duckdb_data_chunk_set_size(duckdb_data_chunk chunk, idx_t size); +#endif -This method can be called multiple times for each prepared statement, and the parameters can be modified -between calls to this function. +/* --- Struct definitions for data_chunk --- */ -Note that the result must be freed with `duckdb_destroy_result`. +/* ============================================================================ + * MODULE: database + * ============================================================================ */ -* @param prepared_statement The prepared statement to execute. -* @param out_result The query result. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_execute_prepared_streaming(duckdb_prepared_statement prepared_statement, - duckdb_result *out_result); +/* --- Enums for database --- */ -#endif +/* --- Struct forward declarations for database --- */ -//---------------------------------------------------------------------------------------------------------------------- -// Extract Statements -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// A query string can be extracted into multiple SQL statements. Each statement should be prepared and executed -// separately. -//---------------------------------------------------------------------------------------------------------------------- +/* --- Types for database --- */ -/*! -Extract all statements from a query. -Note that after calling `duckdb_extract_statements`, the extracted statements should always be destroyed using -`duckdb_destroy_extracted`, even if no statements were extracted. +/* --- Constants for database --- */ -If the extract fails, `duckdb_extract_statements_error` can be called to obtain the reason why the extract failed. +/* --- Function pointer typedefs for database --- */ -* @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_C_API idx_t duckdb_extract_statements(duckdb_connection connection, const char *query, - duckdb_extracted_statements *out_extracted_statements); +/* --- Functions for database --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -Prepare an extracted statement. -Note that after calling `duckdb_prepare_extracted_statement`, the prepared statement should always be destroyed using -`duckdb_destroy_prepare`, even if the prepare fails. + * Creates a new database instance cache. The instance cache is necessary if a client/program (re)opens multiple + * databases to the same file within the same process. Must be destroyed with 'duckdb_destroy_instance_cache'. + * + * history: + * - unstable: v1.2.0 + * - stable: v1.5.6 + * + * @return duckdb_instance_cache + */ +DUCKDB_C_API duckdb_instance_cache duckdb_create_instance_cache(void); +#endif -If the prepare fails, `duckdb_prepare_error` can be called to obtain the reason why the prepare failed. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Creates a new database instance in the instance cache, or retrieves an existing database instance. Must be closed + * with 'duckdb_close'. + * + * history: + * - unstable: v1.2.0 + * - stable: v1.5.6 + * + * @param instance_cache The instance cache in which to create the database, or from which to take the database. + * @param path Path to the database file on disk. Both `nullptr` and `:memory:` open or retrieve an in-memory database. + * @param out_database The resulting cached database. + * @param config (Optional) configuration used to create the database. + * @param out_error If set and the function returns `DuckDBError`, this contains the error message. Note that the error + * message must be freed using `duckdb_free`. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_get_or_create_from_cache(duckdb_instance_cache instance_cache, const char *path, + duckdb_database *out_database, duckdb_config config, + char **out_error); +#endif -* @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_C_API duckdb_state duckdb_prepare_extracted_statement(duckdb_connection connection, - duckdb_extracted_statements extracted_statements, - idx_t index, - duckdb_prepared_statement *out_prepared_statement); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys an existing database instance cache and de-allocates its memory. + * + * history: + * - unstable: v1.2.0 + * - stable: v1.5.6 + * + * @param instance_cache The instance cache to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_instance_cache(duckdb_instance_cache *instance_cache); +#endif /*! -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. + * Creates a new database or opens an existing database file stored at the given path. If no path is given a new + * in-memory database is created instead. The database must be closed with 'duckdb_close'. + * + * history: + * - stable: v0.1.0 + * + * @param path Path to the database file on disk. Both `nullptr` and `:memory:` open an in-memory database. + * @param out_database The result database object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_open(const char *path, duckdb_database *out_database); -* @param extracted_statements The extracted statements to fetch the error from. -* @return The error of the extracted statements. -*/ -DUCKDB_C_API const char *duckdb_extract_statements_error(duckdb_extracted_statements extracted_statements); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) +/*! + * Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the given path. + * The database must be closed with 'duckdb_close'. + * + * history: + * - stable: v0.2.8 + * + * @param path Path to the database file on disk. Both `nullptr` and `:memory:` open an in-memory database. + * @param out_database The result database object. + * @param config (Optional) configuration used to start up the database. + * @param out_error If set and the function returns `DuckDBError`, this contains the error message. Note that the error + * message must be freed using `duckdb_free`. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config, + char **out_error); +#endif /*! -De-allocates all memory allocated for the extracted statements. -* @param extracted_statements The extracted statements to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_extracted(duckdb_extracted_statements *extracted_statements); + * 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` or `duckdb_open_ext`. 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. + * + * history: + * - stable: v0.1.0 + * + * @param database The database object to shut down. + * @return void + */ +DUCKDB_C_API void duckdb_close(duckdb_database *database); -//---------------------------------------------------------------------------------------------------------------------- -// Pending Result Interface -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to interact with a pending result. First, prepare a pending result, and then execute it. -//---------------------------------------------------------------------------------------------------------------------- +#if DUCKDB_API_VERSION_AT_LEAST(0, 6, 0) +/*! + * Returns the version of the linked DuckDB, with a version postfix for dev versions + * + * Usually used for developing C extensions that must return this for a compatibility check. + * + * history: + * - stable: v0.6.0 + * + * @return const char* + */ +DUCKDB_C_API const char *duckdb_library_version(void); +#endif -/*! -Executes the prepared statement with the given bound parameters, and returns a pending result. -The pending result represents an intermediate structure for a query that is not yet fully executed. -The pending result can be used to incrementally execute a query, returning control to the client between tasks. - -Note that after calling `duckdb_pending_prepared`, the pending result should always be destroyed using -`duckdb_destroy_pending`, even if this function returns DuckDBError. - -* @param prepared_statement The prepared statement to execute. -* @param out_result The pending query result. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_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. - -Executes the prepared statement with the given bound parameters, and returns a pending result. -This pending result will create a streaming duckdb_result when executed. -The pending result represents an intermediate structure for a query that is not yet fully executed. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) +/*! + * Initializes an empty configuration object that can be used to provide start-up options for the DuckDB instance + * through `duckdb_open_ext`. The duckdb_config must be destroyed using 'duckdb_destroy_config' + * + * This will always succeed unless there is a malloc failure. + * + * Note that `duckdb_destroy_config` should always be called on the resulting config, even if the function returns + * `DuckDBError`. + * + * history: + * - stable: v0.2.8 + * + * @param out_config The result configuration object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_create_config(duckdb_config *out_config); +#endif -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. +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) +/*! + * 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. + * + * history: + * - stable: v0.2.8 + * + * @return size_t + */ +DUCKDB_C_API size_t duckdb_config_count(void); +#endif -* @param prepared_statement The prepared statement to execute. -* @param out_result The pending query result. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_pending_prepared_streaming(duckdb_prepared_statement prepared_statement, - duckdb_pending_result *out_result); +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) +/*! + * 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. + * + * history: + * - stable: v0.2.8 + * + * @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 duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_get_config_flag(size_t index, const char **out_name, const char **out_description); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) +/*! + * 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. + * + * history: + * - stable: v0.2.8 + * + * @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 duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_set_config(duckdb_config config, const char *name, const char *option); #endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 2, 8) /*! -Closes the pending result and de-allocates all memory allocated for the result. + * Destroys the specified configuration object and de-allocates all memory allocated for the object. + * + * history: + * - stable: v0.2.8 + * + * @param config The configuration object to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_config(duckdb_config *config); +#endif -* @param pending_result The pending result to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_pending(duckdb_pending_result *pending_result); +/* --- Struct definitions for database --- */ -/*! -Returns the error message contained within the pending result. +/* ============================================================================ + * MODULE: expression + * ============================================================================ */ -The result of this function must not be freed. It will be cleaned up when `duckdb_destroy_pending` is called. +/* --- Enums for expression --- */ -* @param pending_result The pending result to fetch the error from. -* @return The error of the pending result. -*/ -DUCKDB_C_API const char *duckdb_pending_error(duckdb_pending_result pending_result); +/* --- Struct forward declarations for expression --- */ -/*! -Executes a single task within the query, returning whether or not the query is ready. +/* --- Types for expression --- */ -If this returns DUCKDB_PENDING_RESULT_READY, the duckdb_execute_pending function can be called to obtain the result. -If this returns DUCKDB_PENDING_RESULT_NOT_READY, the duckdb_pending_execute_task function should be called again. -If this returns DUCKDB_PENDING_ERROR, an error occurred during execution. +/* --- Constants for expression --- */ -The error message can be obtained by calling duckdb_pending_error on the pending_result. +/* --- Function pointer typedefs for expression --- */ -* @param pending_result The pending result to execute a task within. -* @return The state of the pending result after the execution. -*/ -DUCKDB_C_API duckdb_pending_state duckdb_pending_execute_task(duckdb_pending_result pending_result); +/* --- Functions for expression --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -If this returns DUCKDB_PENDING_RESULT_READY, the duckdb_execute_pending function can be called to obtain the result. -If this returns DUCKDB_PENDING_RESULT_NOT_READY, the duckdb_pending_execute_check_state function should be called again. -If this returns DUCKDB_PENDING_ERROR, an error occurred during execution. + * Destroys the expression and de-allocates its memory. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param expr A pointer to the expression. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_expression(duckdb_expression *expr); +#endif -The error message can be obtained by calling duckdb_pending_error on the pending_result. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Returns the return type of an expression. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param expr The expression. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_expression_return_type(duckdb_expression expr); +#endif -* @param pending_result The pending result. -* @return The state of the pending result. -*/ -DUCKDB_C_API duckdb_pending_state duckdb_pending_execute_check_state(duckdb_pending_result pending_result); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Returns whether the expression is foldable into a value or not. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param expr The expression. + * @return bool + */ +DUCKDB_C_API bool duckdb_expression_is_foldable(duckdb_expression expr); +#endif -/*! -Fully execute a pending query result, returning the final query result. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Folds an expression creating a folded value. + * + * history: + * - unstable: v1.4.0 + * - stable: v1.5.6 + * + * @param context The client context. + * @param expr The expression. Must be foldable. + * @param out_value The folded value, if folding was successful. Must be destroyed with `duckdb_destroy_value`. + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_expression_fold(duckdb_client_context context, duckdb_expression expr, + duckdb_value *out_value); +#endif -If duckdb_pending_execute_task has been called until DUCKDB_PENDING_RESULT_READY was returned, this will return fast. -Otherwise, all remaining tasks must be executed first. +/* --- Struct definitions for expression --- */ -Note that the result must be freed with `duckdb_destroy_result`. +/* ============================================================================ + * MODULE: file_system + * ============================================================================ */ -* @param pending_result The pending result to execute. -* @param out_result The result object. -* @return `DuckDBSuccess` on success or `DuckDBError` on failure. -*/ -DUCKDB_C_API duckdb_state duckdb_execute_pending(duckdb_pending_result pending_result, duckdb_result *out_result); +/* --- Enums for file_system --- */ -/*! -Returns whether a duckdb_pending_state is finished executing. For example if `pending_state` is -DUCKDB_PENDING_RESULT_READY, this function will return true. +/* --- Struct forward declarations for file_system --- */ -* @param pending_state The pending state on which to decide whether to finish execution. -* @return Boolean indicating pending execution should be considered finished. -*/ -DUCKDB_C_API bool duckdb_pending_execution_is_finished(duckdb_pending_state pending_state); +/* --- Types for file_system --- */ -//---------------------------------------------------------------------------------------------------------------------- -// Value Interface -//---------------------------------------------------------------------------------------------------------------------- -// DESCRIPTION: -// Functions to create a `duckdb_value` for each of DuckDB's supported data types, and to access the contents of a -// `duckdb_value`. The `duckdb_value` wrapper allows handling of primitive and arbitrarily (nested) types through the -// same interface. -//---------------------------------------------------------------------------------------------------------------------- +/* --- Constants for file_system --- */ -/*! -Destroys the value and de-allocates all memory allocated for that type. +/* --- Function pointer typedefs for file_system --- */ -* @param value The value to destroy. -*/ -DUCKDB_C_API void duckdb_destroy_value(duckdb_value *value); +/* --- Functions for file_system --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -Creates a value from a null-terminated string. Returns nullptr if the string is not valid UTF-8 or other invalid input. - -Superseded by `duckdb_create_varchar_length`. + * Get a file system instance associated with the given client context. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param context The client context. + * @return duckdb_file_system + */ +DUCKDB_C_API duckdb_file_system duckdb_client_context_get_file_system(duckdb_client_context context); +#endif -* @param text The null-terminated string -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_varchar(const char *text); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the given file system instance. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_system The file system instance to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_file_system(duckdb_file_system *file_system); +#endif -/*! -Creates a value from a string. Returns nullptr if the string is not valid UTF-8 or other invalid input. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the last error that occurred on the given file system instance. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_system The file system instance. + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_file_system_error_data(duckdb_file_system file_system); +#endif -* @param text The text -* @param length The length of the text -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_varchar_length(const char *text, idx_t length); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Opens a file at the given path with the specified options. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_system The file system instance. + * @param path The path to the file. + * @param options The file open options specifying how to open the file. + * @param out_file The resulting file handle instance, or `nullptr` if the open failed. Must be destroyed with + * `duckdb_destroy_file_handle`. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_file_system_open(duckdb_file_system file_system, const char *path, + duckdb_file_open_options options, duckdb_file_handle *out_file); +#endif -/*! -Creates a value from a boolean +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Creates a new file open options instance with blank settings. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @return duckdb_file_open_options + */ +DUCKDB_C_API duckdb_file_open_options duckdb_create_file_open_options(void); +#endif -* @param input The boolean value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_bool(bool input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets a specific flag in the file open options. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param options The file open options instance. + * @param flag The flag to set (e.g., read, write). + * @param value If the flag is enabled or disabled. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_file_open_options_set_flag(duckdb_file_open_options options, duckdb_file_flag flag, + bool value); +#endif -/*! -Creates a value from an int8_t (a tinyint) +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the given file open options instance. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param options The file open options instance to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_file_open_options(duckdb_file_open_options *options); +#endif -* @param input The tinyint value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_int8(int8_t input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys the given file handle and deallocates all associated resources. This will also close the file if it is still + * open. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_file_handle(duckdb_file_handle *file_handle); +#endif -/*! -Creates a value from a uint8_t (a utinyint) +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Retrieves the last error that occurred on the given file handle. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle. + * @return duckdb_error_data + */ +DUCKDB_C_API duckdb_error_data duckdb_file_handle_error_data(duckdb_file_handle file_handle); +#endif -* @param input The utinyint value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_uint8(uint8_t input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Reads data from the file into the buffer. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to read from. + * @param buffer The buffer to read data into. + * @param size The number of bytes to read. + * @return int64_t + */ +DUCKDB_C_API int64_t duckdb_file_handle_read(duckdb_file_handle file_handle, void *buffer, int64_t size); +#endif -/*! -Creates a value from an int16_t (a smallint) +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Writes data from the buffer to the file. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to write to. + * @param buffer The buffer containing data to write. + * @param size The number of bytes to write. + * @return int64_t + */ +DUCKDB_C_API int64_t duckdb_file_handle_write(duckdb_file_handle file_handle, const void *buffer, int64_t size); +#endif -* @param input The smallint value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_int16(int16_t input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Tells the current position in the file. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to tell the position of. + * @return int64_t + */ +DUCKDB_C_API int64_t duckdb_file_handle_tell(duckdb_file_handle file_handle); +#endif -/*! -Creates a value from a uint16_t (a usmallint) +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Gets the size of the file. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to get the size of. + * @return int64_t + */ +DUCKDB_C_API int64_t duckdb_file_handle_size(duckdb_file_handle file_handle); +#endif -* @param input The usmallint value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_uint16(uint16_t input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Seeks to a specific position in the file. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to seek in. + * @param position + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_file_handle_seek(duckdb_file_handle file_handle, int64_t position); +#endif -/*! -Creates a value from an int32_t (an integer) +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Synchronizes the file's state with the underlying storage. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to synchronize. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_file_handle_sync(duckdb_file_handle file_handle); +#endif -* @param input The integer value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_int32(int32_t input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Closes the given file handle. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param file_handle The file handle to close. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_file_handle_close(duckdb_file_handle file_handle); +#endif -/*! -Creates a value from a uint32_t (a uinteger) +/* --- Struct definitions for file_system --- */ -* @param input The uinteger value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_uint32(uint32_t input); +/* ============================================================================ + * MODULE: log_storage + * ============================================================================ */ -/*! -Creates a value from a uint64_t (a ubigint) +/* --- Enums for log_storage --- */ -* @param input The ubigint value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_uint64(uint64_t input); +/* --- Struct forward declarations for log_storage --- */ -/*! -Creates a value from an int64 +/* --- Types for log_storage --- */ -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_int64(int64_t val); +/* --- Constants for log_storage --- */ -/*! -Creates a value from a hugeint +/* --- Function pointer typedefs for log_storage --- */ -* @param input The hugeint value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_hugeint(duckdb_hugeint input); +/* --- Functions for log_storage --- */ +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) /*! -Creates a value from a uhugeint + * Creates a new log storage object. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @return duckdb_log_storage + */ +DUCKDB_C_API duckdb_log_storage duckdb_create_log_storage(void); +#endif -* @param input The uhugeint value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_uhugeint(duckdb_uhugeint input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Destroys a log storage object. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param log_storage The log storage object to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_log_storage(duckdb_log_storage *log_storage); +#endif -/*! -Creates a BIGNUM value from a duckdb_bignum +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the callback function for writing log entries. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param log_storage The log storage object. + * @param function The function to call. + * @return void + */ +DUCKDB_C_API void duckdb_log_storage_set_write_log_entry(duckdb_log_storage log_storage, + duckdb_logger_write_log_entry_t function); +#endif -* @param input The duckdb_bignum value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_bignum(duckdb_bignum input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the extra data of the custom log storage. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param log_storage The log storage object. + * @param extra_data The extra data that is passed back into the callbacks. + * @param delete_callback + * @return void + */ +DUCKDB_C_API void duckdb_log_storage_set_extra_data(duckdb_log_storage log_storage, void *extra_data, + duckdb_delete_callback_t delete_callback); +#endif -/*! -Creates a DECIMAL value from a duckdb_decimal +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Sets the name of the log storage. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param log_storage The log storage object. + * @param name The name of the log storage. + * @return void + */ +DUCKDB_C_API void duckdb_log_storage_set_name(duckdb_log_storage log_storage, const char *name); +#endif -* @param input The duckdb_decimal value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_decimal(duckdb_decimal input); +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Registers a custom log storage for the logger. + * + * history: + * - unstable: v1.5.0 + * - stable: v1.5.6 + * + * @param database A database object. + * @param log_storage The log storage object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_register_log_storage(duckdb_database database, duckdb_log_storage log_storage); +#endif -/*! -Creates a value from a float +/* --- Struct definitions for log_storage --- */ -* @param input The float value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_float(float input); +/* ============================================================================ + * MODULE: logical_type + * ============================================================================ */ -/*! -Creates a value from a double +/* --- Enums for logical_type --- */ -* @param input The double value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_double(double input); +/* --- Struct forward declarations for logical_type --- */ -/*! -Creates a value from a date +/* --- Types for logical_type --- */ -* @param input The date value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_date(duckdb_date input); +/* --- Constants for logical_type --- */ -/*! -Creates a value from a time +/* --- Function pointer typedefs for logical_type --- */ -* @param input The time value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_time(duckdb_time input); +/* --- Functions for logical_type --- */ +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Creates a value from a time_ns - -* @param input The time value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_time_ns(duckdb_time_ns input); + * Creates a `duckdb_logical_type` from a primitive type. The resulting logical type must be destroyed with + * `duckdb_destroy_logical_type`. + * + * Returns an invalid logical type, if type is: `DUCKDB_TYPE_INVALID`, `DUCKDB_TYPE_DECIMAL`, `DUCKDB_TYPE_ENUM`, + * `DUCKDB_TYPE_LIST`, `DUCKDB_TYPE_STRUCT`, `DUCKDB_TYPE_MAP`, `DUCKDB_TYPE_ARRAY`, or `DUCKDB_TYPE_UNION`. + * + * history: + * - stable: v0.3.3 + * + * @param type The primitive type to create. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_logical_type(duckdb_type type); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) /*! -Creates a value from a time_tz. -Not to be confused with `duckdb_create_time_tz`, which creates a duckdb_time_tz_t. + * Returns the alias of a duckdb_logical_type, if set, else `nullptr`. The result must be destroyed with `duckdb_free`. + * + * history: + * - stable: v0.10.0 + * + * @param type The logical type + * @return char* + */ +DUCKDB_C_API char *duckdb_logical_type_get_alias(duckdb_logical_type type); +#endif -* @param value The time_tz value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_time_tz_value(duckdb_time_tz value); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Sets the alias of a duckdb_logical_type. + * + * history: + * - stable: v1.1.0 + * + * @param type The logical type + * @param alias The alias to set + * @return void + */ +DUCKDB_C_API void duckdb_logical_type_set_alias(duckdb_logical_type type, const char *alias); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 4, 0) /*! -Creates a TIMESTAMP value from a duckdb_timestamp - -* @param input The duckdb_timestamp value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_timestamp(duckdb_timestamp input); + * Creates a LIST type from its child type. The return type must be destroyed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.4.0 + * + * @param type The child type of the list + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_list_type(duckdb_logical_type type); +#endif -/*! -Creates a TIMESTAMP_TZ value from a duckdb_timestamp +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 1) +/*! + * Creates an ARRAY type from its child type. The return type must be destroyed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.10.1 + * + * @param type The child type of the array. + * @param array_size The number of elements in the array. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_array_type(duckdb_logical_type type, idx_t array_size); +#endif -* @param input The duckdb_timestamp value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_timestamp_tz(duckdb_timestamp input); +#if DUCKDB_API_VERSION_AT_LEAST(0, 4, 0) +/*! + * Creates a MAP type from its key type and value type. The return type must be destroyed with + * `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.4.0 + * + * @param key_type The map's key type. + * @param value_type The map's value type. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_map_type(duckdb_logical_type key_type, duckdb_logical_type value_type); +#endif -/*! -Creates a TIMESTAMP_S value from a duckdb_timestamp_s +#if DUCKDB_API_VERSION_AT_LEAST(0, 7, 0) +/*! + * Creates a UNION type from the passed arrays. The return type must be destroyed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.7.0 + * + * @param member_types The array of union member types. + * @param member_names The union member names. + * @param member_count The number of union members. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_union_type(duckdb_logical_type *member_types, const char **member_names, + idx_t member_count); +#endif -* @param input The duckdb_timestamp_s value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_timestamp_s(duckdb_timestamp_s input); +#if DUCKDB_API_VERSION_AT_LEAST(0, 9, 0) +/*! + * Creates a STRUCT type based on the member types and names. The resulting type must be destroyed with + * `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.9.0 + * + * @param member_types The array of types of the struct members. + * @param member_names The array of names of the struct members. + * @param member_count The number of members of the struct. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_struct_type(duckdb_logical_type *member_types, const char **member_names, + idx_t member_count); +#endif -/*! -Creates a TIMESTAMP_MS value from a duckdb_timestamp_ms +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * Creates an ENUM type from the passed member name array. The resulting type should be destroyed with + * `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.10.0 + * + * @param member_names The array of names that the enum should consist of. + * @param member_count The number of elements that were specified in the array. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_enum_type(const char **member_names, idx_t member_count); +#endif -* @param input The duckdb_timestamp_ms value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_timestamp_ms(duckdb_timestamp_ms input); +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Creates a DECIMAL type with the specified width and scale. The resulting type should be destroyed with + * `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.3.3 + * + * @param width The width of the decimal type + * @param scale The scale of the decimal type + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_create_decimal_type(uint8_t width, uint8_t scale); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Creates a TIMESTAMP_NS value from a duckdb_timestamp_ns - -* @param input The duckdb_timestamp_ns value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_timestamp_ns(duckdb_timestamp_ns input); + * Retrieves the enum `duckdb_type` of a `duckdb_logical_type`. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type. + * @return duckdb_type + */ +DUCKDB_C_API duckdb_type duckdb_get_type_id(duckdb_logical_type type); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Creates a value from an interval + * Retrieves the width of a decimal type. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @return uint8_t + */ +DUCKDB_C_API uint8_t duckdb_decimal_width(duckdb_logical_type type); +#endif -* @param input The interval value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_interval(duckdb_interval input); +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the scale of a decimal type. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @return uint8_t + */ +DUCKDB_C_API uint8_t duckdb_decimal_scale(duckdb_logical_type type); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Creates a value from a blob + * Retrieves the internal storage type of a decimal type. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @return duckdb_type + */ +DUCKDB_C_API duckdb_type duckdb_decimal_internal_type(duckdb_logical_type type); +#endif -* @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_C_API duckdb_value duckdb_create_blob(const uint8_t *data, idx_t length); +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the internal storage type of an enum type. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @return duckdb_type + */ +DUCKDB_C_API duckdb_type duckdb_enum_internal_type(duckdb_logical_type type); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Creates a BIT value from a duckdb_bit + * Retrieves the dictionary size of the enum type. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @return uint32_t + */ +DUCKDB_C_API uint32_t duckdb_enum_dictionary_size(duckdb_logical_type type); +#endif -* @param input The duckdb_bit value -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_bit(duckdb_bit input); +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the dictionary value at the specified position from the enum. + * + * The result must be freed with `duckdb_free`. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @param index The index in the dictionary + * @return char* + */ +DUCKDB_C_API char *duckdb_enum_dictionary_value(duckdb_logical_type type, idx_t index); +#endif -/*! -Creates a UUID value from a uhugeint +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the child type of the given LIST type. Also accepts MAP types. The result must be freed with + * `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type, either LIST or MAP. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_list_type_child_type(duckdb_logical_type type); +#endif -* @param input The duckdb_uhugeint containing the UUID -* @return The value. This must be destroyed with `duckdb_destroy_value`. -*/ -DUCKDB_C_API duckdb_value duckdb_create_uuid(duckdb_uhugeint input); +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 1) +/*! + * Retrieves the child type of the given ARRAY type. + * + * The result must be freed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.10.1 + * + * @param type The logical type. Must be ARRAY. + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_array_type_child_type(duckdb_logical_type type); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 1) /*! -Returns the boolean value of the given value. + * Retrieves the array size of the given array type. + * + * history: + * - stable: v0.10.1 + * + * @param type The logical type object + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_array_type_array_size(duckdb_logical_type type); +#endif -* @param val A duckdb_value containing a boolean -* @return A boolean, or false if the value cannot be converted -*/ -DUCKDB_C_API bool duckdb_get_bool(duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(0, 4, 0) +/*! + * Retrieves the key type of the given map type. + * + * The result must be freed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.4.0 + * + * @param type The logical type object + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_map_type_key_type(duckdb_logical_type type); +#endif + +#if DUCKDB_API_VERSION_AT_LEAST(0, 4, 0) +/*! + * Retrieves the value type of the given map type. + * + * The result must be freed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.4.0 + * + * @param type The logical type object + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_map_type_value_type(duckdb_logical_type type); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Returns the int8_t value of the given value. + * Returns the number of children of a struct type. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_struct_type_child_count(duckdb_logical_type type); +#endif -* @param val A duckdb_value containing a tinyint -* @return A int8_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API int8_t duckdb_get_int8(duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the name of the struct child. + * + * The result must be freed with `duckdb_free`. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @param index The child index + * @return char* + */ +DUCKDB_C_API char *duckdb_struct_type_child_name(duckdb_logical_type type, idx_t index); +#endif + +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) +/*! + * Retrieves the child type of the given struct type at the specified index. + * + * The result must be freed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type object + * @param index The child index + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_struct_type_child_type(duckdb_logical_type type, idx_t index); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 7, 0) /*! -Returns the uint8_t value of the given value. + * Returns the number of members that the union type has. + * + * history: + * - stable: v0.7.0 + * + * @param type The logical type (union) object + * @return idx_t + */ +DUCKDB_C_API idx_t duckdb_union_type_member_count(duckdb_logical_type type); +#endif -* @param val A duckdb_value containing a utinyint -* @return A uint8_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API uint8_t duckdb_get_uint8(duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(0, 7, 0) +/*! + * Retrieves the name of the union member. + * + * The result must be freed with `duckdb_free`. + * + * history: + * - stable: v0.7.0 + * + * @param type The logical type object + * @param index The child index + * @return char* + */ +DUCKDB_C_API char *duckdb_union_type_member_name(duckdb_logical_type type, idx_t index); +#endif + +#if DUCKDB_API_VERSION_AT_LEAST(0, 7, 0) +/*! + * Retrieves the child type of the given union member at the specified index. + * + * The result must be freed with `duckdb_destroy_logical_type`. + * + * history: + * - stable: v0.7.0 + * + * @param type The logical type object + * @param index The child index + * @return duckdb_logical_type + */ +DUCKDB_C_API duckdb_logical_type duckdb_union_type_member_type(duckdb_logical_type type, idx_t index); +#endif +#if DUCKDB_API_VERSION_AT_LEAST(0, 3, 3) /*! -Returns the int16_t value of the given value. + * Destroys the logical type and de-allocates all memory allocated for that type. + * + * history: + * - stable: v0.3.3 + * + * @param type The logical type to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_logical_type(duckdb_logical_type *type); +#endif -* @param val A duckdb_value containing a smallint -* @return A int16_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API int16_t duckdb_get_int16(duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(1, 1, 0) +/*! + * Registers a custom type within the given connection. The type must have an alias + * + * history: + * - stable: v1.1.0 + * + * @param con The connection to use + * @param type The custom type to register + * @param info + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_register_logical_type(duckdb_connection con, duckdb_logical_type type, + duckdb_create_type_info info); +#endif -/*! -Returns the uint16_t value of the given value. +#if DUCKDB_API_VERSION_AT_LEAST(1, 5, 6) +/*! + * Gets the CRS (Coordinate Reference System) of a GEOMETRY type. Result must be freed with `duckdb_free`. + * + * history: + * - unstable: v1.5.2 + * - stable: v1.5.6 + * + * @param type The GEOMETRY type. + * @return char* + */ +DUCKDB_C_API char *duckdb_geometry_type_get_crs(duckdb_logical_type type); +#endif -* @param val A duckdb_value containing a usmallint -* @return A uint16_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API uint16_t duckdb_get_uint16(duckdb_value val); +/* --- Struct definitions for logical_type --- */ -/*! -Returns the int32_t value of the given value. +/* ============================================================================ + * MODULE: pending + * ============================================================================ */ -* @param val A duckdb_value containing an integer -* @return A int32_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API int32_t duckdb_get_int32(duckdb_value val); +/* --- Enums for pending --- */ -/*! -Returns the uint32_t value of the given value. +/* --- Struct forward declarations for pending --- */ -* @param val A duckdb_value containing a uinteger -* @return A uint32_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API uint32_t duckdb_get_uint32(duckdb_value val); +/* --- Types for pending --- */ -/*! -Returns the int64_t value of the given value. +/* --- Constants for pending --- */ -* @param val A duckdb_value containing a bigint -* @return A int64_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API int64_t duckdb_get_int64(duckdb_value val); +/* --- Function pointer typedefs for pending --- */ + +/* --- Functions for pending --- */ +#if DUCKDB_API_VERSION_AT_LEAST(0, 5, 0) /*! -Returns the uint64_t value of the given value. + * Executes the prepared statement with the given bound parameters, and returns a pending result. The pending result + * represents an intermediate structure for a query that is not yet fully executed. The pending result can be used to + * incrementally execute a query, returning control to the client between tasks. + * + * Note that after calling `duckdb_pending_prepared`, the pending result should always be destroyed using + * `duckdb_destroy_pending`, even if this function returns DuckDBError. + * + * history: + * - stable: v0.5.0 + * + * @param prepared_statement The prepared statement to execute. + * @param out_result The pending query result. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_pending_prepared(duckdb_prepared_statement prepared_statement, + duckdb_pending_result *out_result); +#endif -* @param val A duckdb_value containing a ubigint -* @return A uint64_t, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API uint64_t duckdb_get_uint64(duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(0, 5, 0) +/*! + * Closes the pending result and de-allocates all memory allocated for the result. + * + * Destroying a pending result whose statement has not completed aborts the statement. On autocommit, its writes are + * rolled back. Inside a transaction, a statement that may write invalidates the transaction, and a read-only statement + * just stops. Until the statement has completed, preparing or running another statement on the connection fails with + * `DUCKDB_ERROR_RESOURCE_IN_USE` and leaves it untouched. `duckdb_pending_execution_is_finished` reporting true does + * not mean that the statement completed. To make sure a statement takes effect, complete it before destroying the + * pending result: call `duckdb_execute_pending`, and fetch a streaming result until `duckdb_fetch_chunk` returns NULL. + * A NULL chunk is also returned on an error, so check `duckdb_result_error` afterwards. + * + * history: + * - stable: v0.5.0 + * + * @param pending_result The pending result to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_pending(duckdb_pending_result *pending_result); +#endif -/*! -Returns the hugeint value of the given value. +#if DUCKDB_API_VERSION_AT_LEAST(0, 5, 0) +/*! + * 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. + * + * history: + * - stable: v0.5.0 + * + * @param pending_result The pending result to fetch the error from. + * @return const char* + */ +DUCKDB_C_API const char *duckdb_pending_error(duckdb_pending_result pending_result); +#endif -* @param val A duckdb_value containing a hugeint -* @return A duckdb_hugeint, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API duckdb_hugeint duckdb_get_hugeint(duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(0, 5, 0) +/*! + * Executes a single task within the query, returning whether or not the query is ready. + * + * If this returns DUCKDB_PENDING_RESULT_READY, the duckdb_execute_pending function can be called to obtain the result. + * If this returns DUCKDB_PENDING_RESULT_NOT_READY, the duckdb_pending_execute_task function should be called again. 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. + * + * history: + * - stable: v0.5.0 + * + * @param pending_result The pending result to execute a task within. + * @return duckdb_pending_state + */ +DUCKDB_C_API duckdb_pending_state duckdb_pending_execute_task(duckdb_pending_result pending_result); +#endif -/*! -Returns the uhugeint value of the given value. +#if DUCKDB_API_VERSION_AT_LEAST(0, 10, 0) +/*! + * If this returns DUCKDB_PENDING_RESULT_READY, the duckdb_execute_pending function can be called to obtain the result. + * If this returns DUCKDB_PENDING_RESULT_NOT_READY, the duckdb_pending_execute_check_state function should be called + * again. 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. + * + * history: + * - stable: v0.10.0 + * + * @param pending_result The pending result. + * @return duckdb_pending_state + */ +DUCKDB_C_API duckdb_pending_state duckdb_pending_execute_check_state(duckdb_pending_result pending_result); +#endif -* @param val A duckdb_value containing a uhugeint -* @return A duckdb_uhugeint, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API duckdb_uhugeint duckdb_get_uhugeint(duckdb_value val); +#if DUCKDB_API_VERSION_AT_LEAST(0, 5, 0) +/*! + * Fully execute a pending query result, returning the final query result. + * + * If duckdb_pending_execute_task has been called until DUCKDB_PENDING_RESULT_READY was returned, this will return fast. + * Otherwise, all remaining tasks must be executed first. + * + * Note that the result must be freed with `duckdb_destroy_result`. + * + * history: + * - stable: v0.5.0 + * + * @param pending_result The pending result to execute. + * @param out_result The result object. + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_execute_pending(duckdb_pending_result pending_result, duckdb_result *out_result); +#endif -/*! -Returns the duckdb_bignum value of the given value. -The `data` field must be destroyed with `duckdb_free`. +#if DUCKDB_API_VERSION_AT_LEAST(0, 9, 0) +/*! + * Returns whether a duckdb_pending_state is finished executing. For example if `pending_state` is + * DUCKDB_PENDING_RESULT_READY, this function will return true. + * + * history: + * - stable: v0.9.0 + * + * @param pending_state The pending state on which to decide whether to finish execution. + * @return bool + */ +DUCKDB_C_API bool duckdb_pending_execution_is_finished(duckdb_pending_state pending_state); +#endif -* @param val A duckdb_value containing a BIGNUM -* @return A duckdb_bignum. The `data` field must be destroyed with `duckdb_free`. -*/ -DUCKDB_C_API duckdb_bignum duckdb_get_bignum(duckdb_value val); +/* --- Struct definitions for pending --- */ -/*! -Returns the duckdb_decimal value of the given value. +/* ============================================================================ + * MODULE: prepared_statement + * ============================================================================ */ -* @param val A duckdb_value containing a DECIMAL -* @return A duckdb_decimal, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API duckdb_decimal duckdb_get_decimal(duckdb_value val); +/* --- Enums for prepared_statement --- */ -/*! -Returns the float value of the given value. +/* --- Struct forward declarations for prepared_statement --- */ -* @param val A duckdb_value containing a float -* @return A float, or NAN if the value cannot be converted -*/ -DUCKDB_C_API float duckdb_get_float(duckdb_value val); +/* --- Types for prepared_statement --- */ -/*! -Returns the double value of the given value. +/* --- Constants for prepared_statement --- */ -* @param val A duckdb_value containing a double -* @return A double, or NAN if the value cannot be converted -*/ -DUCKDB_C_API double duckdb_get_double(duckdb_value val); +/* --- Function pointer typedefs for prepared_statement --- */ -/*! -Returns the date value of the given value. +/* --- Functions for prepared_statement --- */ -* @param val A duckdb_value containing a date -* @return A duckdb_date, or MinValue if the value cannot be converted -*/ -DUCKDB_C_API duckdb_date duckdb_get_date(duckdb_value val); +/*! + * Create a prepared statement object from a query. + * + * Note that after calling `duckdb_prepare`, the prepared statement should always be destroyed using + * `duckdb_destroy_prepare`, even if the prepare fails. + * + * If the prepare fails, `duckdb_prepare_error` can be called to obtain the reason why the prepare failed. + * + * history: + * - stable: v0.1.0 + * + * @param connection The connection object + * @param query The SQL query to prepare + * @param out_prepared_statement The resulting prepared statement object + * @return duckdb_state + */ +DUCKDB_C_API duckdb_state duckdb_prepare(duckdb_connection connection, const char *query, + duckdb_prepared_statement *out_prepared_statement); /*! -Returns the time value of the given value. + * Closes the prepared statement and de-allocates all memory allocated for the statement. + * + * history: + * - stable: v0.1.0 + * + * @param prepared_statement The prepared statement to destroy. + * @return void + */ +DUCKDB_C_API void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement); -* @param val A duckdb_value containing a time -* @return A duckdb_time, or MinValue