diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,4 @@ +# Changelog + +## 0.1.4.1 +- Initial release diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,373 @@ +Mozilla Public License Version 2.0 +================================== + +1. Definitions +-------------- + +1.1. "Contributor" + means each individual or legal entity that creates, contributes to + the creation of, or owns Covered Software. + +1.2. "Contributor Version" + means the combination of the Contributions of others (if any) used + by a Contributor and that particular Contributor's Contribution. + +1.3. "Contribution" + means Covered Software of a particular Contributor. + +1.4. "Covered Software" + means Source Code Form to which the initial Contributor has attached + the notice in Exhibit A, the Executable Form of such Source Code + Form, and Modifications of such Source Code Form, in each case + including portions thereof. + +1.5. "Incompatible With Secondary Licenses" + means + + (a) that the initial Contributor has attached the notice described + in Exhibit B to the Covered Software; or + + (b) that the Covered Software was made available under the terms of + version 1.1 or earlier of the License, but not also under the + terms of a Secondary License. + +1.6. "Executable Form" + means any form of the work other than Source Code Form. + +1.7. "Larger Work" + means a work that combines Covered Software with other material, in + a separate file or files, that is not Covered Software. + +1.8. "License" + means this document. + +1.9. "Licensable" + means having the right to grant, to the maximum extent possible, + whether at the time of the initial grant or subsequently, any and + all of the rights conveyed by this License. + +1.10. "Modifications" + means any of the following: + + (a) any file in Source Code Form that results from an addition to, + deletion from, or modification of the contents of Covered + Software; or + + (b) any new file in Source Code Form that contains any Covered + Software. + +1.11. "Patent Claims" of a Contributor + means any patent claim(s), including without limitation, method, + process, and apparatus claims, in any patent Licensable by such + Contributor that would be infringed, but for the grant of the + License, by the making, using, selling, offering for sale, having + made, import, or transfer of either its Contributions or its + Contributor Version. + +1.12. "Secondary License" + means either the GNU General Public License, Version 2.0, the GNU + Lesser General Public License, Version 2.1, the GNU Affero General + Public License, Version 3.0, or any later versions of those + licenses. + +1.13. "Source Code Form" + means the form of the work preferred for making modifications. + +1.14. "You" (or "Your") + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial + ownership of such entity. + +2. License Grants and Conditions +-------------------------------- + +2.1. Grants + +Each Contributor hereby grants You a world-wide, royalty-free, +non-exclusive license: + +(a) under intellectual property rights (other than patent or trademark) + Licensable by such Contributor to use, reproduce, make available, + modify, display, perform, distribute, and otherwise exploit its + Contributions, either on an unmodified basis, with Modifications, or + as part of a Larger Work; and + +(b) under Patent Claims of such Contributor to make, use, sell, offer + for sale, have made, import, and otherwise transfer either its + Contributions or its Contributor Version. + +2.2. Effective Date + +The licenses granted in Section 2.1 with respect to any Contribution +become effective for each Contribution on the date the Contributor first +distributes such Contribution. + +2.3. Limitations on Grant Scope + +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: + +(a) for any code that a Contributor has removed from Covered Software; + or + +(b) for infringements caused by: (i) Your and any other third party's + modifications of Covered Software, or (ii) the combination of its + Contributions with other software (except as part of its Contributor + Version); or + +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. + +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). + +2.4. Subsequent Licenses + +No Contributor makes additional grants as a result of Your choice to +distribute the Covered Software under a subsequent version of this +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). + +2.5. Representation + +Each Contributor represents that the Contributor believes its +Contributions are its original creation(s) or it has sufficient rights +to grant the rights to its Contributions conveyed by this License. + +2.6. Fair Use + +This License is not intended to limit any rights You have under +applicable copyright doctrines of fair use, fair dealing, or other +equivalents. + +2.7. Conditions + +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. + +3. Responsibilities +------------------- + +3.1. Distribution of Source Form + +All distribution of Covered Software in Source Code Form, including any +Modifications that You create or to which You contribute, must be under +the terms of this License. You must inform recipients that the Source +Code Form of the Covered Software is governed by the terms of this +License, and how they can obtain a copy of this License. You may not +attempt to alter or restrict the recipients' rights in the Source Code +Form. + +3.2. Distribution of Executable Form + +If You distribute Covered Software in Executable Form then: + +(a) such Covered Software must also be made available in Source Code + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and + +(b) You may distribute such Executable Form under the terms of this + License, or sublicense it under different terms, provided that the + license for the Executable Form does not attempt to limit or alter + the recipients' rights in the Source Code Form under this License. + +3.3. Distribution of a Larger Work + +You may create and distribute a Larger Work under terms of Your choice, +provided that You also comply with the requirements of this License for +the Covered Software. If the Larger Work is a combination of Covered +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this +License permits You to additionally distribute such Covered Software +under the terms of such Secondary License(s), so that the recipient of +the Larger Work may, at their option, further distribute the Covered +Software under the terms of either this License or such Secondary +License(s). + +3.4. Notices + +You may not remove or alter the substance of any license notices +(including copyright notices, patent notices, disclaimers of warranty, +or limitations of liability) contained within the Source Code Form of +the Covered Software, except that You may alter any license notices to +the extent required to remedy known factual inaccuracies. + +3.5. Application of Additional Terms + +You may choose to offer, and to charge a fee for, warranty, support, +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. + +4. Inability to Comply Due to Statute or Regulation +--------------------------------------------------- + +If it is impossible for You to comply with any of the terms of this +License with respect to some or all of the Covered Software due to +statute, judicial order, or regulation then You must: (a) comply with +the terms of this License to the maximum extent possible; and (b) +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. + +5. Termination +-------------- + +5.1. The rights granted under this License will terminate automatically +if You fail to comply with any of its terms. However, if You become +compliant, then the rights granted under this License from a particular +Contributor are reinstated (a) provisionally, unless and until such +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the +non-compliance by some reasonable means prior to 60 days after You have +come back into compliance. Moreover, Your grants from a particular +Contributor are reinstated on an ongoing basis if such Contributor +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. + +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, +counter-claims, and cross-claims) alleging that a Contributor Version +directly or indirectly infringes any patent, then the rights granted to +You by any and all Contributors for the Covered Software under Section +2.1 of this License shall terminate. + +5.3. In the event of termination under Sections 5.1 or 5.2 above, all +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. + +************************************************************************ +* * +* 6. Disclaimer of Warranty * +* ------------------------- * +* * +* Covered Software is provided under this License on an "as is" * +* basis, without warranty of any kind, either expressed, implied, or * +* statutory, including, without limitation, warranties that the * +* Covered Software is free of defects, merchantable, fit for a * +* particular purpose or non-infringing. The entire risk as to the * +* quality and performance of the Covered Software is with You. * +* Should any Covered Software prove defective in any respect, You * +* (not any Contributor) assume the cost of any necessary servicing, * +* repair, or correction. This disclaimer of warranty constitutes an * +* essential part of this License. No use of any Covered Software is * +* authorized under this License except under this disclaimer. * +* * +************************************************************************ + +************************************************************************ +* * +* 7. Limitation of Liability * +* -------------------------- * +* * +* Under no circumstances and under no legal theory, whether tort * +* (including negligence), contract, or otherwise, shall any * +* Contributor, or anyone who distributes Covered Software as * +* permitted above, be liable to You for any direct, indirect, * +* special, incidental, or consequential damages of any character * +* including, without limitation, damages for lost profits, loss of * +* goodwill, work stoppage, computer failure or malfunction, or any * +* and all other commercial damages or losses, even if such party * +* shall have been informed of the possibility of such damages. This * +* limitation of liability shall not apply to liability for death or * +* personal injury resulting from such party's negligence to the * +* extent applicable law prohibits such limitation. Some * +* jurisdictions do not allow the exclusion or limitation of * +* incidental or consequential damages, so this exclusion and * +* limitation may not apply to You. * +* * +************************************************************************ + +8. Litigation +------------- + +Any litigation relating to this License may be brought only in the +courts of a jurisdiction where the defendant maintains its principal +place of business and such litigation shall be governed by laws of that +jurisdiction, without reference to its conflict-of-law provisions. +Nothing in this Section shall prevent a party's ability to bring +cross-claims or counter-claims. + +9. Miscellaneous +---------------- + +This License represents the complete agreement concerning the subject +matter hereof. If any provision of this License is held to be +unenforceable, such provision shall be reformed only to the extent +necessary to make it enforceable. Any law or regulation which provides +that the language of a contract shall be construed against the drafter +shall not be used to construe this License against a Contributor. + +10. Versions of the License +--------------------------- + +10.1. New Versions + +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. + +10.2. Effect of New Versions + +You may distribute the Covered Software under the terms of the version +of the License under which You originally received the Covered Software, +or under the terms of any subsequent version published by the license +steward. + +10.3. Modified Versions + +If you create software not governed by this License, and you want to +create a new license for such software, you may create and use a +modified version of this License if you rename the license and remove +any references to the name of the license steward (except to note that +such modified license differs from this License). + +10.4. Distributing Source Code Form that is Incompatible With Secondary +Licenses + +If You choose to distribute Source Code Form that is Incompatible With +Secondary Licenses under the terms of this version of the License, the +notice described in Exhibit B of this License must be attached. + +Exhibit A - Source Code Form License Notice +------------------------------------------- + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at https://mozilla.org/MPL/2.0/. + +If it is not possible or desirable to put the notice in a particular +file, then You may include the notice in a location (such as a LICENSE +file in a relevant directory) where a recipient would be likely to look +for such a notice. + +You may add additional accurate notices of copyright ownership. + +Exhibit B - "Incompatible With Secondary Licenses" Notice +--------------------------------------------------------- + + This Source Code Form is "Incompatible With Secondary Licenses", as + defined by the Mozilla Public License, v. 2.0. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,109 @@ +-- Setup.hs + +import Control.Exception (bracket) +import Control.Monad (filterM, forM_) +import Data.List (nub) +import Data.Maybe (catMaybes, isJust, listToMaybe) +import Distribution.PackageDescription ( + GenericPackageDescription (..), + PackageDescription (..), + extraLibDirs, + libBuildInfo, + library, + package, + ) +import Distribution.Simple +import Distribution.Simple.Compiler (compilerInfo) +import Distribution.Simple.InstallDirs (absoluteInstallDirs, dynlibdir, libdir) +import Distribution.Simple.LocalBuildInfo (LocalBuildInfo (..), localUnitId) +import Distribution.Simple.Setup (configExtraLibDirs, configVerbosity, copyDest, defaultCopyFlags, fromFlag) +import Distribution.Simple.Utils (copyFileVerbose, createDirectoryIfMissingVerbose, createTempDirectory, info) +import Distribution.Verbosity (Verbosity) +import System.Directory ( + doesDirectoryExist, + doesFileExist, + findFile, + getCurrentDirectory, + getTemporaryDirectory, + removeDirectoryRecursive, + ) +import System.Environment (lookupEnv) +import System.FilePath ((), splitSearchPath) +import System.Process (callProcess) + +main :: IO () +main = + defaultMainWithHooks + simpleUserHooks + { preConf = \args flags -> do + ensureDuckDBAvailable (fromFlag (configVerbosity flags)) + preConf simpleUserHooks args flags + } + +systemLibraryCandidates :: [FilePath] +systemLibraryCandidates = + [ "libduckdb.so" + , "libduckdb.so.1" + , "libduckdb.so.1.4" + , "libduckdb.so.1.4.0" + , "libduckdb.so.1.4.1" + ] + + +ensureDuckDBAvailable :: Verbosity -> IO () +ensureDuckDBAvailable verb = do + available <- systemDuckDBAvailable + if available + then info verb "libduckdb found" + else error "libduckdb not found, please install libduckdb (available at https://duckdb.org/install/)" + + +systemDuckDBAvailable :: IO Bool +systemDuckDBAvailable = do + header <- findDuckDBHeader + lib <- findDuckDBLibrary + pure (isJust header && isJust lib) + +findDuckDBHeader :: IO (Maybe FilePath) +findDuckDBHeader = do + paths <- headerSearchPaths + findFile paths "duckdb.h" + +findDuckDBLibrary :: IO (Maybe FilePath) +findDuckDBLibrary = do + paths <- librarySearchPaths + listToMaybe . catMaybes <$> mapM (findFile paths) systemLibraryCandidates + +headerSearchPaths :: IO [FilePath] +headerSearchPaths = do + envPaths <- gatherEnvPaths ["C_INCLUDE_PATH", "CPATH", "INCLUDE"] + let defaults = + [ "/usr/include" + , "/usr/local/include" + , "/usr/include/x86_64-linux-gnu" + , "/usr/include/aarch64-linux-gnu" + , "/opt/homebrew/include" + , "/opt/local/include" + ] + pure (nub (envPaths ++ defaults)) + +librarySearchPaths :: IO [FilePath] +librarySearchPaths = do + envPaths <- gatherEnvPaths ["LIBRARY_PATH", "LD_LIBRARY_PATH", "DYLD_LIBRARY_PATH", "LIB"] + let defaults = + [ "/usr/lib" + , "/usr/local/lib" + , "/usr/lib64" + , "/usr/local/lib64" + , "/usr/lib/x86_64-linux-gnu" + , "/usr/lib/aarch64-linux-gnu" + , "/opt/homebrew/lib" + , "/opt/local/lib" + ] + pure (nub (envPaths ++ defaults)) + +gatherEnvPaths :: [String] -> IO [FilePath] +gatherEnvPaths names = do + vals <- mapM lookupEnv names + let paths = concatMap splitSearchPath (catMaybes vals) + pure (filter (not . null) paths) diff --git a/cbits/duckdb.h b/cbits/duckdb.h new file mode 100644 --- /dev/null +++ b/cbits/duckdb.h @@ -0,0 +1,5168 @@ +//===----------------------------------------------------------------------===// +// +// DuckDB +// +// duckdb.h +// +// +//===----------------------------------------------------------------------===// +// +// !!!!!!! +// WARNING: this file is autogenerated by scripts/generate_c_api.py, manual changes will be overwritten +// !!!!!!! + +#pragma once + +#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) +#define DUCKDB_C_API __declspec(dllexport) +#else +#define DUCKDB_C_API __declspec(dllimport) +#endif +#endif +#else +#define DUCKDB_C_API +#endif +#endif + +//! duplicate of duckdb/main/winapi.hpp +#ifndef DUCKDB_EXTENSION_API +#ifdef _WIN32 +#ifdef DUCKDB_STATIC_BUILD +#define DUCKDB_EXTENSION_API +#else +#define DUCKDB_EXTENSION_API __declspec(dllexport) +#endif +#else +#define DUCKDB_EXTENSION_API __attribute__((visibility("default"))) +#endif +#endif + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +//===--------------------------------------------------------------------===// +// Enums +//===--------------------------------------------------------------------===// + +//! 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 + +//! An enum over DuckDB's internal types. +typedef enum DUCKDB_TYPE { + DUCKDB_TYPE_INVALID = 0, + // bool + DUCKDB_TYPE_BOOLEAN = 1, + // int8_t + DUCKDB_TYPE_TINYINT = 2, + // int16_t + DUCKDB_TYPE_SMALLINT = 3, + // int32_t + DUCKDB_TYPE_INTEGER = 4, + // int64_t + DUCKDB_TYPE_BIGINT = 5, + // uint8_t + DUCKDB_TYPE_UTINYINT = 6, + // uint16_t + DUCKDB_TYPE_USMALLINT = 7, + // uint32_t + DUCKDB_TYPE_UINTEGER = 8, + // uint64_t + DUCKDB_TYPE_UBIGINT = 9, + // float + DUCKDB_TYPE_FLOAT = 10, + // double + DUCKDB_TYPE_DOUBLE = 11, + // duckdb_timestamp (microseconds) + DUCKDB_TYPE_TIMESTAMP = 12, + // duckdb_date + DUCKDB_TYPE_DATE = 13, + // duckdb_time + DUCKDB_TYPE_TIME = 14, + // duckdb_interval + DUCKDB_TYPE_INTERVAL = 15, + // duckdb_hugeint + DUCKDB_TYPE_HUGEINT = 16, + // duckdb_uhugeint + DUCKDB_TYPE_UHUGEINT = 32, + // const char* + DUCKDB_TYPE_VARCHAR = 17, + // duckdb_blob + DUCKDB_TYPE_BLOB = 18, + // duckdb_decimal + DUCKDB_TYPE_DECIMAL = 19, + // duckdb_timestamp_s (seconds) + DUCKDB_TYPE_TIMESTAMP_S = 20, + // duckdb_timestamp_ms (milliseconds) + DUCKDB_TYPE_TIMESTAMP_MS = 21, + // duckdb_timestamp_ns (nanoseconds) + DUCKDB_TYPE_TIMESTAMP_NS = 22, + // enum type, only useful as logical type + DUCKDB_TYPE_ENUM = 23, + // list type, only useful as logical type + DUCKDB_TYPE_LIST = 24, + // struct type, only useful as logical type + DUCKDB_TYPE_STRUCT = 25, + // 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_TYPE_UUID = 27, + // union type, only useful as logical type + DUCKDB_TYPE_UNION = 28, + // duckdb_bit + DUCKDB_TYPE_BIT = 29, + // duckdb_time_tz + DUCKDB_TYPE_TIME_TZ = 30, + // duckdb_timestamp (microseconds) + DUCKDB_TYPE_TIMESTAMP_TZ = 31, + // enum type, only useful as logical type + DUCKDB_TYPE_ANY = 34, + // duckdb_bignum + DUCKDB_TYPE_BIGNUM = 35, + // enum type, only useful as logical type + DUCKDB_TYPE_SQLNULL = 36, + // enum type, only useful as logical type + DUCKDB_TYPE_STRING_LITERAL = 37, + // enum type, only useful as logical type + DUCKDB_TYPE_INTEGER_LITERAL = 38, + // duckdb_time_ns (nanoseconds) + DUCKDB_TYPE_TIME_NS = 39, +} duckdb_type; + +//! An enum over the returned state of different functions. +typedef enum duckdb_state { DuckDBSuccess = 0, DuckDBError = 1 } duckdb_state; + +//! An enum over the pending state of a pending query result. +typedef enum duckdb_pending_state { + DUCKDB_PENDING_RESULT_READY = 0, + DUCKDB_PENDING_RESULT_NOT_READY = 1, + DUCKDB_PENDING_ERROR = 2, + DUCKDB_PENDING_NO_TASKS_AVAILABLE = 3 +} duckdb_pending_state; + +//! An enum over DuckDB's different result types. +typedef enum duckdb_result_type { + DUCKDB_RESULT_TYPE_INVALID = 0, + DUCKDB_RESULT_TYPE_CHANGED_ROWS = 1, + DUCKDB_RESULT_TYPE_NOTHING = 2, + DUCKDB_RESULT_TYPE_QUERY_RESULT = 3, +} duckdb_result_type; + +//! An enum over DuckDB's different statement types. +typedef enum duckdb_statement_type { + DUCKDB_STATEMENT_TYPE_INVALID = 0, + DUCKDB_STATEMENT_TYPE_SELECT = 1, + DUCKDB_STATEMENT_TYPE_INSERT = 2, + DUCKDB_STATEMENT_TYPE_UPDATE = 3, + DUCKDB_STATEMENT_TYPE_EXPLAIN = 4, + DUCKDB_STATEMENT_TYPE_DELETE = 5, + DUCKDB_STATEMENT_TYPE_PREPARE = 6, + DUCKDB_STATEMENT_TYPE_CREATE = 7, + DUCKDB_STATEMENT_TYPE_EXECUTE = 8, + DUCKDB_STATEMENT_TYPE_ALTER = 9, + DUCKDB_STATEMENT_TYPE_TRANSACTION = 10, + DUCKDB_STATEMENT_TYPE_COPY = 11, + DUCKDB_STATEMENT_TYPE_ANALYZE = 12, + DUCKDB_STATEMENT_TYPE_VARIABLE_SET = 13, + DUCKDB_STATEMENT_TYPE_CREATE_FUNC = 14, + DUCKDB_STATEMENT_TYPE_DROP = 15, + DUCKDB_STATEMENT_TYPE_EXPORT = 16, + DUCKDB_STATEMENT_TYPE_PRAGMA = 17, + DUCKDB_STATEMENT_TYPE_VACUUM = 18, + DUCKDB_STATEMENT_TYPE_CALL = 19, + DUCKDB_STATEMENT_TYPE_SET = 20, + DUCKDB_STATEMENT_TYPE_LOAD = 21, + DUCKDB_STATEMENT_TYPE_RELATION = 22, + DUCKDB_STATEMENT_TYPE_EXTENSION = 23, + DUCKDB_STATEMENT_TYPE_LOGICAL_PLAN = 24, + DUCKDB_STATEMENT_TYPE_ATTACH = 25, + DUCKDB_STATEMENT_TYPE_DETACH = 26, + DUCKDB_STATEMENT_TYPE_MULTI = 27, +} duckdb_statement_type; + +//! An enum over DuckDB's different error types. +typedef enum duckdb_error_type { + DUCKDB_ERROR_INVALID = 0, + DUCKDB_ERROR_OUT_OF_RANGE = 1, + DUCKDB_ERROR_CONVERSION = 2, + DUCKDB_ERROR_UNKNOWN_TYPE = 3, + DUCKDB_ERROR_DECIMAL = 4, + DUCKDB_ERROR_MISMATCH_TYPE = 5, + DUCKDB_ERROR_DIVIDE_BY_ZERO = 6, + DUCKDB_ERROR_OBJECT_SIZE = 7, + DUCKDB_ERROR_INVALID_TYPE = 8, + DUCKDB_ERROR_SERIALIZATION = 9, + DUCKDB_ERROR_TRANSACTION = 10, + DUCKDB_ERROR_NOT_IMPLEMENTED = 11, + DUCKDB_ERROR_EXPRESSION = 12, + DUCKDB_ERROR_CATALOG = 13, + DUCKDB_ERROR_PARSER = 14, + DUCKDB_ERROR_PLANNER = 15, + DUCKDB_ERROR_SCHEDULER = 16, + DUCKDB_ERROR_EXECUTOR = 17, + DUCKDB_ERROR_CONSTRAINT = 18, + DUCKDB_ERROR_INDEX = 19, + DUCKDB_ERROR_STAT = 20, + DUCKDB_ERROR_CONNECTION = 21, + DUCKDB_ERROR_SYNTAX = 22, + DUCKDB_ERROR_SETTINGS = 23, + DUCKDB_ERROR_BINDER = 24, + DUCKDB_ERROR_NETWORK = 25, + DUCKDB_ERROR_OPTIMIZER = 26, + DUCKDB_ERROR_NULL_POINTER = 27, + DUCKDB_ERROR_IO = 28, + DUCKDB_ERROR_INTERRUPT = 29, + DUCKDB_ERROR_FATAL = 30, + DUCKDB_ERROR_INTERNAL = 31, + DUCKDB_ERROR_INVALID_INPUT = 32, + DUCKDB_ERROR_OUT_OF_MEMORY = 33, + DUCKDB_ERROR_PERMISSION = 34, + DUCKDB_ERROR_PARAMETER_NOT_RESOLVED = 35, + DUCKDB_ERROR_PARAMETER_NOT_ALLOWED = 36, + DUCKDB_ERROR_DEPENDENCY = 37, + DUCKDB_ERROR_HTTP = 38, + DUCKDB_ERROR_MISSING_EXTENSION = 39, + DUCKDB_ERROR_AUTOLOAD = 40, + DUCKDB_ERROR_SEQUENCE = 41, + DUCKDB_INVALID_CONFIGURATION = 42 +} duckdb_error_type; + +//! An enum over DuckDB's different cast modes. +typedef enum duckdb_cast_mode { DUCKDB_CAST_NORMAL = 0, DUCKDB_CAST_TRY = 1 } duckdb_cast_mode; + +//===--------------------------------------------------------------------===// +// General type definitions +//===--------------------------------------------------------------------===// + +//! DuckDB's index type. +typedef uint64_t idx_t; + +//! Type definition for the data pointers of selection vectors. +typedef uint32_t sel_t; + +//! 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); + +//! The callback to copy data, e.g., bind data (if any). +typedef void *(*duckdb_copy_callback_t)(void *data); + +//! Used for threading, contains a task state. +//! Must be destroyed with `duckdb_destroy_task_state`. +typedef void *duckdb_task_state; + +//===--------------------------------------------------------------------===// +// Types (no explicit freeing) +//===--------------------------------------------------------------------===// + +//! 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 { + int32_t days; +} duckdb_date; + +typedef 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 { + int64_t micros; +} duckdb_time; + +typedef 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 { + 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 { + uint64_t bits; +} duckdb_time_tz; + +typedef 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 { + int64_t micros; +} duckdb_timestamp; + +typedef struct { + duckdb_date_struct date; + duckdb_time_struct time; +} duckdb_timestamp_struct; + +//! TIMESTAMP_S is stored as seconds since 1970-01-01. +typedef struct { + int64_t seconds; +} duckdb_timestamp_s; + +//! TIMESTAMP_MS is stored as milliseconds since 1970-01-01. +typedef struct { + int64_t millis; +} duckdb_timestamp_ms; + +//! TIMESTAMP_NS is stored as nanoseconds since 1970-01-01. +typedef struct { + int64_t nanos; +} duckdb_timestamp_ns; + +//! INTERVAL is stored in months, days, and micros. +typedef struct { + 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 { + 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 { + 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 { + uint8_t width; + uint8_t scale; + duckdb_hugeint value; +} duckdb_decimal; + +//! A type holding information about the query execution progress. +typedef struct { + 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 { + 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`. + 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 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 { + 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 { + 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 { + 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`. + 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; + +//! A database instance cache object. Must be destroyed with `duckdb_destroy_instance_cache`. +typedef struct _duckdb_instance_cache { + void *internal_ptr; +} * duckdb_instance_cache; + +//! A database object. Must be closed with `duckdb_close`. +typedef struct _duckdb_database { + void *internal_ptr; +} * duckdb_database; + +//! A connection to a duckdb database. Must be closed with `duckdb_disconnect`. +typedef struct _duckdb_connection { + void *internal_ptr; +} * duckdb_connection; + +//! A client context of a duckdb connection. Must be destroyed with `duckdb_destroy_context`. +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`. +typedef struct _duckdb_prepared_statement { + void *internal_ptr; +} * duckdb_prepared_statement; + +//! Extracted statements. Must be destroyed with `duckdb_destroy_extracted`. +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`. +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`. +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`. +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`. +typedef struct _duckdb_config { + void *internal_ptr; +} * duckdb_config; + +//! A logical type. +//! Must be destroyed with `duckdb_destroy_logical_type`. +typedef struct _duckdb_logical_type { + void *internal_ptr; +} * duckdb_logical_type; + +//! Holds extra information to register a custom logical type. +//! Reserved for future use. +typedef struct _duckdb_create_type_info { + void *internal_ptr; +} * duckdb_create_type_info; + +//! Contains a data chunk of a duckdb_result. +//! Must be destroyed with `duckdb_destroy_data_chunk`. +typedef struct _duckdb_data_chunk { + void *internal_ptr; +} * duckdb_data_chunk; + +//! A value of a logical type. +//! Must be destroyed with `duckdb_destroy_value`. +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. +typedef struct _duckdb_profiling_info { + void *internal_ptr; +} * duckdb_profiling_info; + +//! Holds error data. +//! Must be destroyed with `duckdb_destroy_error_data`. +typedef struct _duckdb_error_data { + void *internal_ptr; +} * duckdb_error_data; + +//! Holds a bound expression. +//! Must be destroyed with `duckdb_destroy_expression`. +typedef struct _duckdb_expression { + void *internal_ptr; +} * duckdb_expression; + +//===--------------------------------------------------------------------===// +// C API extension information +//===--------------------------------------------------------------------===// + +//! Holds the state of the C API extension initialization process. +typedef struct _duckdb_extension_info { + void *internal_ptr; +} * duckdb_extension_info; + +//===--------------------------------------------------------------------===// +// Function types +//===--------------------------------------------------------------------===// + +//! Additional function info. +//! When setting this info, it is necessary to pass a destroy-callback function. +typedef struct _duckdb_function_info { + void *internal_ptr; +} * duckdb_function_info; + +//! The bind info of a function. +//! When setting this info, it is necessary to pass a destroy-callback function. +typedef struct _duckdb_bind_info { + void *internal_ptr; +} * duckdb_bind_info; + +//===--------------------------------------------------------------------===// +// Scalar function types +//===--------------------------------------------------------------------===// + +//! A scalar function. Must be destroyed with `duckdb_destroy_scalar_function`. +typedef struct _duckdb_scalar_function { + void *internal_ptr; +} * duckdb_scalar_function; + +//! A scalar function set. Must be destroyed with `duckdb_destroy_scalar_function_set`. +typedef struct _duckdb_scalar_function_set { + void *internal_ptr; +} * duckdb_scalar_function_set; + +//! The bind function callback of the scalar function. +typedef void (*duckdb_scalar_function_bind_t)(duckdb_bind_info info); + +//! 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); + +//===--------------------------------------------------------------------===// +// Aggregate function types +//===--------------------------------------------------------------------===// + +//! An aggregate function. Must be destroyed with `duckdb_destroy_aggregate_function`. +typedef struct _duckdb_aggregate_function { + void *internal_ptr; +} * duckdb_aggregate_function; + +//! A aggregate function set. Must be destroyed with `duckdb_destroy_aggregate_function_set`. +typedef struct _duckdb_aggregate_function_set { + void *internal_ptr; +} * duckdb_aggregate_function_set; + +//! The state of an aggregate function. +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`. +typedef struct _duckdb_table_function { + void *internal_ptr; +} * duckdb_table_function; + +//! Additional function initialization info. +//! When setting this info, it is necessary to pass a destroy-callback function. +typedef struct _duckdb_init_info { + void *internal_ptr; +} * duckdb_init_info; + +//! The bind function of the table function. +typedef void (*duckdb_table_function_bind_t)(duckdb_bind_info info); + +//! 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); + +//===--------------------------------------------------------------------===// +// 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. +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 { + void *internal_ptr; +} * duckdb_arrow; + +//! Holds an arrow array stream. Must be destroyed with `duckdb_destroy_arrow_stream`. +typedef struct _duckdb_arrow_stream { + void *internal_ptr; +} * duckdb_arrow_stream; + +//! Holds an arrow schema. Remember to release the respective ArrowSchema object. +typedef struct _duckdb_arrow_schema { + void *internal_ptr; +} * duckdb_arrow_schema; + +//! 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 { + void *internal_ptr; +} * duckdb_arrow_converted_schema; + +//! Holds an arrow array. Remember to release the respective ArrowSchema object. +typedef struct _duckdb_arrow_array { + void *internal_ptr; +} * duckdb_arrow_array; + +//! 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; + +//===--------------------------------------------------------------------===// +// 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 +//===--------------------------------------------------------------------===// + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +Interrupt running query + +* @param connection The connection to interrupt +*/ +DUCKDB_C_API void duckdb_interrupt(duckdb_connection connection); + +/*! +Get progress of the running query + +* @param connection The working connection +* @return -1 if no progress or a percentage of the progress +*/ +DUCKDB_C_API duckdb_query_progress_type duckdb_query_progress(duckdb_connection connection); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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. +*/ +DUCKDB_C_API const char *duckdb_library_version(); + +/*! +Get the list of (fully qualified) table names of the query. + +* @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); + +//===--------------------------------------------------------------------===// +// Configuration +//===--------------------------------------------------------------------===// + +/*! +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`. + +* @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); + +/*! +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(); + +/*! +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); + +/*! +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); + +/*! +Destroys the specified configuration object and de-allocates all memory allocated for the object. + +* @param config The configuration object to destroy. +*/ +DUCKDB_C_API void duckdb_destroy_config(duckdb_config *config); + +//===--------------------------------------------------------------------===// +// Error Data +//===--------------------------------------------------------------------===// + +// Functions that can throw DuckDB errors must return duckdb_error_data. +// Please use this interface for all new functions, as it deprecates all previous error handling approaches. + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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 +//===--------------------------------------------------------------------===// + +/*! +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. + +* @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); + +/*! +Closes the result and de-allocates all memory allocated for that result. + +* @param result The result to destroy. +*/ +DUCKDB_C_API void duckdb_destroy_result(duckdb_result *result); + +/*! +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. + +Returns `NULL` if the column is out of range. + +* @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); + +/*! +Returns the column type of the specified column. + +Returns `DUCKDB_TYPE_INVALID` if the column is out of range. + +* @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); + +/*! +Returns the statement type of the statement that was executed + +* @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); + +/*! +Returns the logical column type of the specified column. + +The return type of this call should be destroyed with `duckdb_destroy_logical_type`. + +Returns `NULL` if the column is out of range. + +* @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); + +/*! +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); + +/*! +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); + +#ifndef DUCKDB_API_NO_DEPRECATED +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +Returns the number of rows present in the result object. + +* @param result The result object. +* @return The number of rows present in the result object. +*/ +DUCKDB_C_API idx_t duckdb_row_count(duckdb_result *result); + +#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. + +* @param result The result object. +* @return The number of rows changed. +*/ +DUCKDB_C_API idx_t duckdb_rows_changed(duckdb_result *result); + +#ifndef DUCKDB_API_NO_DEPRECATED +/*! +**DEPRECATED**: Prefer using `duckdb_result_get_chunk` instead. + +Returns the data of a specific column of a result in columnar format. + +The function returns a dense array which contains the result data. The exact type stored in the array depends on the +corresponding duckdb_type (as provided by `duckdb_column_type`). For the exact type by which the data should be +accessed, see the comments in [the types section](types) or the `DUCKDB_TYPE` enum. + +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]); +``` + +* @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); + +/*! +**DEPRECATED**: Prefer using `duckdb_result_get_chunk` instead. + +Returns the nullmask of a specific column of a result in columnar format. The nullmask indicates for every row +whether or not the corresponding row is `NULL`. If a row is `NULL`, the values present in the array provided +by `duckdb_column_data` are undefined. + +```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]); +} +``` + +* @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); + +#endif + +/*! +Returns the error message contained within the result. The error is only set if `duckdb_query` returns `DuckDBError`. + +The result of this function must not be freed. It will be cleaned up when `duckdb_destroy_result` is called. + +* @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); + +/*! +Returns the result error type contained within the result. The error is only set if `duckdb_query` returns +`DuckDBError`. + +* @param result The result object to fetch the error from. +* @return The error type of the result. +*/ +DUCKDB_C_API duckdb_error_type duckdb_result_error_type(duckdb_result *result); + +//===--------------------------------------------------------------------===// +// Result Functions +//===--------------------------------------------------------------------===// + +#ifndef DUCKDB_API_NO_DEPRECATED +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +Fetches a data chunk from the duckdb_result. This function should be called repeatedly until the result is exhausted. + +The result must be destroyed with `duckdb_destroy_data_chunk`. + +This function supersedes all `duckdb_value` functions, as well as the `duckdb_column_data` and `duckdb_nullmask_data` +functions. It results in significantly better performance, and should be preferred in newer code-bases. + +If this function is used, none of the other result functions can be used and vice versa (i.e. this function cannot be +mixed with the legacy result functions). + +Use `duckdb_result_chunk_count` to figure out how many chunks there are in the result. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +Checks if the type of the internal result is StreamQueryResult. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +Returns the number of data chunks present in the result. + +* @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); + +#endif + +/*! +Returns the return_type of the given result, or DUCKDB_RETURN_TYPE_INVALID on error + +* @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 +//===--------------------------------------------------------------------===// + +// These functions will perform conversions if necessary. +// On failure (e.g. if conversion cannot be performed or if the value is NULL) a default value is returned. +// Note that these functions are slow since they perform bounds checking and conversion +// For fast access of values prefer using `duckdb_result_get_chunk` +#ifndef DUCKDB_API_NO_DEPRECATED +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATED**: Use duckdb_value_string instead. This function does not work correctly if the string contains null +bytes. + +* @return The text value at the specified location as a null-terminated string, or nullptr if the value cannot be +converted. The result must be freed with `duckdb_free`. +*/ +DUCKDB_C_API char *duckdb_value_varchar(duckdb_result *result, idx_t col, idx_t row); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +No support for nested types, and for other complex types. +The resulting field "string.data" must be freed with `duckdb_free.` + +* @return The string value at the specified location. Attempts to cast the result value to string. +*/ +DUCKDB_C_API duckdb_string duckdb_value_string(duckdb_result *result, idx_t col, idx_t row); + +/*! +**DEPRECATED**: Use duckdb_value_string_internal instead. This function does not work correctly if the string contains +null bytes. + +* @return The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast. +If the column is NOT a VARCHAR column this function will return NULL. + +The result must NOT be freed. +*/ +DUCKDB_C_API char *duckdb_value_varchar_internal(duckdb_result *result, idx_t col, idx_t row); + +/*! +**DEPRECATED**: Use duckdb_value_string_internal instead. This function does not work correctly if the string contains +null bytes. +* @return The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast. +If the column is NOT a VARCHAR column this function will return NULL. + +The result must NOT be freed. +*/ +DUCKDB_C_API duckdb_string duckdb_value_string_internal(duckdb_result *result, idx_t col, idx_t row); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +/*! +**DEPRECATION NOTICE**: This method is scheduled for removal in a future release. + +* @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); + +#endif + +//===--------------------------------------------------------------------===// +// Helpers +//===--------------------------------------------------------------------===// + +/*! +Allocate `size` bytes of memory using the duckdb internal malloc function. Any memory allocated in this manner +should be freed using `duckdb_free`. + +* @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); + +/*! +Free a value returned from `duckdb_malloc`, `duckdb_value_varchar`, `duckdb_value_blob`, or +`duckdb_value_string`. + +* @param ptr The memory region to de-allocate. +*/ +DUCKDB_C_API void duckdb_free(void *ptr); + +/*! +The internal vector size used by DuckDB. +This is the amount of tuples that will fit into a data chunk created by `duckdb_create_data_chunk`. + +* @return The vector size. +*/ +DUCKDB_C_API idx_t duckdb_vector_size(); + +/*! +Whether or not the duckdb_string_t value is inlined. +This means that the data of the string does not have a separate allocation. + +*/ +DUCKDB_C_API bool duckdb_string_is_inlined(duckdb_string_t string); + +/*! +Get the string length of a string_t + +* @param string The string to get the length of. +* @return The length. +*/ +DUCKDB_C_API uint32_t duckdb_string_t_length(duckdb_string_t string); + +/*! +Get a pointer to the string data of a string_t + +* @param string The string to get the pointer to. +* @return The pointer. +*/ +DUCKDB_C_API const char *duckdb_string_t_data(duckdb_string_t *string); + +//===--------------------------------------------------------------------===// +// Date Time Timestamp Helpers +//===--------------------------------------------------------------------===// + +/*! +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); + +/*! +Re-compose a `duckdb_date` from year, month and date (`duckdb_date_struct`). + +* @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); + +/*! +Test a `duckdb_date` to see if it is a finite value. + +* @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); + +/*! +Decompose a `duckdb_time` object into hour, minute, second and microsecond (stored as `duckdb_time_struct`). + +* @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); + +/*! +Create a `duckdb_time_tz` object from micros and a timezone offset. + +* @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); + +/*! +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. + +* @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); + +/*! +Re-compose a `duckdb_time` from hour, minute, second and microsecond (`duckdb_time_struct`). + +* @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); + +/*! +Decompose a `duckdb_timestamp` object into a `duckdb_timestamp_struct`. + +* @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); + +/*! +Re-compose a `duckdb_timestamp` from a duckdb_timestamp_struct. + +* @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); + +/*! +Test a `duckdb_timestamp` to see if it is a finite value. + +* @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); + +/*! +Test a `duckdb_timestamp_s` to see if it is a finite value. + +* @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); + +/*! +Test a `duckdb_timestamp_ms` to see if it is a finite value. + +* @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); + +/*! +Test a `duckdb_timestamp_ns` to see if it is a finite value. + +* @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); + +//===--------------------------------------------------------------------===// +// Hugeint Helpers +//===--------------------------------------------------------------------===// + +/*! +Converts a duckdb_hugeint object (as obtained from a `DUCKDB_TYPE_HUGEINT` column) into a double. + +* @param val The hugeint value. +* @return The converted `double` element. +*/ +DUCKDB_C_API double duckdb_hugeint_to_double(duckdb_hugeint val); + +/*! +Converts a double value to a duckdb_hugeint object. + +If the conversion fails because the double value is too big the result will be 0. + +* @param val The double value. +* @return The converted `duckdb_hugeint` element. +*/ +DUCKDB_C_API duckdb_hugeint duckdb_double_to_hugeint(double val); + +//===--------------------------------------------------------------------===// +// Unsigned Hugeint Helpers +//===--------------------------------------------------------------------===// + +/*! +Converts a duckdb_uhugeint object (as obtained from a `DUCKDB_TYPE_UHUGEINT` column) into a double. + +* @param val The uhugeint value. +* @return The converted `double` element. +*/ +DUCKDB_C_API double duckdb_uhugeint_to_double(duckdb_uhugeint val); + +/*! +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. + +* @param val The double value. +* @return The converted `duckdb_uhugeint` element. +*/ +DUCKDB_C_API duckdb_uhugeint duckdb_double_to_uhugeint(double val); + +//===--------------------------------------------------------------------===// +// Decimal Helpers +//===--------------------------------------------------------------------===// + +/*! +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. + +* @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); + +/*! +Converts a duckdb_decimal object (as obtained from a `DUCKDB_TYPE_DECIMAL` column) into a double. + +* @param val The decimal value. +* @return The converted `double` element. +*/ +DUCKDB_C_API double duckdb_decimal_to_double(duckdb_decimal val); + +//===--------------------------------------------------------------------===// +// Prepared Statements +//===--------------------------------------------------------------------===// + +// A prepared statement is a parameterized query that allows you to bind parameters to it. +// * This is useful to easily supply parameters to functions and avoid SQL injection attacks. +// * This is useful to speed up queries that you will execute several times with different parameters. +// Because the query will only be parsed, bound, optimized and planned once during the prepare stage, +// rather than once per execution. +// For example: +// SELECT * FROM tbl WHERE id=? +// Or a query with multiple parameters: +// SELECT * FROM tbl WHERE id=$1 OR name=$2 +/*! +Create a prepared statement object from a query. + +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. + +* @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); + +/*! +Closes the prepared statement and de-allocates all memory allocated for the statement. + +* @param prepared_statement The prepared statement to destroy. +*/ +DUCKDB_C_API void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement); + +/*! +Returns the error message associated with the given prepared statement. +If the prepared statement has no error message, this returns `nullptr` instead. + +The error message should not be freed. It will be de-allocated when `duckdb_destroy_prepare` is called. + +* @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); + +/*! +Returns the number of parameters that can be provided to the given prepared statement. + +Returns 0 if the query was not successfully prepared. + +* @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); + +/*! +Returns the name used to identify the parameter +The returned string should be freed using `duckdb_free`. + +Returns NULL if the index is out of range for the provided prepared statement. + +* @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); + +/*! +Returns the parameter type for the parameter at the given index. + +Returns `DUCKDB_TYPE_INVALID` if the parameter index is out of range or the statement was not successfully prepared. + +* @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); + +/*! +Returns the logical type for the parameter at the given index. + +Returns `nullptr` if the parameter index is out of range or the statement was not successfully prepared. + +The return type of this call should be destroyed with `duckdb_destroy_logical_type`. + +* @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); + +/*! +Clear the params bind to the prepared statement. +*/ +DUCKDB_C_API duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement); + +/*! +Returns the statement type of the statement to be executed + +* @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); + +/*! +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. + +* @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); + +/*! +Returns the name of the specified column of the result of the prepared_statement. +The returned string should be freed using `duckdb_free`. + +Returns `nullptr` if the column is out of range. + +* @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); + +/*! +Returns the column type of the specified column of the result of the prepared_statement. + +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`. + +* @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); + +/*! +Returns the column type of the specified column of the result of the prepared_statement. + +Returns `DUCKDB_TYPE_INVALID` if the column is out of range. + +* @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); + +//===--------------------------------------------------------------------===// +// Bind Values to Prepared Statements +//===--------------------------------------------------------------------===// + +/*! +Binds a value to the prepared statement at the specified index. +*/ +DUCKDB_C_API duckdb_state duckdb_bind_value(duckdb_prepared_statement prepared_statement, idx_t param_idx, + duckdb_value val); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +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); + +/*! +Binds a null-terminated varchar value to the prepared statement at the specified index. +*/ +DUCKDB_C_API duckdb_state duckdb_bind_varchar(duckdb_prepared_statement prepared_statement, idx_t param_idx, + const char *val); + +/*! +Binds a varchar value to the prepared statement at the specified index. +*/ +DUCKDB_C_API duckdb_state duckdb_bind_varchar_length(duckdb_prepared_statement prepared_statement, idx_t param_idx, + const char *val, idx_t length); + +/*! +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); + +/*! +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 +//===--------------------------------------------------------------------===// + +/*! +Executes the prepared statement with the given bound parameters, and returns a materialized query result. + +This method can be called multiple times for each prepared statement, and the parameters can be modified +between calls to this function. + +Note that the result must be freed with `duckdb_destroy_result`. + +* @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); + +#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 an optionally-streaming query result. +To determine if the resulting query was in fact streamed, use `duckdb_result_is_streaming` + +This method can be called multiple times for each prepared statement, and the parameters can be modified +between calls to this function. + +Note that the result must be freed with `duckdb_destroy_result`. + +* @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); + +#endif + +//===--------------------------------------------------------------------===// +// Extract Statements +//===--------------------------------------------------------------------===// + +// A query string can be extracted into multiple SQL statements. Each statement can be prepared and executed separately. +/*! +Extract all statements from a query. +Note that after calling `duckdb_extract_statements`, the extracted statements should always be destroyed using +`duckdb_destroy_extracted`, even if no statements were extracted. + +If the extract fails, `duckdb_extract_statements_error` can be called to obtain the reason why the extract failed. + +* @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); + +/*! +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. + +If the prepare fails, `duckdb_prepare_error` can be called to obtain the reason why the prepare failed. + +* @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); + +/*! +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. + +* @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); + +/*! +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); + +//===--------------------------------------------------------------------===// +// Pending Result Interface +//===--------------------------------------------------------------------===// + +/*! +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. + +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. + +* @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); + +#endif + +/*! +Closes the pending result and de-allocates all memory allocated for the result. + +* @param pending_result The pending result to destroy. +*/ +DUCKDB_C_API void duckdb_destroy_pending(duckdb_pending_result *pending_result); + +/*! +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. + +* @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); + +/*! +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. + +* @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); + +/*! +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. + +* @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); + +/*! +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`. + +* @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); + +/*! +Returns whether a duckdb_pending_state is finished executing. For example if `pending_state` is +DUCKDB_PENDING_RESULT_READY, this function will return true. + +* @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); + +//===--------------------------------------------------------------------===// +// Value Interface +//===--------------------------------------------------------------------===// + +/*! +Destroys the value and de-allocates all memory allocated for that type. + +* @param value The value to destroy. +*/ +DUCKDB_C_API void duckdb_destroy_value(duckdb_value *value); + +/*! +Creates a value from a null-terminated string + +* @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); + +/*! +Creates a value from a string + +* @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); + +/*! +Creates a value from a boolean + +* @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); + +/*! +Creates a value from an int8_t (a tinyint) + +* @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); + +/*! +Creates a value from a uint8_t (a utinyint) + +* @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); + +/*! +Creates a value from an int16_t (a smallint) + +* @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); + +/*! +Creates a value from a uint16_t (a usmallint) + +* @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); + +/*! +Creates a value from an int32_t (an integer) + +* @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); + +/*! +Creates a value from a uint32_t (a uinteger) + +* @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); + +/*! +Creates a value from a uint64_t (a ubigint) + +* @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); + +/*! +Creates a value from an int64 + +* @return The value. This must be destroyed with `duckdb_destroy_value`. +*/ +DUCKDB_C_API duckdb_value duckdb_create_int64(int64_t val); + +/*! +Creates a value from a hugeint + +* @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); + +/*! +Creates a value from a uhugeint + +* @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); + +/*! +Creates a BIGNUM value from a duckdb_bignum + +* @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); + +/*! +Creates a DECIMAL value from a duckdb_decimal + +* @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); + +/*! +Creates a value from a float + +* @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); + +/*! +Creates a value from a double + +* @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); + +/*! +Creates a value from a date + +* @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); + +/*! +Creates a value from a time + +* @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); + +/*! +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 value from a time_tz. +Not to be confused with `duckdb_create_time_tz`, which creates a duckdb_time_tz_t. + +* @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); + +/*! +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 TIMESTAMP_TZ 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_tz(duckdb_timestamp input); + +/*! +Creates a TIMESTAMP_S value from a duckdb_timestamp_s + +* @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); + +/*! +Creates a TIMESTAMP_MS value from a duckdb_timestamp_ms + +* @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); + +/*! +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); + +/*! +Creates a value from an interval + +* @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); + +/*! +Creates a value from a blob + +* @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); + +/*! +Creates a BIT value from a duckdb_bit + +* @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); + +/*! +Creates a UUID value from a uhugeint + +* @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); + +/*! +Returns the boolean value of the given value. + +* @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); + +/*! +Returns the int8_t value of the given value. + +* @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); + +/*! +Returns the uint8_t value of the given value. + +* @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); + +/*! +Returns the int16_t value of the given value. + +* @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); + +/*! +Returns the uint16_t value of the given value. + +* @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); + +/*! +Returns the int32_t value of the given value. + +* @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); + +/*! +Returns the uint32_t value of the given value. + +* @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); + +/*! +Returns the int64_t value of the given value. + +* @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); + +/*! +Returns the uint64_t value of the given value. + +* @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); + +/*! +Returns the hugeint value of the given value. + +* @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); + +/*! +Returns the uhugeint value of the given value. + +* @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); + +/*! +Returns the duckdb_bignum value of the given value. +The `data` field must be destroyed with `duckdb_free`. + +* @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); + +/*! +Returns the duckdb_decimal value of the given value. + +* @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); + +/*! +Returns the float value of the given value. + +* @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); + +/*! +Returns the double value of the given value. + +* @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); + +/*! +Returns the date value of the given value. + +* @param val A duckdb_value containing a date +* @return A duckdb_date, or MinValue if the value cannot be converted +*/ +DUCKDB_C_API duckdb_date duckdb_get_date(duckdb_value val); + +/*! +Returns the time value of the given value. + +* @param val A duckdb_value containing a time +* @return A duckdb_time, or MinValue