1//===----------------------------------------------------------------------===//
2//
3// DuckDB
4//
5// duckdb.h
6//
7//
8//===----------------------------------------------------------------------===//
9
10#pragma once
11
12// duplicate of duckdb/main/winapi.hpp
13#ifndef DUCKDB_API
14#ifdef _WIN32
15#if defined(DUCKDB_BUILD_LIBRARY) && !defined(DUCKDB_BUILD_LOADABLE_EXTENSION)
16#define DUCKDB_API __declspec(dllexport)
17#else
18#define DUCKDB_API __declspec(dllimport)
19#endif
20#else
21#define DUCKDB_API
22#endif
23#endif
24
25// duplicate of duckdb/main/winapi.hpp
26#ifndef DUCKDB_EXTENSION_API
27#ifdef _WIN32
28#ifdef DUCKDB_BUILD_LOADABLE_EXTENSION
29#define DUCKDB_EXTENSION_API __declspec(dllexport)
30#else
31#define DUCKDB_EXTENSION_API
32#endif
33#else
34#define DUCKDB_EXTENSION_API __attribute__((visibility("default")))
35#endif
36#endif
37
38// API versions
39// if no explicit API version is defined, the latest API version is used
40// Note that using older API versions (i.e. not using DUCKDB_API_LATEST) is deprecated.
41// These will not be supported long-term, and will be removed in future versions.
42#ifndef DUCKDB_API_0_3_1
43#define DUCKDB_API_0_3_1 1
44#endif
45#ifndef DUCKDB_API_0_3_2
46#define DUCKDB_API_0_3_2 2
47#endif
48#ifndef DUCKDB_API_LATEST
49#define DUCKDB_API_LATEST DUCKDB_API_0_3_2
50#endif
51
52#ifndef DUCKDB_API_VERSION
53#define DUCKDB_API_VERSION DUCKDB_API_LATEST
54#endif
55
56#include <stdbool.h>
57#include <stdint.h>
58#include <stdlib.h>
59
60#ifdef __cplusplus
61extern "C" {
62#endif
63
64//===--------------------------------------------------------------------===//
65// Type Information
66//===--------------------------------------------------------------------===//
67typedef uint64_t idx_t;
68
69typedef enum DUCKDB_TYPE {
70 DUCKDB_TYPE_INVALID = 0,
71 // bool
72 DUCKDB_TYPE_BOOLEAN,
73 // int8_t
74 DUCKDB_TYPE_TINYINT,
75 // int16_t
76 DUCKDB_TYPE_SMALLINT,
77 // int32_t
78 DUCKDB_TYPE_INTEGER,
79 // int64_t
80 DUCKDB_TYPE_BIGINT,
81 // uint8_t
82 DUCKDB_TYPE_UTINYINT,
83 // uint16_t
84 DUCKDB_TYPE_USMALLINT,
85 // uint32_t
86 DUCKDB_TYPE_UINTEGER,
87 // uint64_t
88 DUCKDB_TYPE_UBIGINT,
89 // float
90 DUCKDB_TYPE_FLOAT,
91 // double
92 DUCKDB_TYPE_DOUBLE,
93 // duckdb_timestamp, in microseconds
94 DUCKDB_TYPE_TIMESTAMP,
95 // duckdb_date
96 DUCKDB_TYPE_DATE,
97 // duckdb_time
98 DUCKDB_TYPE_TIME,
99 // duckdb_interval
100 DUCKDB_TYPE_INTERVAL,
101 // duckdb_hugeint
102 DUCKDB_TYPE_HUGEINT,
103 // const char*
104 DUCKDB_TYPE_VARCHAR,
105 // duckdb_blob
106 DUCKDB_TYPE_BLOB,
107 // decimal
108 DUCKDB_TYPE_DECIMAL,
109 // duckdb_timestamp, in seconds
110 DUCKDB_TYPE_TIMESTAMP_S,
111 // duckdb_timestamp, in milliseconds
112 DUCKDB_TYPE_TIMESTAMP_MS,
113 // duckdb_timestamp, in nanoseconds
114 DUCKDB_TYPE_TIMESTAMP_NS,
115 // enum type, only useful as logical type
116 DUCKDB_TYPE_ENUM,
117 // list type, only useful as logical type
118 DUCKDB_TYPE_LIST,
119 // struct type, only useful as logical type
120 DUCKDB_TYPE_STRUCT,
121 // map type, only useful as logical type
122 DUCKDB_TYPE_MAP,
123 // duckdb_hugeint
124 DUCKDB_TYPE_UUID,
125 // union type, only useful as logical type
126 DUCKDB_TYPE_UNION,
127 // duckdb_bit
128 DUCKDB_TYPE_BIT,
129} duckdb_type;
130
131//! Days are stored as days since 1970-01-01
132//! Use the duckdb_from_date/duckdb_to_date function to extract individual information
133typedef struct {
134 int32_t days;
135} duckdb_date;
136
137typedef struct {
138 int32_t year;
139 int8_t month;
140 int8_t day;
141} duckdb_date_struct;
142
143//! Time is stored as microseconds since 00:00:00
144//! Use the duckdb_from_time/duckdb_to_time function to extract individual information
145typedef struct {
146 int64_t micros;
147} duckdb_time;
148
149typedef struct {
150 int8_t hour;
151 int8_t min;
152 int8_t sec;
153 int32_t micros;
154} duckdb_time_struct;
155
156//! Timestamps are stored as microseconds since 1970-01-01
157//! Use the duckdb_from_timestamp/duckdb_to_timestamp function to extract individual information
158typedef struct {
159 int64_t micros;
160} duckdb_timestamp;
161
162typedef struct {
163 duckdb_date_struct date;
164 duckdb_time_struct time;
165} duckdb_timestamp_struct;
166
167typedef struct {
168 int32_t months;
169 int32_t days;
170 int64_t micros;
171} duckdb_interval;
172
173//! Hugeints are composed in a (lower, upper) component
174//! The value of the hugeint is upper * 2^64 + lower
175//! For easy usage, the functions duckdb_hugeint_to_double/duckdb_double_to_hugeint are recommended
176typedef struct {
177 uint64_t lower;
178 int64_t upper;
179} duckdb_hugeint;
180
181typedef struct {
182 uint8_t width;
183 uint8_t scale;
184
185 duckdb_hugeint value;
186} duckdb_decimal;
187
188typedef struct {
189 char *data;
190 idx_t size;
191} duckdb_string;
192
193/*
194 The internal data representation of a VARCHAR/BLOB column
195*/
196typedef struct {
197 union {
198 struct {
199 uint32_t length;
200 char prefix[4];
201 char *ptr;
202 } pointer;
203 struct {
204 uint32_t length;
205 char inlined[12];
206 } inlined;
207 } value;
208} duckdb_string_t;
209
210typedef struct {
211 void *data;
212 idx_t size;
213} duckdb_blob;
214
215typedef struct {
216 uint64_t offset;
217 uint64_t length;
218} duckdb_list_entry;
219
220typedef struct {
221#if DUCKDB_API_VERSION < DUCKDB_API_0_3_2
222 void *data;
223 bool *nullmask;
224 duckdb_type type;
225 char *name;
226#else
227 // deprecated, use duckdb_column_data
228 void *__deprecated_data;
229 // deprecated, use duckdb_nullmask_data
230 bool *__deprecated_nullmask;
231 // deprecated, use duckdb_column_type
232 duckdb_type __deprecated_type;
233 // deprecated, use duckdb_column_name
234 char *__deprecated_name;
235#endif
236 void *internal_data;
237} duckdb_column;
238
239typedef struct {
240#if DUCKDB_API_VERSION < DUCKDB_API_0_3_2
241 idx_t column_count;
242 idx_t row_count;
243 idx_t rows_changed;
244 duckdb_column *columns;
245 char *error_message;
246#else
247 // deprecated, use duckdb_column_count
248 idx_t __deprecated_column_count;
249 // deprecated, use duckdb_row_count
250 idx_t __deprecated_row_count;
251 // deprecated, use duckdb_rows_changed
252 idx_t __deprecated_rows_changed;
253 // deprecated, use duckdb_column_ family of functions
254 duckdb_column *__deprecated_columns;
255 // deprecated, use duckdb_result_error
256 char *__deprecated_error_message;
257#endif
258 void *internal_data;
259} duckdb_result;
260
261typedef struct _duckdb_database {
262 void *__db;
263} * duckdb_database;
264typedef struct _duckdb_connection {
265 void *__conn;
266} * duckdb_connection;
267typedef struct _duckdb_prepared_statement {
268 void *__prep;
269} * duckdb_prepared_statement;
270typedef struct _duckdb_extracted_statements {
271 void *__extrac;
272} * duckdb_extracted_statements;
273typedef struct _duckdb_pending_result {
274 void *__pend;
275} * duckdb_pending_result;
276typedef struct _duckdb_appender {
277 void *__appn;
278} * duckdb_appender;
279typedef struct _duckdb_arrow {
280 void *__arrw;
281} * duckdb_arrow;
282typedef struct _duckdb_config {
283 void *__cnfg;
284} * duckdb_config;
285typedef struct _duckdb_arrow_schema {
286 void *__arrs;
287} * duckdb_arrow_schema;
288typedef struct _duckdb_arrow_array {
289 void *__arra;
290} * duckdb_arrow_array;
291typedef struct _duckdb_logical_type {
292 void *__lglt;
293} * duckdb_logical_type;
294typedef struct _duckdb_data_chunk {
295 void *__dtck;
296} * duckdb_data_chunk;
297typedef struct _duckdb_vector {
298 void *__vctr;
299} * duckdb_vector;
300typedef struct _duckdb_value {
301 void *__val;
302} * duckdb_value;
303
304typedef enum { DuckDBSuccess = 0, DuckDBError = 1 } duckdb_state;
305typedef enum {
306 DUCKDB_PENDING_RESULT_READY = 0,
307 DUCKDB_PENDING_RESULT_NOT_READY = 1,
308 DUCKDB_PENDING_ERROR = 2
309} duckdb_pending_state;
310
311//===--------------------------------------------------------------------===//
312// Open/Connect
313//===--------------------------------------------------------------------===//
314
315/*!
316Creates a new database or opens an existing database file stored at the the given path.
317If no path is given a new in-memory database is created instead.
318The instantiated database should be closed with 'duckdb_close'
319
320* path: Path to the database file on disk, or `nullptr` or `:memory:` to open an in-memory database.
321* out_database: The result database object.
322* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
323*/
324DUCKDB_API duckdb_state duckdb_open(const char *path, duckdb_database *out_database);
325
326/*!
327Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the the given path.
328
329* path: Path to the database file on disk, or `nullptr` or `:memory:` to open an in-memory database.
330* out_database: The result database object.
331* config: (Optional) configuration used to start up the database system.
332* out_error: If set and the function returns DuckDBError, this will contain the reason why the start-up failed.
333Note that the error must be freed using `duckdb_free`.
334* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
335*/
336DUCKDB_API duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config,
337 char **out_error);
338
339/*!
340Closes the specified database and de-allocates all memory allocated for that database.
341This should be called after you are done with any database allocated through `duckdb_open`.
342Note that failing to call `duckdb_close` (in case of e.g. a program crash) will not cause data corruption.
343Still it is recommended to always correctly close a database object after you are done with it.
344
345* database: The database object to shut down.
346*/
347DUCKDB_API void duckdb_close(duckdb_database *database);
348
349/*!
350Opens a connection to a database. Connections are required to query the database, and store transactional state
351associated with the connection.
352The instantiated connection should be closed using 'duckdb_disconnect'
353
354* database: The database file to connect to.
355* out_connection: The result connection object.
356* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
357*/
358DUCKDB_API duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection);
359
360/*!
361Closes the specified connection and de-allocates all memory allocated for that connection.
362
363* connection: The connection to close.
364*/
365DUCKDB_API void duckdb_disconnect(duckdb_connection *connection);
366
367/*!
368Returns the version of the linked DuckDB, with a version postfix for dev versions
369
370Usually used for developing C extensions that must return this for a compatibility check.
371*/
372DUCKDB_API const char *duckdb_library_version();
373
374//===--------------------------------------------------------------------===//
375// Configuration
376//===--------------------------------------------------------------------===//
377/*!
378Initializes an empty configuration object that can be used to provide start-up options for the DuckDB instance
379through `duckdb_open_ext`.
380
381This will always succeed unless there is a malloc failure.
382
383* out_config: The result configuration object.
384* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
385*/
386DUCKDB_API duckdb_state duckdb_create_config(duckdb_config *out_config);
387
388/*!
389This returns the total amount of configuration options available for usage with `duckdb_get_config_flag`.
390
391This should not be called in a loop as it internally loops over all the options.
392
393* returns: The amount of config options available.
394*/
395DUCKDB_API size_t duckdb_config_count();
396
397/*!
398Obtains a human-readable name and description of a specific configuration option. This can be used to e.g.
399display configuration options. This will succeed unless `index` is out of range (i.e. `>= duckdb_config_count`).
400
401The result name or description MUST NOT be freed.
402
403* index: The index of the configuration option (between 0 and `duckdb_config_count`)
404* out_name: A name of the configuration flag.
405* out_description: A description of the configuration flag.
406* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
407*/
408DUCKDB_API duckdb_state duckdb_get_config_flag(size_t index, const char **out_name, const char **out_description);
409
410/*!
411Sets the specified option for the specified configuration. The configuration option is indicated by name.
412To obtain a list of config options, see `duckdb_get_config_flag`.
413
414In the source code, configuration options are defined in `config.cpp`.
415
416This can fail if either the name is invalid, or if the value provided for the option is invalid.
417
418* duckdb_config: The configuration object to set the option on.
419* name: The name of the configuration flag to set.
420* option: The value to set the configuration flag to.
421* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
422*/
423DUCKDB_API duckdb_state duckdb_set_config(duckdb_config config, const char *name, const char *option);
424
425/*!
426Destroys the specified configuration option and de-allocates all memory allocated for the object.
427
428* config: The configuration object to destroy.
429*/
430DUCKDB_API void duckdb_destroy_config(duckdb_config *config);
431
432//===--------------------------------------------------------------------===//
433// Query Execution
434//===--------------------------------------------------------------------===//
435/*!
436Executes a SQL query within a connection and stores the full (materialized) result in the out_result pointer.
437If the query fails to execute, DuckDBError is returned and the error message can be retrieved by calling
438`duckdb_result_error`.
439
440Note that after running `duckdb_query`, `duckdb_destroy_result` must be called on the result object even if the
441query fails, otherwise the error stored within the result will not be freed correctly.
442
443* connection: The connection to perform the query in.
444* query: The SQL query to run.
445* out_result: The query result.
446* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
447*/
448DUCKDB_API duckdb_state duckdb_query(duckdb_connection connection, const char *query, duckdb_result *out_result);
449
450/*!
451Closes the result and de-allocates all memory allocated for that connection.
452
453* result: The result to destroy.
454*/
455DUCKDB_API void duckdb_destroy_result(duckdb_result *result);
456
457/*!
458Returns the column name of the specified column. The result should not need be freed; the column names will
459automatically be destroyed when the result is destroyed.
460
461Returns `NULL` if the column is out of range.
462
463* result: The result object to fetch the column name from.
464* col: The column index.
465* returns: The column name of the specified column.
466*/
467DUCKDB_API const char *duckdb_column_name(duckdb_result *result, idx_t col);
468
469/*!
470Returns the column type of the specified column.
471
472Returns `DUCKDB_TYPE_INVALID` if the column is out of range.
473
474* result: The result object to fetch the column type from.
475* col: The column index.
476* returns: The column type of the specified column.
477*/
478DUCKDB_API duckdb_type duckdb_column_type(duckdb_result *result, idx_t col);
479
480/*!
481Returns the logical column type of the specified column.
482
483The return type of this call should be destroyed with `duckdb_destroy_logical_type`.
484
485Returns `NULL` if the column is out of range.
486
487* result: The result object to fetch the column type from.
488* col: The column index.
489* returns: The logical column type of the specified column.
490*/
491DUCKDB_API duckdb_logical_type duckdb_column_logical_type(duckdb_result *result, idx_t col);
492
493/*!
494Returns the number of columns present in a the result object.
495
496* result: The result object.
497* returns: The number of columns present in the result object.
498*/
499DUCKDB_API idx_t duckdb_column_count(duckdb_result *result);
500
501/*!
502Returns the number of rows present in a the result object.
503
504* result: The result object.
505* returns: The number of rows present in the result object.
506*/
507DUCKDB_API idx_t duckdb_row_count(duckdb_result *result);
508
509/*!
510Returns the number of rows changed by the query stored in the result. This is relevant only for INSERT/UPDATE/DELETE
511queries. For other queries the rows_changed will be 0.
512
513* result: The result object.
514* returns: The number of rows changed.
515*/
516DUCKDB_API idx_t duckdb_rows_changed(duckdb_result *result);
517
518/*!
519**DEPRECATED**: Prefer using `duckdb_result_get_chunk` instead.
520
521Returns the data of a specific column of a result in columnar format.
522
523The function returns a dense array which contains the result data. The exact type stored in the array depends on the
524corresponding duckdb_type (as provided by `duckdb_column_type`). For the exact type by which the data should be
525accessed, see the comments in [the types section](types) or the `DUCKDB_TYPE` enum.
526
527For example, for a column of type `DUCKDB_TYPE_INTEGER`, rows can be accessed in the following manner:
528```c
529int32_t *data = (int32_t *) duckdb_column_data(&result, 0);
530printf("Data for row %d: %d\n", row, data[row]);
531```
532
533* result: The result object to fetch the column data from.
534* col: The column index.
535* returns: The column data of the specified column.
536*/
537DUCKDB_API void *duckdb_column_data(duckdb_result *result, idx_t col);
538
539/*!
540**DEPRECATED**: Prefer using `duckdb_result_get_chunk` instead.
541
542Returns the nullmask of a specific column of a result in columnar format. The nullmask indicates for every row
543whether or not the corresponding row is `NULL`. If a row is `NULL`, the values present in the array provided
544by `duckdb_column_data` are undefined.
545
546```c
547int32_t *data = (int32_t *) duckdb_column_data(&result, 0);
548bool *nullmask = duckdb_nullmask_data(&result, 0);
549if (nullmask[row]) {
550 printf("Data for row %d: NULL\n", row);
551} else {
552 printf("Data for row %d: %d\n", row, data[row]);
553}
554```
555
556* result: The result object to fetch the nullmask from.
557* col: The column index.
558* returns: The nullmask of the specified column.
559*/
560DUCKDB_API bool *duckdb_nullmask_data(duckdb_result *result, idx_t col);
561
562/*!
563Returns the error message contained within the result. The error is only set if `duckdb_query` returns `DuckDBError`.
564
565The result of this function must not be freed. It will be cleaned up when `duckdb_destroy_result` is called.
566
567* result: The result object to fetch the error from.
568* returns: The error of the result.
569*/
570DUCKDB_API const char *duckdb_result_error(duckdb_result *result);
571
572//===--------------------------------------------------------------------===//
573// Result Functions
574//===--------------------------------------------------------------------===//
575
576/*!
577Fetches a data chunk from the duckdb_result. This function should be called repeatedly until the result is exhausted.
578
579The result must be destroyed with `duckdb_destroy_data_chunk`.
580
581This function supersedes all `duckdb_value` functions, as well as the `duckdb_column_data` and `duckdb_nullmask_data`
582functions. It results in significantly better performance, and should be preferred in newer code-bases.
583
584If this function is used, none of the other result functions can be used and vice versa (i.e. this function cannot be
585mixed with the legacy result functions).
586
587Use `duckdb_result_chunk_count` to figure out how many chunks there are in the result.
588
589* result: The result object to fetch the data chunk from.
590* chunk_index: The chunk index to fetch from.
591* returns: The resulting data chunk. Returns `NULL` if the chunk index is out of bounds.
592*/
593DUCKDB_API duckdb_data_chunk duckdb_result_get_chunk(duckdb_result result, idx_t chunk_index);
594
595/*!
596Checks if the type of the internal result is StreamQueryResult.
597
598* result: The result object to check.
599* returns: Whether or not the result object is of the type StreamQueryResult
600*/
601DUCKDB_API bool duckdb_result_is_streaming(duckdb_result result);
602
603/*!
604Returns the number of data chunks present in the result.
605
606* result: The result object
607* returns: Number of data chunks present in the result.
608*/
609DUCKDB_API idx_t duckdb_result_chunk_count(duckdb_result result);
610
611// Safe fetch functions
612// These functions will perform conversions if necessary.
613// On failure (e.g. if conversion cannot be performed or if the value is NULL) a default value is returned.
614// Note that these functions are slow since they perform bounds checking and conversion
615// For fast access of values prefer using `duckdb_result_get_chunk`
616
617/*!
618 * returns: The boolean value at the specified location, or false if the value cannot be converted.
619 */
620DUCKDB_API bool duckdb_value_boolean(duckdb_result *result, idx_t col, idx_t row);
621
622/*!
623 * returns: The int8_t value at the specified location, or 0 if the value cannot be converted.
624 */
625DUCKDB_API int8_t duckdb_value_int8(duckdb_result *result, idx_t col, idx_t row);
626
627/*!
628 * returns: The int16_t value at the specified location, or 0 if the value cannot be converted.
629 */
630DUCKDB_API int16_t duckdb_value_int16(duckdb_result *result, idx_t col, idx_t row);
631
632/*!
633 * returns: The int32_t value at the specified location, or 0 if the value cannot be converted.
634 */
635DUCKDB_API int32_t duckdb_value_int32(duckdb_result *result, idx_t col, idx_t row);
636
637/*!
638 * returns: The int64_t value at the specified location, or 0 if the value cannot be converted.
639 */
640DUCKDB_API int64_t duckdb_value_int64(duckdb_result *result, idx_t col, idx_t row);
641
642/*!
643 * returns: The duckdb_hugeint value at the specified location, or 0 if the value cannot be converted.
644 */
645DUCKDB_API duckdb_hugeint duckdb_value_hugeint(duckdb_result *result, idx_t col, idx_t row);
646
647/*!
648 * returns: The duckdb_decimal value at the specified location, or 0 if the value cannot be converted.
649 */
650DUCKDB_API duckdb_decimal duckdb_value_decimal(duckdb_result *result, idx_t col, idx_t row);
651
652/*!
653 * returns: The uint8_t value at the specified location, or 0 if the value cannot be converted.
654 */
655DUCKDB_API uint8_t duckdb_value_uint8(duckdb_result *result, idx_t col, idx_t row);
656
657/*!
658 * returns: The uint16_t value at the specified location, or 0 if the value cannot be converted.
659 */
660DUCKDB_API uint16_t duckdb_value_uint16(duckdb_result *result, idx_t col, idx_t row);
661
662/*!
663 * returns: The uint32_t value at the specified location, or 0 if the value cannot be converted.
664 */
665DUCKDB_API uint32_t duckdb_value_uint32(duckdb_result *result, idx_t col, idx_t row);
666
667/*!
668 * returns: The uint64_t value at the specified location, or 0 if the value cannot be converted.
669 */
670DUCKDB_API uint64_t duckdb_value_uint64(duckdb_result *result, idx_t col, idx_t row);
671
672/*!
673 * returns: The float value at the specified location, or 0 if the value cannot be converted.
674 */
675DUCKDB_API float duckdb_value_float(duckdb_result *result, idx_t col, idx_t row);
676
677/*!
678 * returns: The double value at the specified location, or 0 if the value cannot be converted.
679 */
680DUCKDB_API double duckdb_value_double(duckdb_result *result, idx_t col, idx_t row);
681
682/*!
683 * returns: The duckdb_date value at the specified location, or 0 if the value cannot be converted.
684 */
685DUCKDB_API duckdb_date duckdb_value_date(duckdb_result *result, idx_t col, idx_t row);
686
687/*!
688 * returns: The duckdb_time value at the specified location, or 0 if the value cannot be converted.
689 */
690DUCKDB_API duckdb_time duckdb_value_time(duckdb_result *result, idx_t col, idx_t row);
691
692/*!
693 * returns: The duckdb_timestamp value at the specified location, or 0 if the value cannot be converted.
694 */
695DUCKDB_API duckdb_timestamp duckdb_value_timestamp(duckdb_result *result, idx_t col, idx_t row);
696
697/*!
698 * returns: The duckdb_interval value at the specified location, or 0 if the value cannot be converted.
699 */
700DUCKDB_API duckdb_interval duckdb_value_interval(duckdb_result *result, idx_t col, idx_t row);
701
702/*!
703* DEPRECATED: use duckdb_value_string instead. This function does not work correctly if the string contains null bytes.
704* returns: The text value at the specified location as a null-terminated string, or nullptr if the value cannot be
705converted. The result must be freed with `duckdb_free`.
706*/
707DUCKDB_API char *duckdb_value_varchar(duckdb_result *result, idx_t col, idx_t row);
708
709/*!s
710* returns: The string value at the specified location.
711The result must be freed with `duckdb_free`.
712*/
713DUCKDB_API duckdb_string duckdb_value_string(duckdb_result *result, idx_t col, idx_t row);
714
715/*!
716* DEPRECATED: use duckdb_value_string_internal instead. This function does not work correctly if the string contains
717null bytes.
718* returns: The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast.
719If the column is NOT a VARCHAR column this function will return NULL.
720
721The result must NOT be freed.
722*/
723DUCKDB_API char *duckdb_value_varchar_internal(duckdb_result *result, idx_t col, idx_t row);
724
725/*!
726* DEPRECATED: use duckdb_value_string_internal instead. This function does not work correctly if the string contains
727null bytes.
728* returns: The char* value at the specified location. ONLY works on VARCHAR columns and does not auto-cast.
729If the column is NOT a VARCHAR column this function will return NULL.
730
731The result must NOT be freed.
732*/
733DUCKDB_API duckdb_string duckdb_value_string_internal(duckdb_result *result, idx_t col, idx_t row);
734
735/*!
736* returns: The duckdb_blob value at the specified location. Returns a blob with blob.data set to nullptr if the
737value cannot be converted. The resulting "blob.data" must be freed with `duckdb_free.`
738*/
739DUCKDB_API duckdb_blob duckdb_value_blob(duckdb_result *result, idx_t col, idx_t row);
740
741/*!
742 * returns: Returns true if the value at the specified index is NULL, and false otherwise.
743 */
744DUCKDB_API bool duckdb_value_is_null(duckdb_result *result, idx_t col, idx_t row);
745
746//===--------------------------------------------------------------------===//
747// Helpers
748//===--------------------------------------------------------------------===//
749/*!
750Allocate `size` bytes of memory using the duckdb internal malloc function. Any memory allocated in this manner
751should be freed using `duckdb_free`.
752
753* size: The number of bytes to allocate.
754* returns: A pointer to the allocated memory region.
755*/
756DUCKDB_API void *duckdb_malloc(size_t size);
757
758/*!
759Free a value returned from `duckdb_malloc`, `duckdb_value_varchar` or `duckdb_value_blob`.
760
761* ptr: The memory region to de-allocate.
762*/
763DUCKDB_API void duckdb_free(void *ptr);
764
765/*!
766The internal vector size used by DuckDB.
767This is the amount of tuples that will fit into a data chunk created by `duckdb_create_data_chunk`.
768
769* returns: The vector size.
770*/
771DUCKDB_API idx_t duckdb_vector_size();
772
773/*!
774Whether or not the duckdb_string_t value is inlined.
775This means that the data of the string does not have a separate allocation.
776
777*/
778DUCKDB_API bool duckdb_string_is_inlined(duckdb_string_t string);
779
780//===--------------------------------------------------------------------===//
781// Date/Time/Timestamp Helpers
782//===--------------------------------------------------------------------===//
783/*!
784Decompose a `duckdb_date` object into year, month and date (stored as `duckdb_date_struct`).
785
786* date: The date object, as obtained from a `DUCKDB_TYPE_DATE` column.
787* returns: The `duckdb_date_struct` with the decomposed elements.
788*/
789DUCKDB_API duckdb_date_struct duckdb_from_date(duckdb_date date);
790
791/*!
792Re-compose a `duckdb_date` from year, month and date (`duckdb_date_struct`).
793
794* date: The year, month and date stored in a `duckdb_date_struct`.
795* returns: The `duckdb_date` element.
796*/
797DUCKDB_API duckdb_date duckdb_to_date(duckdb_date_struct date);
798
799/*!
800Decompose a `duckdb_time` object into hour, minute, second and microsecond (stored as `duckdb_time_struct`).
801
802* time: The time object, as obtained from a `DUCKDB_TYPE_TIME` column.
803* returns: The `duckdb_time_struct` with the decomposed elements.
804*/
805DUCKDB_API duckdb_time_struct duckdb_from_time(duckdb_time time);
806
807/*!
808Re-compose a `duckdb_time` from hour, minute, second and microsecond (`duckdb_time_struct`).
809
810* time: The hour, minute, second and microsecond in a `duckdb_time_struct`.
811* returns: The `duckdb_time` element.
812*/
813DUCKDB_API duckdb_time duckdb_to_time(duckdb_time_struct time);
814
815/*!
816Decompose a `duckdb_timestamp` object into a `duckdb_timestamp_struct`.
817
818* ts: The ts object, as obtained from a `DUCKDB_TYPE_TIMESTAMP` column.
819* returns: The `duckdb_timestamp_struct` with the decomposed elements.
820*/
821DUCKDB_API duckdb_timestamp_struct duckdb_from_timestamp(duckdb_timestamp ts);
822
823/*!
824Re-compose a `duckdb_timestamp` from a duckdb_timestamp_struct.
825
826* ts: The de-composed elements in a `duckdb_timestamp_struct`.
827* returns: The `duckdb_timestamp` element.
828*/
829DUCKDB_API duckdb_timestamp duckdb_to_timestamp(duckdb_timestamp_struct ts);
830
831//===--------------------------------------------------------------------===//
832// Hugeint Helpers
833//===--------------------------------------------------------------------===//
834/*!
835Converts a duckdb_hugeint object (as obtained from a `DUCKDB_TYPE_HUGEINT` column) into a double.
836
837* val: The hugeint value.
838* returns: The converted `double` element.
839*/
840DUCKDB_API double duckdb_hugeint_to_double(duckdb_hugeint val);
841
842/*!
843Converts a double value to a duckdb_hugeint object.
844
845If the conversion fails because the double value is too big the result will be 0.
846
847* val: The double value.
848* returns: The converted `duckdb_hugeint` element.
849*/
850DUCKDB_API duckdb_hugeint duckdb_double_to_hugeint(double val);
851
852/*!
853Converts a double value to a duckdb_decimal object.
854
855If the conversion fails because the double value is too big, or the width/scale are invalid the result will be 0.
856
857* val: The double value.
858* returns: The converted `duckdb_decimal` element.
859*/
860DUCKDB_API duckdb_decimal duckdb_double_to_decimal(double val, uint8_t width, uint8_t scale);
861
862//===--------------------------------------------------------------------===//
863// Decimal Helpers
864//===--------------------------------------------------------------------===//
865/*!
866Converts a duckdb_decimal object (as obtained from a `DUCKDB_TYPE_DECIMAL` column) into a double.
867
868* val: The decimal value.
869* returns: The converted `double` element.
870*/
871DUCKDB_API double duckdb_decimal_to_double(duckdb_decimal val);
872
873//===--------------------------------------------------------------------===//
874// Prepared Statements
875//===--------------------------------------------------------------------===//
876// A prepared statement is a parameterized query that allows you to bind parameters to it.
877// * This is useful to easily supply parameters to functions and avoid SQL injection attacks.
878// * This is useful to speed up queries that you will execute several times with different parameters.
879// Because the query will only be parsed, bound, optimized and planned once during the prepare stage,
880// rather than once per execution.
881// For example:
882// SELECT * FROM tbl WHERE id=?
883// Or a query with multiple parameters:
884// SELECT * FROM tbl WHERE id=$1 OR name=$2
885
886/*!
887Create a prepared statement object from a query.
888
889Note that after calling `duckdb_prepare`, the prepared statement should always be destroyed using
890`duckdb_destroy_prepare`, even if the prepare fails.
891
892If the prepare fails, `duckdb_prepare_error` can be called to obtain the reason why the prepare failed.
893
894* connection: The connection object
895* query: The SQL query to prepare
896* out_prepared_statement: The resulting prepared statement object
897* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
898*/
899DUCKDB_API duckdb_state duckdb_prepare(duckdb_connection connection, const char *query,
900 duckdb_prepared_statement *out_prepared_statement);
901
902/*!
903Closes the prepared statement and de-allocates all memory allocated for the statement.
904
905* prepared_statement: The prepared statement to destroy.
906*/
907DUCKDB_API void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement);
908
909/*!
910Returns the error message associated with the given prepared statement.
911If the prepared statement has no error message, this returns `nullptr` instead.
912
913The error message should not be freed. It will be de-allocated when `duckdb_destroy_prepare` is called.
914
915* prepared_statement: The prepared statement to obtain the error from.
916* returns: The error message, or `nullptr` if there is none.
917*/
918DUCKDB_API const char *duckdb_prepare_error(duckdb_prepared_statement prepared_statement);
919
920/*!
921Returns the number of parameters that can be provided to the given prepared statement.
922
923Returns 0 if the query was not successfully prepared.
924
925* prepared_statement: The prepared statement to obtain the number of parameters for.
926*/
927DUCKDB_API idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement);
928
929/*!
930Returns the parameter type for the parameter at the given index.
931
932Returns `DUCKDB_TYPE_INVALID` if the parameter index is out of range or the statement was not successfully prepared.
933
934* prepared_statement: The prepared statement.
935* param_idx: The parameter index.
936* returns: The parameter type
937*/
938DUCKDB_API duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx);
939
940/*!
941Clear the params bind to the prepared statement.
942*/
943DUCKDB_API duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement);
944
945/*!
946Binds a bool value to the prepared statement at the specified index.
947*/
948DUCKDB_API duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val);
949
950/*!
951Binds an int8_t value to the prepared statement at the specified index.
952*/
953DUCKDB_API duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val);
954
955/*!
956Binds an int16_t value to the prepared statement at the specified index.
957*/
958DUCKDB_API duckdb_state duckdb_bind_int16(duckdb_prepared_statement prepared_statement, idx_t param_idx, int16_t val);
959
960/*!
961Binds an int32_t value to the prepared statement at the specified index.
962*/
963DUCKDB_API duckdb_state duckdb_bind_int32(duckdb_prepared_statement prepared_statement, idx_t param_idx, int32_t val);
964
965/*!
966Binds an int64_t value to the prepared statement at the specified index.
967*/
968DUCKDB_API duckdb_state duckdb_bind_int64(duckdb_prepared_statement prepared_statement, idx_t param_idx, int64_t val);
969
970/*!
971Binds an duckdb_hugeint value to the prepared statement at the specified index.
972*/
973DUCKDB_API duckdb_state duckdb_bind_hugeint(duckdb_prepared_statement prepared_statement, idx_t param_idx,
974 duckdb_hugeint val);
975/*!
976Binds a duckdb_decimal value to the prepared statement at the specified index.
977*/
978DUCKDB_API duckdb_state duckdb_bind_decimal(duckdb_prepared_statement prepared_statement, idx_t param_idx,
979 duckdb_decimal val);
980
981/*!
982Binds an uint8_t value to the prepared statement at the specified index.
983*/
984DUCKDB_API duckdb_state duckdb_bind_uint8(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint8_t val);
985
986/*!
987Binds an uint16_t value to the prepared statement at the specified index.
988*/
989DUCKDB_API duckdb_state duckdb_bind_uint16(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint16_t val);
990
991/*!
992Binds an uint32_t value to the prepared statement at the specified index.
993*/
994DUCKDB_API duckdb_state duckdb_bind_uint32(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint32_t val);
995
996/*!
997Binds an uint64_t value to the prepared statement at the specified index.
998*/
999DUCKDB_API duckdb_state duckdb_bind_uint64(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint64_t val);
1000
1001/*!
1002Binds an float value to the prepared statement at the specified index.
1003*/
1004DUCKDB_API duckdb_state duckdb_bind_float(duckdb_prepared_statement prepared_statement, idx_t param_idx, float val);
1005
1006/*!
1007Binds an double value to the prepared statement at the specified index.
1008*/
1009DUCKDB_API duckdb_state duckdb_bind_double(duckdb_prepared_statement prepared_statement, idx_t param_idx, double val);
1010
1011/*!
1012Binds a duckdb_date value to the prepared statement at the specified index.
1013*/
1014DUCKDB_API duckdb_state duckdb_bind_date(duckdb_prepared_statement prepared_statement, idx_t param_idx,
1015 duckdb_date val);
1016
1017/*!
1018Binds a duckdb_time value to the prepared statement at the specified index.
1019*/
1020DUCKDB_API duckdb_state duckdb_bind_time(duckdb_prepared_statement prepared_statement, idx_t param_idx,
1021 duckdb_time val);
1022
1023/*!
1024Binds a duckdb_timestamp value to the prepared statement at the specified index.
1025*/
1026DUCKDB_API duckdb_state duckdb_bind_timestamp(duckdb_prepared_statement prepared_statement, idx_t param_idx,
1027 duckdb_timestamp val);
1028
1029/*!
1030Binds a duckdb_interval value to the prepared statement at the specified index.
1031*/
1032DUCKDB_API duckdb_state duckdb_bind_interval(duckdb_prepared_statement prepared_statement, idx_t param_idx,
1033 duckdb_interval val);
1034
1035/*!
1036Binds a null-terminated varchar value to the prepared statement at the specified index.
1037*/
1038DUCKDB_API duckdb_state duckdb_bind_varchar(duckdb_prepared_statement prepared_statement, idx_t param_idx,
1039 const char *val);
1040
1041/*!
1042Binds a varchar value to the prepared statement at the specified index.
1043*/
1044DUCKDB_API duckdb_state duckdb_bind_varchar_length(duckdb_prepared_statement prepared_statement, idx_t param_idx,
1045 const char *val, idx_t length);
1046
1047/*!
1048Binds a blob value to the prepared statement at the specified index.
1049*/
1050DUCKDB_API duckdb_state duckdb_bind_blob(duckdb_prepared_statement prepared_statement, idx_t param_idx,
1051 const void *data, idx_t length);
1052
1053/*!
1054Binds a NULL value to the prepared statement at the specified index.
1055*/
1056DUCKDB_API duckdb_state duckdb_bind_null(duckdb_prepared_statement prepared_statement, idx_t param_idx);
1057
1058/*!
1059Executes the prepared statement with the given bound parameters, and returns a materialized query result.
1060
1061This method can be called multiple times for each prepared statement, and the parameters can be modified
1062between calls to this function.
1063
1064* prepared_statement: The prepared statement to execute.
1065* out_result: The query result.
1066* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
1067*/
1068DUCKDB_API duckdb_state duckdb_execute_prepared(duckdb_prepared_statement prepared_statement,
1069 duckdb_result *out_result);
1070
1071/*!
1072Executes the prepared statement with the given bound parameters, and returns an arrow query result.
1073
1074* prepared_statement: The prepared statement to execute.
1075* out_result: The query result.
1076* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
1077*/
1078DUCKDB_API duckdb_state duckdb_execute_prepared_arrow(duckdb_prepared_statement prepared_statement,
1079 duckdb_arrow *out_result);
1080
1081//===--------------------------------------------------------------------===//
1082// Extract Statements
1083//===--------------------------------------------------------------------===//
1084// A query string can be extracted into multiple SQL statements. Each statement can be prepared and executed separately.
1085
1086/*!
1087Extract all statements from a query.
1088Note that after calling `duckdb_extract_statements`, the extracted statements should always be destroyed using
1089`duckdb_destroy_extracted`, even if no statements were extracted.
1090If the extract fails, `duckdb_extract_statements_error` can be called to obtain the reason why the extract failed.
1091* connection: The connection object
1092* query: The SQL query to extract
1093* out_extracted_statements: The resulting extracted statements object
1094* returns: The number of extracted statements or 0 on failure.
1095*/
1096DUCKDB_API idx_t duckdb_extract_statements(duckdb_connection connection, const char *query,
1097 duckdb_extracted_statements *out_extracted_statements);
1098
1099/*!
1100Prepare an extracted statement.
1101Note that after calling `duckdb_prepare_extracted_statement`, the prepared statement should always be destroyed using
1102`duckdb_destroy_prepare`, even if the prepare fails.
1103If the prepare fails, `duckdb_prepare_error` can be called to obtain the reason why the prepare failed.
1104* connection: The connection object
1105* extracted_statements: The extracted statements object
1106* index: The index of the extracted statement to prepare
1107* out_prepared_statement: The resulting prepared statement object
1108* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
1109*/
1110DUCKDB_API duckdb_state duckdb_prepare_extracted_statement(duckdb_connection connection,
1111 duckdb_extracted_statements extracted_statements,
1112 idx_t index,
1113 duckdb_prepared_statement *out_prepared_statement);
1114/*!
1115Returns the error message contained within the extracted statements.
1116The result of this function must not be freed. It will be cleaned up when `duckdb_destroy_extracted` is called.
1117* result: The extracted statements to fetch the error from.
1118* returns: The error of the extracted statements.
1119*/
1120DUCKDB_API const char *duckdb_extract_statements_error(duckdb_extracted_statements extracted_statements);
1121
1122/*!
1123De-allocates all memory allocated for the extracted statements.
1124* extracted_statements: The extracted statements to destroy.
1125*/
1126DUCKDB_API void duckdb_destroy_extracted(duckdb_extracted_statements *extracted_statements);
1127
1128//===--------------------------------------------------------------------===//
1129// Pending Result Interface
1130//===--------------------------------------------------------------------===//
1131/*!
1132Executes the prepared statement with the given bound parameters, and returns a pending result.
1133The pending result represents an intermediate structure for a query that is not yet fully executed.
1134The pending result can be used to incrementally execute a query, returning control to the client between tasks.
1135
1136Note that after calling `duckdb_pending_prepared`, the pending result should always be destroyed using
1137`duckdb_destroy_pending`, even if this function returns DuckDBError.
1138
1139* prepared_statement: The prepared statement to execute.
1140* out_result: The pending query result.
1141* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
1142*/
1143DUCKDB_API duckdb_state duckdb_pending_prepared(duckdb_prepared_statement prepared_statement,
1144 duckdb_pending_result *out_result);
1145
1146/*!
1147Executes the prepared statement with the given bound parameters, and returns a pending result.
1148This pending result will create a streaming duckdb_result when executed.
1149The pending result represents an intermediate structure for a query that is not yet fully executed.
1150
1151Note that after calling `duckdb_pending_prepared_streaming`, the pending result should always be destroyed using
1152`duckdb_destroy_pending`, even if this function returns DuckDBError.
1153
1154* prepared_statement: The prepared statement to execute.
1155* out_result: The pending query result.
1156* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
1157*/
1158DUCKDB_API duckdb_state duckdb_pending_prepared_streaming(duckdb_prepared_statement prepared_statement,
1159 duckdb_pending_result *out_result);
1160
1161/*!
1162Closes the pending result and de-allocates all memory allocated for the result.
1163
1164* pending_result: The pending result to destroy.
1165*/
1166DUCKDB_API void duckdb_destroy_pending(duckdb_pending_result *pending_result);
1167
1168/*!
1169Returns the error message contained within the pending result.
1170
1171The result of this function must not be freed. It will be cleaned up when `duckdb_destroy_pending` is called.
1172
1173* result: The pending result to fetch the error from.
1174* returns: The error of the pending result.
1175*/
1176DUCKDB_API const char *duckdb_pending_error(duckdb_pending_result pending_result);
1177
1178/*!
1179Executes a single task within the query, returning whether or not the query is ready.
1180
1181If this returns DUCKDB_PENDING_RESULT_READY, the duckdb_execute_pending function can be called to obtain the result.
1182If this returns DUCKDB_PENDING_RESULT_NOT_READY, the duckdb_pending_execute_task function should be called again.
1183If this returns DUCKDB_PENDING_ERROR, an error occurred during execution.
1184
1185The error message can be obtained by calling duckdb_pending_error on the pending_result.
1186
1187* pending_result: The pending result to execute a task within..
1188* returns: The state of the pending result after the execution.
1189*/
1190DUCKDB_API duckdb_pending_state duckdb_pending_execute_task(duckdb_pending_result pending_result);
1191
1192/*!
1193Fully execute a pending query result, returning the final query result.
1194
1195If duckdb_pending_execute_task has been called until DUCKDB_PENDING_RESULT_READY was returned, this will return fast.
1196Otherwise, all remaining tasks must be executed first.
1197
1198* pending_result: The pending result to execute.
1199* out_result: The result object.
1200* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
1201*/
1202DUCKDB_API duckdb_state duckdb_execute_pending(duckdb_pending_result pending_result, duckdb_result *out_result);
1203
1204//===--------------------------------------------------------------------===//
1205// Value Interface
1206//===--------------------------------------------------------------------===//
1207/*!
1208Destroys the value and de-allocates all memory allocated for that type.
1209
1210* value: The value to destroy.
1211*/
1212DUCKDB_API void duckdb_destroy_value(duckdb_value *value);
1213
1214/*!
1215Creates a value from a null-terminated string
1216
1217* value: The null-terminated string
1218* returns: The value. This must be destroyed with `duckdb_destroy_value`.
1219*/
1220DUCKDB_API duckdb_value duckdb_create_varchar(const char *text);
1221
1222/*!
1223Creates a value from a string
1224
1225* value: The text
1226* length: The length of the text
1227* returns: The value. This must be destroyed with `duckdb_destroy_value`.
1228*/
1229DUCKDB_API duckdb_value duckdb_create_varchar_length(const char *text, idx_t length);
1230
1231/*!
1232Creates a value from an int64
1233
1234* value: The bigint value
1235* returns: The value. This must be destroyed with `duckdb_destroy_value`.
1236*/
1237DUCKDB_API duckdb_value duckdb_create_int64(int64_t val);
1238
1239/*!
1240Obtains a string representation of the given value.
1241The result must be destroyed with `duckdb_free`.
1242
1243* value: The value
1244* returns: The string value. This must be destroyed with `duckdb_free`.
1245*/
1246DUCKDB_API char *duckdb_get_varchar(duckdb_value value);
1247
1248/*!
1249Obtains an int64 of the given value.
1250
1251* value: The value
1252* returns: The int64 value, or 0 if no conversion is possible
1253*/
1254DUCKDB_API int64_t duckdb_get_int64(duckdb_value value);
1255
1256//===--------------------------------------------------------------------===//
1257// Logical Type Interface
1258//===--------------------------------------------------------------------===//
1259
1260/*!
1261Creates a `duckdb_logical_type` from a standard primitive type.
1262The resulting type should be destroyed with `duckdb_destroy_logical_type`.
1263
1264This should not be used with `DUCKDB_TYPE_DECIMAL`.
1265
1266* type: The primitive type to create.
1267* returns: The logical type.
1268*/
1269DUCKDB_API duckdb_logical_type duckdb_create_logical_type(duckdb_type type);
1270
1271/*!
1272Creates a list type from its child type.
1273The resulting type should be destroyed with `duckdb_destroy_logical_type`.
1274
1275* type: The child type of list type to create.
1276* returns: The logical type.
1277*/
1278DUCKDB_API duckdb_logical_type duckdb_create_list_type(duckdb_logical_type type);
1279
1280/*!
1281Creates a map type from its key type and value type.
1282The resulting type should be destroyed with `duckdb_destroy_logical_type`.
1283
1284* type: The key type and value type of map type to create.
1285* returns: The logical type.
1286*/
1287DUCKDB_API duckdb_logical_type duckdb_create_map_type(duckdb_logical_type key_type, duckdb_logical_type value_type);
1288
1289/*!
1290Creates a UNION type from the passed types array
1291The resulting type should be destroyed with `duckdb_destroy_logical_type`.
1292
1293* types: The array of types that the union should consist of.
1294* type_amount: The size of the types array.
1295* returns: The logical type.
1296*/
1297DUCKDB_API duckdb_logical_type duckdb_create_union_type(duckdb_logical_type member_types, const char **member_names,
1298 idx_t member_count);
1299
1300/*!
1301Creates a `duckdb_logical_type` of type decimal with the specified width and scale
1302The resulting type should be destroyed with `duckdb_destroy_logical_type`.
1303
1304* width: The width of the decimal type
1305* scale: The scale of the decimal type
1306* returns: The logical type.
1307*/
1308DUCKDB_API duckdb_logical_type duckdb_create_decimal_type(uint8_t width, uint8_t scale);
1309
1310/*!
1311Retrieves the type class of a `duckdb_logical_type`.
1312
1313* type: The logical type object
1314* returns: The type id
1315*/
1316DUCKDB_API duckdb_type duckdb_get_type_id(duckdb_logical_type type);
1317
1318/*!
1319Retrieves the width of a decimal type.
1320
1321* type: The logical type object
1322* returns: The width of the decimal type
1323*/
1324DUCKDB_API uint8_t duckdb_decimal_width(duckdb_logical_type type);
1325
1326/*!
1327Retrieves the scale of a decimal type.
1328
1329* type: The logical type object
1330* returns: The scale of the decimal type
1331*/
1332DUCKDB_API uint8_t duckdb_decimal_scale(duckdb_logical_type type);
1333
1334/*!
1335Retrieves the internal storage type of a decimal type.
1336
1337* type: The logical type object
1338* returns: The internal type of the decimal type
1339*/
1340DUCKDB_API duckdb_type duckdb_decimal_internal_type(duckdb_logical_type type);
1341
1342/*!
1343Retrieves the internal storage type of an enum type.
1344
1345* type: The logical type object
1346* returns: The internal type of the enum type
1347*/
1348DUCKDB_API duckdb_type duckdb_enum_internal_type(duckdb_logical_type type);
1349
1350/*!
1351Retrieves the dictionary size of the enum type
1352
1353* type: The logical type object
1354* returns: The dictionary size of the enum type
1355*/
1356DUCKDB_API uint32_t duckdb_enum_dictionary_size(duckdb_logical_type type);
1357
1358/*!
1359Retrieves the dictionary value at the specified position from the enum.
1360
1361The result must be freed with `duckdb_free`
1362
1363* type: The logical type object
1364* index: The index in the dictionary
1365* returns: The string value of the enum type. Must be freed with `duckdb_free`.
1366*/
1367DUCKDB_API char *duckdb_enum_dictionary_value(duckdb_logical_type type, idx_t index);
1368
1369/*!
1370Retrieves the child type of the given list type.
1371
1372The result must be freed with `duckdb_destroy_logical_type`
1373
1374* type: The logical type object
1375* returns: The child type of the list type. Must be destroyed with `duckdb_destroy_logical_type`.
1376*/
1377DUCKDB_API duckdb_logical_type duckdb_list_type_child_type(duckdb_logical_type type);
1378
1379/*!
1380Retrieves the key type of the given map type.
1381
1382The result must be freed with `duckdb_destroy_logical_type`
1383
1384* type: The logical type object
1385* returns: The key type of the map type. Must be destroyed with `duckdb_destroy_logical_type`.
1386*/
1387DUCKDB_API duckdb_logical_type duckdb_map_type_key_type(duckdb_logical_type type);
1388
1389/*!
1390Retrieves the value type of the given map type.
1391
1392The result must be freed with `duckdb_destroy_logical_type`
1393
1394* type: The logical type object
1395* returns: The value type of the map type. Must be destroyed with `duckdb_destroy_logical_type`.
1396*/
1397DUCKDB_API duckdb_logical_type duckdb_map_type_value_type(duckdb_logical_type type);
1398
1399/*!
1400Returns the number of children of a struct type.
1401
1402* type: The logical type object
1403* returns: The number of children of a struct type.
1404*/
1405DUCKDB_API idx_t duckdb_struct_type_child_count(duckdb_logical_type type);
1406
1407/*!
1408Retrieves the name of the struct child.
1409
1410The result must be freed with `duckdb_free`
1411
1412* type: The logical type object
1413* index: The child index
1414* returns: The name of the struct type. Must be freed with `duckdb_free`.
1415*/
1416DUCKDB_API char *duckdb_struct_type_child_name(duckdb_logical_type type, idx_t index);
1417
1418/*!
1419Retrieves the child type of the given struct type at the specified index.
1420
1421The result must be freed with `duckdb_destroy_logical_type`
1422
1423* type: The logical type object
1424* index: The child index
1425* returns: The child type of the struct type. Must be destroyed with `duckdb_destroy_logical_type`.
1426*/
1427DUCKDB_API duckdb_logical_type duckdb_struct_type_child_type(duckdb_logical_type type, idx_t index);
1428
1429/*!
1430Returns the number of members that the union type has.
1431
1432* type: The logical type (union) object
1433* returns: The number of members of a union type.
1434*/
1435DUCKDB_API idx_t duckdb_union_type_member_count(duckdb_logical_type type);
1436
1437/*!
1438Retrieves the name of the union member.
1439
1440The result must be freed with `duckdb_free`
1441
1442* type: The logical type object
1443* index: The child index
1444* returns: The name of the union member. Must be freed with `duckdb_free`.
1445*/
1446DUCKDB_API char *duckdb_union_type_member_name(duckdb_logical_type type, idx_t index);
1447
1448/*!
1449Retrieves the child type of the given union member at the specified index.
1450
1451The result must be freed with `duckdb_destroy_logical_type`
1452
1453* type: The logical type object
1454* index: The child index
1455* returns: The child type of the union member. Must be destroyed with `duckdb_destroy_logical_type`.
1456*/
1457DUCKDB_API duckdb_logical_type duckdb_union_type_member_type(duckdb_logical_type type, idx_t index);
1458
1459/*!
1460Destroys the logical type and de-allocates all memory allocated for that type.
1461
1462* type: The logical type to destroy.
1463*/
1464DUCKDB_API void duckdb_destroy_logical_type(duckdb_logical_type *type);
1465
1466//===--------------------------------------------------------------------===//
1467// Data Chunk Interface
1468//===--------------------------------------------------------------------===//
1469/*!
1470Creates an empty DataChunk with the specified set of types.
1471
1472* types: An array of types of the data chunk.
1473* column_count: The number of columns.
1474* returns: The data chunk.
1475*/
1476DUCKDB_API duckdb_data_chunk duckdb_create_data_chunk(duckdb_logical_type *types, idx_t column_count);
1477
1478/*!
1479Destroys the data chunk and de-allocates all memory allocated for that chunk.
1480
1481* chunk: The data chunk to destroy.
1482*/
1483DUCKDB_API void duckdb_destroy_data_chunk(duckdb_data_chunk *chunk);
1484
1485/*!
1486Resets a data chunk, clearing the validity masks and setting the cardinality of the data chunk to 0.
1487
1488* chunk: The data chunk to reset.
1489*/
1490DUCKDB_API void duckdb_data_chunk_reset(duckdb_data_chunk chunk);
1491
1492/*!
1493Retrieves the number of columns in a data chunk.
1494
1495* chunk: The data chunk to get the data from
1496* returns: The number of columns in the data chunk
1497*/
1498DUCKDB_API idx_t duckdb_data_chunk_get_column_count(duckdb_data_chunk chunk);
1499
1500/*!
1501Retrieves the vector at the specified column index in the data chunk.
1502
1503The pointer to the vector is valid for as long as the chunk is alive.
1504It does NOT need to be destroyed.
1505
1506* chunk: The data chunk to get the data from
1507* returns: The vector
1508*/
1509DUCKDB_API duckdb_vector duckdb_data_chunk_get_vector(duckdb_data_chunk chunk, idx_t col_idx);
1510
1511/*!
1512Retrieves the current number of tuples in a data chunk.
1513
1514* chunk: The data chunk to get the data from
1515* returns: The number of tuples in the data chunk
1516*/
1517DUCKDB_API idx_t duckdb_data_chunk_get_size(duckdb_data_chunk chunk);
1518
1519/*!
1520Sets the current number of tuples in a data chunk.
1521
1522* chunk: The data chunk to set the size in
1523* size: The number of tuples in the data chunk
1524*/
1525DUCKDB_API void duckdb_data_chunk_set_size(duckdb_data_chunk chunk, idx_t size);
1526
1527//===--------------------------------------------------------------------===//
1528// Vector Interface
1529//===--------------------------------------------------------------------===//
1530/*!
1531Retrieves the column type of the specified vector.
1532
1533The result must be destroyed with `duckdb_destroy_logical_type`.
1534
1535* vector: The vector get the data from
1536* returns: The type of the vector
1537*/
1538DUCKDB_API duckdb_logical_type duckdb_vector_get_column_type(duckdb_vector vector);
1539
1540/*!
1541Retrieves the data pointer of the vector.
1542
1543The data pointer can be used to read or write values from the vector.
1544How to read or write values depends on the type of the vector.
1545
1546* vector: The vector to get the data from
1547* returns: The data pointer
1548*/
1549DUCKDB_API void *duckdb_vector_get_data(duckdb_vector vector);
1550
1551/*!
1552Retrieves the validity mask pointer of the specified vector.
1553
1554If all values are valid, this function MIGHT return NULL!
1555
1556The validity mask is a bitset that signifies null-ness within the data chunk.
1557It is a series of uint64_t values, where each uint64_t value contains validity for 64 tuples.
1558The bit is set to 1 if the value is valid (i.e. not NULL) or 0 if the value is invalid (i.e. NULL).
1559
1560Validity of a specific value can be obtained like this:
1561
1562idx_t entry_idx = row_idx / 64;
1563idx_t idx_in_entry = row_idx % 64;
1564bool is_valid = validity_mask[entry_idx] & (1 << idx_in_entry);
1565
1566Alternatively, the (slower) duckdb_validity_row_is_valid function can be used.
1567
1568* vector: The vector to get the data from
1569* returns: The pointer to the validity mask, or NULL if no validity mask is present
1570*/
1571DUCKDB_API uint64_t *duckdb_vector_get_validity(duckdb_vector vector);
1572
1573/*!
1574Ensures the validity mask is writable by allocating it.
1575
1576After this function is called, `duckdb_vector_get_validity` will ALWAYS return non-NULL.
1577This allows null values to be written to the vector, regardless of whether a validity mask was present before.
1578
1579* vector: The vector to alter
1580*/
1581DUCKDB_API void duckdb_vector_ensure_validity_writable(duckdb_vector vector);
1582
1583/*!
1584Assigns a string element in the vector at the specified location.
1585
1586* vector: The vector to alter
1587* index: The row position in the vector to assign the string to
1588* str: The null-terminated string
1589*/
1590DUCKDB_API void duckdb_vector_assign_string_element(duckdb_vector vector, idx_t index, const char *str);
1591
1592/*!
1593Assigns a string element in the vector at the specified location.
1594
1595* vector: The vector to alter
1596* index: The row position in the vector to assign the string to
1597* str: The string
1598* str_len: The length of the string (in bytes)
1599*/
1600DUCKDB_API void duckdb_vector_assign_string_element_len(duckdb_vector vector, idx_t index, const char *str,
1601 idx_t str_len);
1602
1603/*!
1604Retrieves the child vector of a list vector.
1605
1606The resulting vector is valid as long as the parent vector is valid.
1607
1608* vector: The vector
1609* returns: The child vector
1610*/
1611DUCKDB_API duckdb_vector duckdb_list_vector_get_child(duckdb_vector vector);
1612
1613/*!
1614Returns the size of the child vector of the list
1615
1616* vector: The vector
1617* returns: The size of the child list
1618*/
1619DUCKDB_API idx_t duckdb_list_vector_get_size(duckdb_vector vector);
1620
1621/*!
1622Sets the total size of the underlying child-vector of a list vector.
1623
1624* vector: The list vector.
1625* size: The size of the child list.
1626* returns: The duckdb state. Returns DuckDBError if the vector is nullptr.
1627*/
1628DUCKDB_API duckdb_state duckdb_list_vector_set_size(duckdb_vector vector, idx_t size);
1629
1630/*!
1631Sets the total capacity of the underlying child-vector of a list.
1632
1633* vector: The list vector.
1634* required_capacity: the total capacity to reserve.
1635* return: The duckdb state. Returns DuckDBError if the vector is nullptr.
1636*/
1637DUCKDB_API duckdb_state duckdb_list_vector_reserve(duckdb_vector vector, idx_t required_capacity);
1638
1639/*!
1640Retrieves the child vector of a struct vector.
1641
1642The resulting vector is valid as long as the parent vector is valid.
1643
1644* vector: The vector
1645* index: The child index
1646* returns: The child vector
1647*/
1648DUCKDB_API duckdb_vector duckdb_struct_vector_get_child(duckdb_vector vector, idx_t index);
1649
1650//===--------------------------------------------------------------------===//
1651// Validity Mask Functions
1652//===--------------------------------------------------------------------===//
1653/*!
1654Returns whether or not a row is valid (i.e. not NULL) in the given validity mask.
1655
1656* validity: The validity mask, as obtained through `duckdb_data_chunk_get_validity`
1657* row: The row index
1658* returns: true if the row is valid, false otherwise
1659*/
1660DUCKDB_API bool duckdb_validity_row_is_valid(uint64_t *validity, idx_t row);
1661
1662/*!
1663In a validity mask, sets a specific row to either valid or invalid.
1664
1665Note that `duckdb_data_chunk_ensure_validity_writable` should be called before calling `duckdb_data_chunk_get_validity`,
1666to ensure that there is a validity mask to write to.
1667
1668* validity: The validity mask, as obtained through `duckdb_data_chunk_get_validity`.
1669* row: The row index
1670* valid: Whether or not to set the row to valid, or invalid
1671*/
1672DUCKDB_API void duckdb_validity_set_row_validity(uint64_t *validity, idx_t row, bool valid);
1673
1674/*!
1675In a validity mask, sets a specific row to invalid.
1676
1677Equivalent to `duckdb_validity_set_row_validity` with valid set to false.
1678
1679* validity: The validity mask
1680* row: The row index
1681*/
1682DUCKDB_API void duckdb_validity_set_row_invalid(uint64_t *validity, idx_t row);
1683
1684/*!
1685In a validity mask, sets a specific row to valid.
1686
1687Equivalent to `duckdb_validity_set_row_validity` with valid set to true.
1688
1689* validity: The validity mask
1690* row: The row index
1691*/
1692DUCKDB_API void duckdb_validity_set_row_valid(uint64_t *validity, idx_t row);
1693
1694//===--------------------------------------------------------------------===//
1695// Table Functions
1696//===--------------------------------------------------------------------===//
1697typedef void *duckdb_table_function;
1698typedef void *duckdb_bind_info;
1699typedef void *duckdb_init_info;
1700typedef void *duckdb_function_info;
1701
1702typedef void (*duckdb_table_function_bind_t)(duckdb_bind_info info);
1703typedef void (*duckdb_table_function_init_t)(duckdb_init_info info);
1704typedef void (*duckdb_table_function_t)(duckdb_function_info info, duckdb_data_chunk output);
1705typedef void (*duckdb_delete_callback_t)(void *data);
1706
1707/*!
1708Creates a new empty table function.
1709
1710The return value should be destroyed with `duckdb_destroy_table_function`.
1711
1712* returns: The table function object.
1713*/
1714DUCKDB_API duckdb_table_function duckdb_create_table_function();
1715
1716/*!
1717Destroys the given table function object.
1718
1719* table_function: The table function to destroy
1720*/
1721DUCKDB_API void duckdb_destroy_table_function(duckdb_table_function *table_function);
1722
1723/*!
1724Sets the name of the given table function.
1725
1726* table_function: The table function
1727* name: The name of the table function
1728*/
1729DUCKDB_API void duckdb_table_function_set_name(duckdb_table_function table_function, const char *name);
1730
1731/*!
1732Adds a parameter to the table function.
1733
1734* table_function: The table function
1735* type: The type of the parameter to add.
1736*/
1737DUCKDB_API void duckdb_table_function_add_parameter(duckdb_table_function table_function, duckdb_logical_type type);
1738
1739/*!
1740Adds a named parameter to the table function.
1741
1742* table_function: The table function
1743* name: The name of the parameter
1744* type: The type of the parameter to add.
1745*/
1746DUCKDB_API void duckdb_table_function_add_named_parameter(duckdb_table_function table_function, const char *name,
1747 duckdb_logical_type type);
1748
1749/*!
1750Assigns extra information to the table function that can be fetched during binding, etc.
1751
1752* table_function: The table function
1753* extra_info: The extra information
1754* destroy: The callback that will be called to destroy the bind data (if any)
1755*/
1756DUCKDB_API void duckdb_table_function_set_extra_info(duckdb_table_function table_function, void *extra_info,
1757 duckdb_delete_callback_t destroy);
1758
1759/*!
1760Sets the bind function of the table function
1761
1762* table_function: The table function
1763* bind: The bind function
1764*/
1765DUCKDB_API void duckdb_table_function_set_bind(duckdb_table_function table_function, duckdb_table_function_bind_t bind);
1766
1767/*!
1768Sets the init function of the table function
1769
1770* table_function: The table function
1771* init: The init function
1772*/
1773DUCKDB_API void duckdb_table_function_set_init(duckdb_table_function table_function, duckdb_table_function_init_t init);
1774
1775/*!
1776Sets the thread-local init function of the table function
1777
1778* table_function: The table function
1779* init: The init function
1780*/
1781DUCKDB_API void duckdb_table_function_set_local_init(duckdb_table_function table_function,
1782 duckdb_table_function_init_t init);
1783
1784/*!
1785Sets the main function of the table function
1786
1787* table_function: The table function
1788* function: The function
1789*/
1790DUCKDB_API void duckdb_table_function_set_function(duckdb_table_function table_function,
1791 duckdb_table_function_t function);
1792
1793/*!
1794Sets whether or not the given table function supports projection pushdown.
1795
1796If this is set to true, the system will provide a list of all required columns in the `init` stage through
1797the `duckdb_init_get_column_count` and `duckdb_init_get_column_index` functions.
1798If this is set to false (the default), the system will expect all columns to be projected.
1799
1800* table_function: The table function
1801* pushdown: True if the table function supports projection pushdown, false otherwise.
1802*/
1803DUCKDB_API void duckdb_table_function_supports_projection_pushdown(duckdb_table_function table_function, bool pushdown);
1804
1805/*!
1806Register the table function object within the given connection.
1807
1808The function requires at least a name, a bind function, an init function and a main function.
1809
1810If the function is incomplete or a function with this name already exists DuckDBError is returned.
1811
1812* con: The connection to register it in.
1813* function: The function pointer
1814* returns: Whether or not the registration was successful.
1815*/
1816DUCKDB_API duckdb_state duckdb_register_table_function(duckdb_connection con, duckdb_table_function function);
1817
1818//===--------------------------------------------------------------------===//
1819// Table Function Bind
1820//===--------------------------------------------------------------------===//
1821/*!
1822Retrieves the extra info of the function as set in `duckdb_table_function_set_extra_info`
1823
1824* info: The info object
1825* returns: The extra info
1826*/
1827DUCKDB_API void *duckdb_bind_get_extra_info(duckdb_bind_info info);
1828
1829/*!
1830Adds a result column to the output of the table function.
1831
1832* info: The info object
1833* name: The name of the column
1834* type: The logical type of the column
1835*/
1836DUCKDB_API void duckdb_bind_add_result_column(duckdb_bind_info info, const char *name, duckdb_logical_type type);
1837
1838/*!
1839Retrieves the number of regular (non-named) parameters to the function.
1840
1841* info: The info object
1842* returns: The number of parameters
1843*/
1844DUCKDB_API idx_t duckdb_bind_get_parameter_count(duckdb_bind_info info);
1845
1846/*!
1847Retrieves the parameter at the given index.
1848
1849The result must be destroyed with `duckdb_destroy_value`.
1850
1851* info: The info object
1852* index: The index of the parameter to get
1853* returns: The value of the parameter. Must be destroyed with `duckdb_destroy_value`.
1854*/
1855DUCKDB_API duckdb_value duckdb_bind_get_parameter(duckdb_bind_info info, idx_t index);
1856
1857/*!
1858Retrieves a named parameter with the given name.
1859
1860The result must be destroyed with `duckdb_destroy_value`.
1861
1862* info: The info object
1863* name: The name of the parameter
1864* returns: The value of the parameter. Must be destroyed with `duckdb_destroy_value`.
1865*/
1866DUCKDB_API duckdb_value duckdb_bind_get_named_parameter(duckdb_bind_info info, const char *name);
1867
1868/*!
1869Sets the user-provided bind data in the bind object. This object can be retrieved again during execution.
1870
1871* info: The info object
1872* extra_data: The bind data object.
1873* destroy: The callback that will be called to destroy the bind data (if any)
1874*/
1875DUCKDB_API void duckdb_bind_set_bind_data(duckdb_bind_info info, void *bind_data, duckdb_delete_callback_t destroy);
1876
1877/*!
1878Sets the cardinality estimate for the table function, used for optimization.
1879
1880* info: The bind data object.
1881* is_exact: Whether or not the cardinality estimate is exact, or an approximation
1882*/
1883DUCKDB_API void duckdb_bind_set_cardinality(duckdb_bind_info info, idx_t cardinality, bool is_exact);
1884
1885/*!
1886Report that an error has occurred while calling bind.
1887
1888* info: The info object
1889* error: The error message
1890*/
1891DUCKDB_API void duckdb_bind_set_error(duckdb_bind_info info, const char *error);
1892
1893//===--------------------------------------------------------------------===//
1894// Table Function Init
1895//===--------------------------------------------------------------------===//
1896
1897/*!
1898Retrieves the extra info of the function as set in `duckdb_table_function_set_extra_info`
1899
1900* info: The info object
1901* returns: The extra info
1902*/
1903DUCKDB_API void *duckdb_init_get_extra_info(duckdb_init_info info);
1904
1905/*!
1906Gets the bind data set by `duckdb_bind_set_bind_data` during the bind.
1907
1908Note that the bind data should be considered as read-only.
1909For tracking state, use the init data instead.
1910
1911* info: The info object
1912* returns: The bind data object
1913*/
1914DUCKDB_API void *duckdb_init_get_bind_data(duckdb_init_info info);
1915
1916/*!
1917Sets the user-provided init data in the init object. This object can be retrieved again during execution.
1918
1919* info: The info object
1920* extra_data: The init data object.
1921* destroy: The callback that will be called to destroy the init data (if any)
1922*/
1923DUCKDB_API void duckdb_init_set_init_data(duckdb_init_info info, void *init_data, duckdb_delete_callback_t destroy);
1924
1925/*!
1926Returns the number of projected columns.
1927
1928This function must be used if projection pushdown is enabled to figure out which columns to emit.
1929
1930* info: The info object
1931* returns: The number of projected columns.
1932*/
1933DUCKDB_API idx_t duckdb_init_get_column_count(duckdb_init_info info);
1934
1935/*!
1936Returns the column index of the projected column at the specified position.
1937
1938This function must be used if projection pushdown is enabled to figure out which columns to emit.
1939
1940* info: The info object
1941* column_index: The index at which to get the projected column index, from 0..duckdb_init_get_column_count(info)
1942* returns: The column index of the projected column.
1943*/
1944DUCKDB_API idx_t duckdb_init_get_column_index(duckdb_init_info info, idx_t column_index);
1945
1946/*!
1947Sets how many threads can process this table function in parallel (default: 1)
1948
1949* info: The info object
1950* max_threads: The maximum amount of threads that can process this table function
1951*/
1952DUCKDB_API void duckdb_init_set_max_threads(duckdb_init_info info, idx_t max_threads);
1953
1954/*!
1955Report that an error has occurred while calling init.
1956
1957* info: The info object
1958* error: The error message
1959*/
1960DUCKDB_API void duckdb_init_set_error(duckdb_init_info info, const char *error);
1961
1962//===--------------------------------------------------------------------===//
1963// Table Function
1964//===--------------------------------------------------------------------===//
1965
1966/*!
1967Retrieves the extra info of the function as set in `duckdb_table_function_set_extra_info`
1968
1969* info: The info object
1970* returns: The extra info
1971*/
1972DUCKDB_API void *duckdb_function_get_extra_info(duckdb_function_info info);
1973/*!
1974Gets the bind data set by `duckdb_bind_set_bind_data` during the bind.
1975
1976Note that the bind data should be considered as read-only.
1977For tracking state, use the init data instead.
1978
1979* info: The info object
1980* returns: The bind data object
1981*/
1982DUCKDB_API void *duckdb_function_get_bind_data(duckdb_function_info info);
1983
1984/*!
1985Gets the init data set by `duckdb_init_set_init_data` during the init.
1986
1987* info: The info object
1988* returns: The init data object
1989*/
1990DUCKDB_API void *duckdb_function_get_init_data(duckdb_function_info info);
1991
1992/*!
1993Gets the thread-local init data set by `duckdb_init_set_init_data` during the local_init.
1994
1995* info: The info object
1996* returns: The init data object
1997*/
1998DUCKDB_API void *duckdb_function_get_local_init_data(duckdb_function_info info);
1999
2000/*!
2001Report that an error has occurred while executing the function.
2002
2003* info: The info object
2004* error: The error message
2005*/
2006DUCKDB_API void duckdb_function_set_error(duckdb_function_info info, const char *error);
2007
2008//===--------------------------------------------------------------------===//
2009// Replacement Scans
2010//===--------------------------------------------------------------------===//
2011typedef void *duckdb_replacement_scan_info;
2012
2013typedef void (*duckdb_replacement_callback_t)(duckdb_replacement_scan_info info, const char *table_name, void *data);
2014
2015/*!
2016Add a replacement scan definition to the specified database
2017
2018* db: The database object to add the replacement scan to
2019* replacement: The replacement scan callback
2020* extra_data: Extra data that is passed back into the specified callback
2021* delete_callback: The delete callback to call on the extra data, if any
2022*/
2023DUCKDB_API void duckdb_add_replacement_scan(duckdb_database db, duckdb_replacement_callback_t replacement,
2024 void *extra_data, duckdb_delete_callback_t delete_callback);
2025
2026/*!
2027Sets the replacement function name to use. If this function is called in the replacement callback,
2028 the replacement scan is performed. If it is not called, the replacement callback is not performed.
2029
2030* info: The info object
2031* function_name: The function name to substitute.
2032*/
2033DUCKDB_API void duckdb_replacement_scan_set_function_name(duckdb_replacement_scan_info info, const char *function_name);
2034
2035/*!
2036Adds a parameter to the replacement scan function.
2037
2038* info: The info object
2039* parameter: The parameter to add.
2040*/
2041DUCKDB_API void duckdb_replacement_scan_add_parameter(duckdb_replacement_scan_info info, duckdb_value parameter);
2042
2043/*!
2044Report that an error has occurred while executing the replacement scan.
2045
2046* info: The info object
2047* error: The error message
2048*/
2049DUCKDB_API void duckdb_replacement_scan_set_error(duckdb_replacement_scan_info info, const char *error);
2050
2051//===--------------------------------------------------------------------===//
2052// Appender
2053//===--------------------------------------------------------------------===//
2054
2055// Appenders are the most efficient way of loading data into DuckDB from within the C interface, and are recommended for
2056// fast data loading. The appender is much faster than using prepared statements or individual `INSERT INTO` statements.
2057
2058// Appends are made in row-wise format. For every column, a `duckdb_append_[type]` call should be made, after which
2059// the row should be finished by calling `duckdb_appender_end_row`. After all rows have been appended,
2060// `duckdb_appender_destroy` should be used to finalize the appender and clean up the resulting memory.
2061
2062// Note that `duckdb_appender_destroy` should always be called on the resulting appender, even if the function returns
2063// `DuckDBError`.
2064
2065/*!
2066Creates an appender object.
2067
2068* connection: The connection context to create the appender in.
2069* schema: The schema of the table to append to, or `nullptr` for the default schema.
2070* table: The table name to append to.
2071* out_appender: The resulting appender object.
2072* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2073*/
2074DUCKDB_API duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table,
2075 duckdb_appender *out_appender);
2076
2077/*!
2078Returns the error message associated with the given appender.
2079If the appender has no error message, this returns `nullptr` instead.
2080
2081The error message should not be freed. It will be de-allocated when `duckdb_appender_destroy` is called.
2082
2083* appender: The appender to get the error from.
2084* returns: The error message, or `nullptr` if there is none.
2085*/
2086DUCKDB_API const char *duckdb_appender_error(duckdb_appender appender);
2087
2088/*!
2089Flush the appender to the table, forcing the cache of the appender to be cleared and the data to be appended to the
2090base table.
2091
2092This should generally not be used unless you know what you are doing. Instead, call `duckdb_appender_destroy` when you
2093are done with the appender.
2094
2095* appender: The appender to flush.
2096* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2097*/
2098DUCKDB_API duckdb_state duckdb_appender_flush(duckdb_appender appender);
2099
2100/*!
2101Close the appender, flushing all intermediate state in the appender to the table and closing it for further appends.
2102
2103This is generally not necessary. Call `duckdb_appender_destroy` instead.
2104
2105* appender: The appender to flush and close.
2106* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2107*/
2108DUCKDB_API duckdb_state duckdb_appender_close(duckdb_appender appender);
2109
2110/*!
2111Close the appender and destroy it. Flushing all intermediate state in the appender to the table, and de-allocating
2112all memory associated with the appender.
2113
2114* appender: The appender to flush, close and destroy.
2115* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2116*/
2117DUCKDB_API duckdb_state duckdb_appender_destroy(duckdb_appender *appender);
2118
2119/*!
2120A nop function, provided for backwards compatibility reasons. Does nothing. Only `duckdb_appender_end_row` is required.
2121*/
2122DUCKDB_API duckdb_state duckdb_appender_begin_row(duckdb_appender appender);
2123
2124/*!
2125Finish the current row of appends. After end_row is called, the next row can be appended.
2126
2127* appender: The appender.
2128* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2129*/
2130DUCKDB_API duckdb_state duckdb_appender_end_row(duckdb_appender appender);
2131
2132/*!
2133Append a bool value to the appender.
2134*/
2135DUCKDB_API duckdb_state duckdb_append_bool(duckdb_appender appender, bool value);
2136
2137/*!
2138Append an int8_t value to the appender.
2139*/
2140DUCKDB_API duckdb_state duckdb_append_int8(duckdb_appender appender, int8_t value);
2141/*!
2142Append an int16_t value to the appender.
2143*/
2144DUCKDB_API duckdb_state duckdb_append_int16(duckdb_appender appender, int16_t value);
2145/*!
2146Append an int32_t value to the appender.
2147*/
2148DUCKDB_API duckdb_state duckdb_append_int32(duckdb_appender appender, int32_t value);
2149/*!
2150Append an int64_t value to the appender.
2151*/
2152DUCKDB_API duckdb_state duckdb_append_int64(duckdb_appender appender, int64_t value);
2153/*!
2154Append a duckdb_hugeint value to the appender.
2155*/
2156DUCKDB_API duckdb_state duckdb_append_hugeint(duckdb_appender appender, duckdb_hugeint value);
2157
2158/*!
2159Append a uint8_t value to the appender.
2160*/
2161DUCKDB_API duckdb_state duckdb_append_uint8(duckdb_appender appender, uint8_t value);
2162/*!
2163Append a uint16_t value to the appender.
2164*/
2165DUCKDB_API duckdb_state duckdb_append_uint16(duckdb_appender appender, uint16_t value);
2166/*!
2167Append a uint32_t value to the appender.
2168*/
2169DUCKDB_API duckdb_state duckdb_append_uint32(duckdb_appender appender, uint32_t value);
2170/*!
2171Append a uint64_t value to the appender.
2172*/
2173DUCKDB_API duckdb_state duckdb_append_uint64(duckdb_appender appender, uint64_t value);
2174
2175/*!
2176Append a float value to the appender.
2177*/
2178DUCKDB_API duckdb_state duckdb_append_float(duckdb_appender appender, float value);
2179/*!
2180Append a double value to the appender.
2181*/
2182DUCKDB_API duckdb_state duckdb_append_double(duckdb_appender appender, double value);
2183
2184/*!
2185Append a duckdb_date value to the appender.
2186*/
2187DUCKDB_API duckdb_state duckdb_append_date(duckdb_appender appender, duckdb_date value);
2188/*!
2189Append a duckdb_time value to the appender.
2190*/
2191DUCKDB_API duckdb_state duckdb_append_time(duckdb_appender appender, duckdb_time value);
2192/*!
2193Append a duckdb_timestamp value to the appender.
2194*/
2195DUCKDB_API duckdb_state duckdb_append_timestamp(duckdb_appender appender, duckdb_timestamp value);
2196/*!
2197Append a duckdb_interval value to the appender.
2198*/
2199DUCKDB_API duckdb_state duckdb_append_interval(duckdb_appender appender, duckdb_interval value);
2200
2201/*!
2202Append a varchar value to the appender.
2203*/
2204DUCKDB_API duckdb_state duckdb_append_varchar(duckdb_appender appender, const char *val);
2205/*!
2206Append a varchar value to the appender.
2207*/
2208DUCKDB_API duckdb_state duckdb_append_varchar_length(duckdb_appender appender, const char *val, idx_t length);
2209/*!
2210Append a blob value to the appender.
2211*/
2212DUCKDB_API duckdb_state duckdb_append_blob(duckdb_appender appender, const void *data, idx_t length);
2213/*!
2214Append a NULL value to the appender (of any type).
2215*/
2216DUCKDB_API duckdb_state duckdb_append_null(duckdb_appender appender);
2217
2218/*!
2219Appends a pre-filled data chunk to the specified appender.
2220
2221The types of the data chunk must exactly match the types of the table, no casting is performed.
2222If the types do not match or the appender is in an invalid state, DuckDBError is returned.
2223If the append is successful, DuckDBSuccess is returned.
2224
2225* appender: The appender to append to.
2226* chunk: The data chunk to append.
2227* returns: The return state.
2228*/
2229DUCKDB_API duckdb_state duckdb_append_data_chunk(duckdb_appender appender, duckdb_data_chunk chunk);
2230
2231//===--------------------------------------------------------------------===//
2232// Arrow Interface
2233//===--------------------------------------------------------------------===//
2234/*!
2235Executes a SQL query within a connection and stores the full (materialized) result in an arrow structure.
2236If the query fails to execute, DuckDBError is returned and the error message can be retrieved by calling
2237`duckdb_query_arrow_error`.
2238
2239Note that after running `duckdb_query_arrow`, `duckdb_destroy_arrow` must be called on the result object even if the
2240query fails, otherwise the error stored within the result will not be freed correctly.
2241
2242* connection: The connection to perform the query in.
2243* query: The SQL query to run.
2244* out_result: The query result.
2245* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2246*/
2247DUCKDB_API duckdb_state duckdb_query_arrow(duckdb_connection connection, const char *query, duckdb_arrow *out_result);
2248
2249/*!
2250Fetch the internal arrow schema from the arrow result.
2251
2252* result: The result to fetch the schema from.
2253* out_schema: The output schema.
2254* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2255*/
2256DUCKDB_API duckdb_state duckdb_query_arrow_schema(duckdb_arrow result, duckdb_arrow_schema *out_schema);
2257
2258/*!
2259Fetch an internal arrow array from the arrow result.
2260
2261This function can be called multiple time to get next chunks, which will free the previous out_array.
2262So consume the out_array before calling this function again.
2263
2264* result: The result to fetch the array from.
2265* out_array: The output array.
2266* returns: `DuckDBSuccess` on success or `DuckDBError` on failure.
2267*/
2268DUCKDB_API duckdb_state duckdb_query_arrow_array(duckdb_arrow result, duckdb_arrow_array *out_array);
2269
2270/*!
2271Returns the number of columns present in a the arrow result object.
2272
2273* result: The result object.
2274* returns: The number of columns present in the result object.
2275*/
2276DUCKDB_API idx_t duckdb_arrow_column_count(duckdb_arrow result);
2277
2278/*!
2279Returns the number of rows present in a the arrow result object.
2280
2281* result: The result object.
2282* returns: The number of rows present in the result object.
2283*/
2284DUCKDB_API idx_t duckdb_arrow_row_count(duckdb_arrow result);
2285
2286/*!
2287Returns the number of rows changed by the query stored in the arrow result. This is relevant only for
2288INSERT/UPDATE/DELETE queries. For other queries the rows_changed will be 0.
2289
2290* result: The result object.
2291* returns: The number of rows changed.
2292*/
2293DUCKDB_API idx_t duckdb_arrow_rows_changed(duckdb_arrow result);
2294
2295/*!
2296Returns the error message contained within the result. The error is only set if `duckdb_query_arrow` returns
2297`DuckDBError`.
2298
2299The error message should not be freed. It will be de-allocated when `duckdb_destroy_arrow` is called.
2300
2301* result: The result object to fetch the nullmask from.
2302* returns: The error of the result.
2303*/
2304DUCKDB_API const char *duckdb_query_arrow_error(duckdb_arrow result);
2305
2306/*!
2307Closes the result and de-allocates all memory allocated for the arrow result.
2308
2309* result: The result to destroy.
2310*/
2311DUCKDB_API void duckdb_destroy_arrow(duckdb_arrow *result);
2312
2313//===--------------------------------------------------------------------===//
2314// Threading Information
2315//===--------------------------------------------------------------------===//
2316typedef void *duckdb_task_state;
2317
2318/*!
2319Execute DuckDB tasks on this thread.
2320
2321Will return after `max_tasks` have been executed, or if there are no more tasks present.
2322
2323* database: The database object to execute tasks for
2324* max_tasks: The maximum amount of tasks to execute
2325*/
2326DUCKDB_API void duckdb_execute_tasks(duckdb_database database, idx_t max_tasks);
2327
2328/*!
2329Creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until
2330 duckdb_finish_execution is called on the state.
2331
2332duckdb_destroy_state should be called on the result in order to free memory.
2333
2334* database: The database object to create the task state for
2335* returns: The task state that can be used with duckdb_execute_tasks_state.
2336*/
2337DUCKDB_API duckdb_task_state duckdb_create_task_state(duckdb_database database);
2338
2339/*!
2340Execute DuckDB tasks on this thread.
2341
2342The thread will keep on executing tasks forever, until duckdb_finish_execution is called on the state.
2343Multiple threads can share the same duckdb_task_state.
2344
2345* state: The task state of the executor
2346*/
2347DUCKDB_API void duckdb_execute_tasks_state(duckdb_task_state state);
2348
2349/*!
2350Execute DuckDB tasks on this thread.
2351
2352The thread will keep on executing tasks until either duckdb_finish_execution is called on the state,
2353max_tasks tasks have been executed or there are no more tasks to be executed.
2354
2355Multiple threads can share the same duckdb_task_state.
2356
2357* state: The task state of the executor
2358* max_tasks: The maximum amount of tasks to execute
2359* returns: The amount of tasks that have actually been executed
2360*/
2361DUCKDB_API idx_t duckdb_execute_n_tasks_state(duckdb_task_state state, idx_t max_tasks);
2362
2363/*!
2364Finish execution on a specific task.
2365
2366* state: The task state to finish execution
2367*/
2368DUCKDB_API void duckdb_finish_execution(duckdb_task_state state);
2369
2370/*!
2371Check if the provided duckdb_task_state has finished execution
2372
2373* state: The task state to inspect
2374* returns: Whether or not duckdb_finish_execution has been called on the task state
2375*/
2376DUCKDB_API bool duckdb_task_state_is_finished(duckdb_task_state state);
2377
2378/*!
2379Destroys the task state returned from duckdb_create_task_state.
2380
2381Note that this should not be called while there is an active duckdb_execute_tasks_state running
2382on the task state.
2383
2384* state: The task state to clean up
2385*/
2386DUCKDB_API void duckdb_destroy_task_state(duckdb_task_state state);
2387
2388/*!
2389Returns true if execution of the current query is finished.
2390
2391* con: The connection on which to check
2392*/
2393DUCKDB_API bool duckdb_execution_is_finished(duckdb_connection con);
2394
2395//===--------------------------------------------------------------------===//
2396// Streaming Result Interface
2397//===--------------------------------------------------------------------===//
2398
2399/*!
2400Fetches a data chunk from the (streaming) duckdb_result. This function should be called repeatedly until the result is
2401exhausted.
2402
2403The result must be destroyed with `duckdb_destroy_data_chunk`.
2404
2405This function can only be used on duckdb_results created with 'duckdb_pending_prepared_streaming'
2406
2407If this function is used, none of the other result functions can be used and vice versa (i.e. this function cannot be
2408mixed with the legacy result functions or the materialized result functions).
2409
2410It is not known beforehand how many chunks will be returned by this result.
2411
2412* result: The result object to fetch the data chunk from.
2413* returns: The resulting data chunk. Returns `NULL` if the result has an error.
2414*/
2415DUCKDB_API duckdb_data_chunk duckdb_stream_fetch_chunk(duckdb_result result);
2416
2417#ifdef __cplusplus
2418}
2419#endif
2420