duckdb-ffi-2.0.0.0: cbits/duckdb_v2.h
//===----------------------------------------------------------------------===//
//
// DuckDB
//
//
//===----------------------------------------------------------------------===//
//
// !!!!!!!
// WARNING: this file is autogenerated, manual changes will be overwritten
// !!!!!!!
#pragma once
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
#ifndef DUCKDB_C_API
#ifdef _WIN32
#ifdef DUCKDB_STATIC_BUILD
#define DUCKDB_C_API
#elif defined(DUCKDB_BUILD_LIBRARY) && !defined(DUCKDB_BUILD_LOADABLE_EXTENSION)
#define DUCKDB_C_API __declspec(dllexport)
#else
#define DUCKDB_C_API __declspec(dllimport)
#endif
#else
#if defined(__GNUC__) || defined(__clang__)
#define DUCKDB_C_API __attribute__((visibility("default")))
#else
#define DUCKDB_C_API
#endif
#endif
#endif
#ifndef DUCKDB_EXTENSION_API
#ifdef _WIN32
#ifdef DUCKDB_STATIC_BUILD
#define DUCKDB_EXTENSION_API
#else
#define DUCKDB_EXTENSION_API __declspec(dllexport)
#endif
#else
#if defined(__GNUC__) || defined(__clang__)
#define DUCKDB_EXTENSION_API __attribute__((visibility("default")))
#else
#define DUCKDB_EXTENSION_API
#endif
#endif
#endif
#if defined(__GNUC__) || defined(__clang__)
#define DUCKDB_DEPRECATED \
__attribute__((deprecated("This function is deprecated and will be removed in a future version.")))
#elif defined(_MSC_VER)
#define DUCKDB_DEPRECATED __declspec(deprecated("This function is deprecated and will be removed in a future version."))
#else
#define DUCKDB_DEPRECATED
#endif
//===--------------------------------------------------------------------===//
// API version
//===--------------------------------------------------------------------===//
//! The API version this translation unit targets. Define all three to compile against an
//! older surface than the one this header describes.
#if !defined(DUCKDB_V2_API_VERSION_MAJOR) && !defined(DUCKDB_V2_API_VERSION_MINOR) && \
!defined(DUCKDB_V2_API_VERSION_PATCH)
#define DUCKDB_V2_API_VERSION_MAJOR 2
#define DUCKDB_V2_API_VERSION_MINOR 0
#define DUCKDB_V2_API_VERSION_PATCH 0
#elif !(defined(DUCKDB_V2_API_VERSION_MAJOR) && defined(DUCKDB_V2_API_VERSION_MINOR) && \
defined(DUCKDB_V2_API_VERSION_PATCH))
#error "define all or none of the DUCKDB_V2_API_VERSION_MAJOR / _MINOR / _PATCH macros"
#endif
//! True when the targeted version is x.y.z or newer.
#define DUCKDB_V2_API_VERSION_AT_LEAST(x, y, z) \
(DUCKDB_V2_API_VERSION_MAJOR > (x) || \
(DUCKDB_V2_API_VERSION_MAJOR == (x) && \
(DUCKDB_V2_API_VERSION_MINOR > (y) || \
(DUCKDB_V2_API_VERSION_MINOR == (y) && DUCKDB_V2_API_VERSION_PATCH >= (z)))))
//! True when the targeted version is older than x.y.z.
#define DUCKDB_V2_API_VERSION_BELOW(x, y, z) (!DUCKDB_V2_API_VERSION_AT_LEAST((x), (y), (z)))
//===--------------------------------------------------------------------===//
// Surface switches
//===--------------------------------------------------------------------===//
//! Set to 1 to compile the deprecated surface, 0 to omit it. Defaults from the
//! older DUCKDB_API_NO_DEPRECATED macro when that is what the consumer defines.
#if !defined(DUCKDB_V2_API_ALLOW_DEPRECATED)
#ifdef DUCKDB_API_NO_DEPRECATED
#define DUCKDB_V2_API_ALLOW_DEPRECATED 0
#else
#define DUCKDB_V2_API_ALLOW_DEPRECATED 1
#endif
#endif
//! Set to 1 to compile the unstable surface, 0 to omit it. Defaults from the
//! older DUCKDB_EXTENSION_API_VERSION_UNSTABLE macro when that is what the consumer defines.
#if !defined(DUCKDB_V2_API_ALLOW_UNSTABLE)
#ifdef DUCKDB_EXTENSION_API_VERSION_UNSTABLE
#define DUCKDB_V2_API_ALLOW_UNSTABLE 1
#else
#define DUCKDB_V2_API_ALLOW_UNSTABLE 0
#endif
#endif
//! The unstable surface is not a promise, so it is not part of any released
//! version: its constructs may change shape or vanish. Targeting an older version
//! while opting into it would hand back today's shapes under names that version
//! never promised, so the two are mutually exclusive.
#if DUCKDB_V2_API_ALLOW_UNSTABLE && !DUCKDB_V2_API_VERSION_AT_LEAST(2, 0, 0)
#error "the unstable surface requires targeting the newest API version"
#endif
//===--------------------------------------------------------------------===//
// General type definitions
//===--------------------------------------------------------------------===//
// Arrow C Data Interface (https://arrow.apache.org/docs/format/CDataInterface.html).
// Defined here so this header is self-contained: a binding author can allocate
// and fill an ArrowSchema / ArrowArray with only this header. Guarded by the
// standard ARROW_C_DATA_INTERFACE / ARROW_C_STREAM_INTERFACE macros that
// pyarrow / nanoarrow / arrow also use, so these definitions coexist with a
// consumer's own Arrow headers (first definition wins; the layouts are
// byte-identical by spec).
#ifndef ARROW_C_DATA_INTERFACE
#define ARROW_C_DATA_INTERFACE
#define ARROW_FLAG_DICTIONARY_ORDERED 1
#define ARROW_FLAG_NULLABLE 2
#define ARROW_FLAG_MAP_KEYS_SORTED 4
struct ArrowSchema {
const char *format;
const char *name;
const char *metadata;
int64_t flags;
int64_t n_children;
struct ArrowSchema **children;
struct ArrowSchema *dictionary;
void (*release)(struct ArrowSchema *);
void *private_data;
};
struct ArrowArray {
int64_t length;
int64_t null_count;
int64_t offset;
int64_t n_buffers;
int64_t n_children;
const void **buffers;
struct ArrowArray **children;
struct ArrowArray *dictionary;
void (*release)(struct ArrowArray *);
void *private_data;
};
#endif
#ifndef ARROW_C_STREAM_INTERFACE
#define ARROW_C_STREAM_INTERFACE
struct ArrowArrayStream {
int (*get_schema)(struct ArrowArrayStream *, struct ArrowSchema *out);
int (*get_next)(struct ArrowArrayStream *, struct ArrowArray *out);
const char *(*get_last_error)(struct ArrowArrayStream *);
void (*release)(struct ArrowArrayStream *);
void *private_data;
};
#endif
typedef uint64_t idx_t;
typedef struct _duckdb_extension_info *duckdb_v2_extension_handle;
/* ============================================================================
* MODULE: common
* ============================================================================ */
/* --- Enums for common --- */
/*!
* The order guarantee a producer of rows makes about its output, which decides whether the rows it produces must be
* kept in order downstream.
*/
typedef enum DUCKDB_V2_ORDER_PRESERVATION {
/*!
* The rows have no meaningful order. The engine may reorder them freely, and consumers that otherwise keep
* insertion order, such as query results, INSERT and COPY, run in parallel without ordering them.
*/
DUCKDB_V2_ORDER_PRESERVATION_NO_ORDER = 0,
/*!
* The rows are produced in insertion order, which the engine keeps unless the `preserve_insertion_order` setting is
* disabled.
*/
DUCKDB_V2_ORDER_PRESERVATION_INSERTION_ORDER = 1,
/*!
* The rows are produced in an order that must be kept, as if sorted by an `ORDER BY`, even when the
* `preserve_insertion_order` setting is disabled.
*/
DUCKDB_V2_ORDER_PRESERVATION_FIXED_ORDER = 2,
DUCKDB_V2_ORDER_PRESERVATION_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_ORDER_PRESERVATION;
/* --- Struct forward declarations for common --- */
typedef struct duckdb_v2_str duckdb_v2_str;
typedef struct duckdb_v2_bytes duckdb_v2_bytes;
typedef struct duckdb_v2_opaque duckdb_v2_opaque;
/* --- Types for common --- */
/*!
* An opaque, owned handle to the V2 environment: the required root through which instance handles are created. All
* instances under one environment share an instance cache, so file-level conflicts — the same database file opened
* twice — are detected across them. Destroying the environment refuses with ERROR_RESOURCE_IN_USE while any instance
* created through it is still alive; destroy those first.
*/
typedef struct _duckdb_v2_environment {
void *internal_ptr;
} * duckdb_v2_environment_handle;
/*!
* An opaque, owned handle to a DuckDB database instance: a buffer pool, a scheduler, a set of GLOBAL settings, and the
* databases attached to it. Created empty by `duckdb_v2_instance_create()`; databases are attached with
* `duckdb_v2_instance_attach()`, made the default with `duckdb_v2_instance_set_default()`, and detached with
* `duckdb_v2_instance_detach()`. Always destroy via `duckdb_v2_instance_destroy()`.
*/
typedef struct _duckdb_v2_instance {
void *internal_ptr;
} * duckdb_v2_instance_handle;
/*!
* An opaque, owned handle to a DuckDB connection: a session on a database instance with its own LOCAL settings and
* transaction state. Always destroy via `duckdb_v2_connection_destroy()`.
*/
typedef struct _duckdb_v2_connection {
void *internal_ptr;
} * duckdb_v2_connection_handle;
/*!
* A borrowed handle to the scope config options are read from and written at. Taken from an instance
* (`duckdb_v2_instance_get_config()`), a connection (`duckdb_v2_connection_get_config()`) or a context
* (`duckdb_v2_context_get_config()`), and valid for as long as its source is; the caller never destroys it. An
* instance's config is the GLOBAL scope alone; a connection's or a context's config reads that client's cascade (its
* SESSION value, else the GLOBAL one, else the default) and writes at any scope the option supports.
*/
typedef struct _duckdb_v2_config {
void *internal_ptr;
} * duckdb_v2_config_handle;
/*!
* An opaque, owned, read-only descriptor of a single config option as registered on an instance: its canonical name,
* default value, description, the scopes it may be written at, and aliases. It carries no current value: read that with
* the *_get_option_value functions, and write it with the *_set_option functions. Returned by the *_get_option_by_name
* and *_get_option_by_index functions; the caller always destroys it via `duckdb_v2_option_destroy()`.
*/
typedef struct _duckdb_v2_option {
void *internal_ptr;
} * duckdb_v2_option_handle;
//! Opaque detail for a failed call; destroy with `duckdb_v2_error_info_destroy()`.
typedef struct _duckdb_v2_error_info {
void *internal_ptr;
} * duckdb_v2_error_info_handle;
/*!
* An opaque, owned handle to a logical type. Carries a type id plus any kind-specific metadata: decimal width and
* scale, enum dictionary, list / array / struct / map / union child types, alias. A type is read-only once constructed;
* instances arrive from a query result schema, or from one of the create_type_* constructors. Always destroy via
* `duckdb_v2_logical_type_destroy()`. Borrowed strings returned by the getters are valid only until then.
*/
typedef struct _duckdb_v2_logical_type {
void *internal_ptr;
} * duckdb_v2_logical_type_handle;
/*!
* An opaque, owned handle to a single SQL value: a logical type plus a typed payload. Always destroy via
* `duckdb_v2_value_destroy()`. The string returned by `duckdb_v2_value_get_varchar()` / `duckdb_v2_value_get_blob()` is
* borrowed and valid only until then. That holds for BIGNUM too, where what is borrowed is the opaque storage form;
* `duckdb_v2_bignum_decode()` translates it into a magnitude and a sign flag, writing into a buffer the caller
* supplies.
*/
typedef struct _duckdb_v2_value {
void *internal_ptr;
} * duckdb_v2_value_handle;
/*!
* An opaque, owned handle to the streaming result of a query. Carries the schema (column names and logical types), the
* statement type, and the result type from prepare time; row data is produced incrementally by stepping
* (`duckdb_v2_result_step()`) or draining (`duckdb_v2_result_fetch_chunk()`). Single consumer: step from one thread at
* a time.
*
* A result is a cursor on the connection's execution, not a box of data. While its statement runs — at most until it is
* finished, cancelled, errored, or destroyed — the connection refuses new queries with ERROR_RESOURCE_IN_USE, and the
* query's transaction stays open, deferring version cleanup and checkpointing, so drain or destroy it promptly.
* Side-effecting statements (PRAGMA, ALTER, ...) take effect only once the result is drained. Always destroy via
* `duckdb_v2_result_destroy()`, which is safe even on a partially consumed stream.
*/
typedef struct _duckdb_v2_result {
void *internal_ptr;
} * duckdb_v2_result_handle;
/*!
* An opaque, owned handle to a data chunk: a set of vectors of equal logical length plus a cardinality (row count).
*
* A data chunk is the main "unit of execution" in DuckDB, and the main unit of data transfer in the API. It may be
* owned or borrowed, depending on the context.
*/
typedef struct _duckdb_v2_data_chunk {
void *internal_ptr;
} * duckdb_v2_data_chunk_handle;
/*!
* A borrowed handle to a vector within a data chunk, carrying a part of a column's values. Vectors are always borrowed
* from a data chunk, and are valid only as long as their parent data chunk is alive.
*/
typedef struct _duckdb_v2_vector {
void *internal_ptr;
} * duckdb_v2_vector_handle;
/*!
* A borrowed handle to a "arena allocator".
*
* Bytes handed out by `duckdb_v2_arena_allocate()` share the same lifetime as the arena itself.
* `duckdb_v2_vector_get_arena()` yields the arena backing the out-of-line bytes of non-inlined VARCHAR / BLOB / BIT /
* BIGNUM values, valid until the owning vector is flattened, reallocated, or destroyed.
*/
typedef struct _duckdb_v2_arena {
void *internal_ptr;
} * duckdb_v2_arena_handle;
/*!
* A borrowed handle to a client context: a connection seen from inside DuckDB. Handed out within DuckDB-managed scopes
* — function bind / init / exec callbacks, replacement scans, and the extension entrypoint — and valid only for the
* duration of that scope; the caller never destroys it. Within that scope a transaction is already active. A context
* reaches the same capabilities a connection does, through `duckdb_v2_context_get_factory()`,
* `duckdb_v2_context_get_config()`, `duckdb_v2_context_get_file_system()` and `duckdb_v2_context_log()`.
*/
typedef struct _duckdb_v2_context {
void *internal_ptr;
} * duckdb_v2_context_handle;
/*!
* A borrowed handle to the scope values, types, data chunks and column data collections are created in. Taken from an
* instance (`duckdb_v2_instance_get_factory()`), a connection (`duckdb_v2_connection_get_factory()`) or a context
* (`duckdb_v2_context_get_factory()`), and valid for as long as its source is; the caller never destroys it. A factory
* resolves in the scope of its source: a connection's or a context's factory reaches the catalog and the client's
* settings, while an instance's factory knows only the built-in types and casts, with default settings, and refuses
* anything that needs a catalog.
*/
typedef struct _duckdb_v2_factory {
void *internal_ptr;
} * duckdb_v2_factory_handle;
/*!
* An entry in a selection-vector.
*
* A selection-vector is a "dictionary" represented as an array of indices (sel_t's) mapping "logical" row indices to
* the "physical" offsets in a vectors primary data buffer. Used by "dictionary vectors" to represent a filtered or
* "sparse" view of the vector's data.
*/
typedef uint32_t duckdb_v2_sel_t;
//! VARCHAR storage. The bytes must contain valid UTF-8. Read the transparent bytes fields directly.
typedef duckdb_v2_bytes duckdb_v2_varchar_t;
//! BLOB storage. Read the transparent bytes fields directly.
typedef duckdb_v2_bytes duckdb_v2_blob_t;
//! BIT storage. Byte 0 is the padding-bit count, bytes 1.. the data.
typedef duckdb_v2_bytes duckdb_v2_bit_t;
//! BIGNUM storage. Decode via `duckdb_v2_bignum_decode()`.
typedef duckdb_v2_bytes duckdb_v2_bignum_t;
/*!
* A borrowed name view with the same layout as str, marking a string DuckDB treats as a SQL identifier: one matched
* case-insensitively. Compare two identifiers case-insensitively rather than byte for byte, and render one into SQL
* through the identifier-quoting entry point rather than embedding it raw. The catalog preserves casing; some
* registries (config settings) canonicalize to lowercase.
*
* An identifier passed into the API must be valid UTF-8; otherwise the call fails with `ERROR_INPUT_INVALID`.
*/
typedef duckdb_v2_str duckdb_v2_identifier_t;
/* --- Constants for common --- */
//! Inline cutoff for `bytes` storage: a value of at most this many bytes is stored inline.
#define DUCKDB_V2_BYTES_INLINE_LENGTH 12
/* --- Function pointer typedefs for common --- */
/*!
* Receives text produced by DuckDB
*
* Invoked exactly once per producing call, with the complete text in a single view.
*
* The view is borrowed for the duration of the call only. Copy what you need before returning, and do not retain `text`
* or `text->ptr`. The bytes are NOT guaranteed to be null-terminated.
*
* `err` is a live error slot, never NULL. Populate it with `duckdb_v2_error_info_set_code()` /
* `duckdb_v2_error_info_set_text()` to signal failure to DuckDB. Do not destroy it yourself.
*
* The sink runs inside DuckDB's call frame: it must not throw or unwind across the boundary, and it must not re-enter
* the API on the handle being operated on.
*/
typedef void (*duckdb_v2_text_sink_fn)(const duckdb_v2_str *text, void *user_data, duckdb_v2_error_info_handle *err);
/*!
* Compares two caller-defined resources for equality.
*
* Invoked when DuckDB needs to compare two opaque handles. The callback is responsible for interpreting the pointers
* and comparing the underlying resources. Return true if they are equal, false otherwise.
*
* The callback runs inside DuckDB's call frame: it must not throw or unwind across the boundary, and it must not
* re-enter the API on the handle being operated on.
*/
typedef bool (*duckdb_v2_opaque_equals_fn)(void *a, void *b);
/*!
* Destroys a caller-defined resource.
*
* Invoked when DuckDB needs to destroy an opaque handle. The callback is responsible for interpreting the pointer and
* freeing the underlying resource.
*
* The callback runs inside DuckDB's call frame: it must not throw or unwind across the boundary, and it must not
* re-enter the API on the handle being operated on.
*/
typedef void (*duckdb_v2_opaque_destroy_fn)(void *data);
/* --- Functions for common --- */
/* --- Struct definitions for common --- */
/*!
* A borrowed, length-delimited string view: `ptr` points at `len` bytes of character data. The bytes are NOT guaranteed
* to be null-terminated and may contain interior null bytes, so always honor `len` rather than scanning for a
* terminator. The view never owns its bytes; the function that produced it documents how long they live (typically
* "valid until the owning handle is destroyed"). `{NULL, 0}` is the canonical empty view, and `ptr` must not be
* dereferenced when `len` is 0. Not to be confused with `bytes`, the transparent 16-byte *storage* format for a
* variable-size value in a vector.
*
* Functions take an input view as a `const str *`, which must not be NULL; a NULL pointer, or a view whose `ptr` is
* NULL while `len` is nonzero, fails with ERROR_INPUT_INVALID. Point at a `{NULL, 0}` view to pass an empty string.
*
* Text inputs, such as VARCHAR values and names, must contain valid UTF-8. The caller is responsible for ensuring this;
* API functions do not necessarily validate the input. Binary inputs, such as BLOB values, do not require valid UTF-8.
*/
struct duckdb_v2_str {
const char *ptr;
idx_t len;
};
/*!
* 16-byte storage for a variable-size, byte-backed value: VARCHAR, BLOB, BIT, or BIGNUM. The bytes are inlined when the
* length is at most BYTES_INLINE_LENGTH, in value.inlined.inlined; otherwise value.pointer.ptr holds them and
* value.pointer.prefix repeats the first
* 4. The union is transparent, so read the fields directly. VARCHAR and
* BLOB carry no further encoding; BIT and BIGNUM do. For BIT, byte 0 is the padding-bit count and bytes 1.. are the
* data; BIGNUM is decoded via `duckdb_v2_bignum_decode()`.
*/
struct duckdb_v2_bytes {
union {
struct {
uint32_t length;
char prefix[4];
char *ptr;
} pointer;
struct {
uint32_t length;
char inlined[12];
} inlined;
} value;
};
/*!
* An opaque, owned handle to a caller-defined resource. Bundles the pointer with optional callbacks that destroy and
* compare the resource.
*/
struct duckdb_v2_opaque {
void *ptr;
duckdb_v2_opaque_destroy_fn destroy;
duckdb_v2_opaque_equals_fn equals;
};
/* ============================================================================
* MODULE: errors
* ============================================================================ */
/* --- Enums for errors --- */
//! Error codes for API calls.
typedef enum DUCKDB_V2_ERROR {
//! Success.
DUCKDB_V2_ERROR_NONE = 0,
//! Generic API error.
DUCKDB_V2_ERROR_API = 1,
//! The specified file could not be found.
DUCKDB_V2_ERROR_IO_FILE_NOT_FOUND = 1001,
//! Failed to read from the storage device.
DUCKDB_V2_ERROR_IO_READ_FAILURE = 1002,
//! Unexpected end of file reached.
DUCKDB_V2_ERROR_IO_EOF = 1003,
//! A generic I/O error occurred while reading or writing data.
DUCKDB_V2_ERROR_IO_GENERAL = 1004,
//! A network-level failure occurred during an I/O operation.
DUCKDB_V2_ERROR_IO_NETWORK = 1005,
//! An HTTP request issued by the database failed.
DUCKDB_V2_ERROR_IO_HTTP = 1006,
//! General invalid input error.
DUCKDB_V2_ERROR_INPUT_INVALID = 2001,
//! A specific function parameter is malformed.
DUCKDB_V2_ERROR_INPUT_PARAMETER_INVALID = 2002,
//! A provided value is outside the acceptable range.
DUCKDB_V2_ERROR_INPUT_OUT_OF_RANGE = 2003,
//! An object exceeded its maximum permitted size.
DUCKDB_V2_ERROR_INPUT_OBJECT_SIZE = 2004,
/*!
* The metadata asked for is known only once execution binds the statement that produces it, because the statement
* expands into several. Step the result and ask again.
*/
DUCKDB_V2_ERROR_INPUT_METADATA_DEFERRED = 2005,
//! The requested resource is already in use.
DUCKDB_V2_ERROR_RESOURCE_IN_USE = 3001,
//! An allocation failed because the system ran out of memory.
DUCKDB_V2_ERROR_RESOURCE_OUT_OF_MEMORY = 3002,
//! A connection-level failure occurred (e.g. the connection has been closed or invalidated).
DUCKDB_V2_ERROR_RESOURCE_CONNECTION = 3003,
//! An operation failed because of an unresolved dependency between catalog objects.
DUCKDB_V2_ERROR_RESOURCE_DEPENDENCY = 3004,
//! An extension required by the operation is not loaded.
DUCKDB_V2_ERROR_RESOURCE_MISSING_EXTENSION = 3005,
//! Autoloading an extension failed.
DUCKDB_V2_ERROR_RESOURCE_AUTOLOAD = 3006,
//! A value could not be converted to the requested type.
DUCKDB_V2_ERROR_TYPE_CONVERSION = 4001,
//! An unknown or unsupported type was encountered.
DUCKDB_V2_ERROR_TYPE_UNKNOWN = 4002,
//! A type was used in a context where it is not valid.
DUCKDB_V2_ERROR_TYPE_INVALID = 4003,
//! Two values or expressions have incompatible types.
DUCKDB_V2_ERROR_TYPE_MISMATCH = 4004,
//! A decimal value is out of range or otherwise invalid.
DUCKDB_V2_ERROR_TYPE_DECIMAL = 4005,
//! Division by zero was attempted.
DUCKDB_V2_ERROR_TYPE_DIVIDE_BY_ZERO = 4006,
//! The query could not be parsed.
DUCKDB_V2_ERROR_QUERY_PARSER = 5001,
//! The query contains a syntax error.
DUCKDB_V2_ERROR_QUERY_SYNTAX = 5002,
//! Binding the query against the catalog failed (e.g. unknown column or table).
DUCKDB_V2_ERROR_QUERY_BINDER = 5003,
//! The query could not be translated into a logical plan.
DUCKDB_V2_ERROR_QUERY_PLANNER = 5004,
//! An error occurred during query optimization.
DUCKDB_V2_ERROR_QUERY_OPTIMIZER = 5005,
//! An expression in the query is invalid or could not be evaluated.
DUCKDB_V2_ERROR_QUERY_EXPRESSION = 5006,
//! An error occurred while executing the physical plan.
DUCKDB_V2_ERROR_QUERY_EXECUTOR = 5007,
//! The task scheduler reported an error while running the query.
DUCKDB_V2_ERROR_QUERY_SCHEDULER = 5008,
//! The requested feature or operation is not implemented.
DUCKDB_V2_ERROR_QUERY_NOT_IMPLEMENTED = 5009,
//! A prepared-statement parameter has not been bound to a value.
DUCKDB_V2_ERROR_QUERY_PARAMETER_NOT_RESOLVED = 5010,
//! A prepared-statement parameter was used in a position where it is not allowed.
DUCKDB_V2_ERROR_QUERY_PARAMETER_NOT_ALLOWED = 5011,
//! A catalog operation failed (e.g. object not found or already exists).
DUCKDB_V2_ERROR_DATABASE_CATALOG = 6001,
//! A transaction-level error occurred (e.g. conflict or aborted transaction).
DUCKDB_V2_ERROR_DATABASE_TRANSACTION = 6002,
//! A constraint (primary key, unique, foreign key, NOT NULL, check) was violated.
DUCKDB_V2_ERROR_DATABASE_CONSTRAINT = 6003,
//! An index operation failed.
DUCKDB_V2_ERROR_DATABASE_INDEX = 6004,
//! A sequence operation failed (e.g. overflow or invalid usage).
DUCKDB_V2_ERROR_DATABASE_SEQUENCE = 6005,
//! An error related to catalog statistics occurred.
DUCKDB_V2_ERROR_DATABASE_STATISTICS = 6006,
//! Serializing or deserializing a database object failed.
DUCKDB_V2_ERROR_DATABASE_SERIALIZATION = 6007,
//! A settings-related error occurred (e.g. setting an unknown option).
DUCKDB_V2_ERROR_CONFIGURATION_SETTINGS = 7001,
//! The database configuration is invalid.
DUCKDB_V2_ERROR_CONFIGURATION_INVALID = 7002,
//! The operation is not permitted under the current configuration.
DUCKDB_V2_ERROR_CONFIGURATION_PERMISSION = 7003,
//! An internal invariant was violated; this indicates a bug in DuckDB.
DUCKDB_V2_ERROR_RUNTIME_INTERNAL = 8001,
//! A fatal error occurred; the database is no longer usable.
DUCKDB_V2_ERROR_RUNTIME_FATAL = 8002,
//! The operation was interrupted (e.g. by a cancel request).
DUCKDB_V2_ERROR_RUNTIME_INTERRUPT = 8003,
//! A required pointer was unexpectedly null.
DUCKDB_V2_ERROR_RUNTIME_NULL_POINTER = 8004,
DUCKDB_V2_ERROR_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_ERROR;
/* --- Struct forward declarations for errors --- */
/* --- Types for errors --- */
/* --- Constants for errors --- */
/* --- Function pointer typedefs for errors --- */
/* --- Functions for errors --- */
/* --- Struct definitions for errors --- */
/* ============================================================================
* MODULE: function properties
* ============================================================================ */
/* --- Enums for function properties --- */
/*!
* Identifies a configurable function property. Pass one of these to `duckdb_v2_scalar_function_set_property()` or
* `duckdb_v2_aggregate_function_set_property()` together with a matching `DUCKDB_V2_FUNCTION_PROPERTY_VALUE`. The high
* byte is the function-type group: COMMON (`0x01xxxx`) keys apply to all function types, while group-specific keys
* (e.g. aggregate `0x03xxxx`) are only valid for that function type and are rejected with an error otherwise.
*/
typedef enum DUCKDB_V2_FUNCTION_PROPERTY_KEY {
/*!
* How stable/deterministic the function's result is across rows and queries. Accepts the
* `FUNCTION_PROPERTY_STABILITY_*` values. Defaults to `CONSISTENT`.
*/
DUCKDB_V2_FUNCTION_PROPERTY_STABILITY = 65536,
/*!
* Whether the function handles NULL inputs itself. Accepts the `FUNCTION_PROPERTY_NULL_HANDLING_*` values. Defaults
* to `DEFAULT` (NULL in, NULL out).
*/
DUCKDB_V2_FUNCTION_PROPERTY_NULL_HANDLING = 65792,
/*!
* Whether the function can raise a runtime error. Accepts the `FUNCTION_PROPERTY_FALLIBILITY_*` values. Functions
* created through this API default to `FALLIBLE`, since their callbacks can report errors.
*/
DUCKDB_V2_FUNCTION_PROPERTY_FALLIBILITY = 66048,
/*!
* How the function interacts with collations on its arguments. Accepts the `FUNCTION_PROPERTY_COLLATION_HANDLING_*`
* values. Defaults to `PROPAGATE`.
*/
DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING = 66304,
/*!
* Aggregate only. Whether the aggregate's result depends on the order in which rows are aggregated. Accepts the
* `FUNCTION_PROPERTY_AGG_ORDER_DEPENDENT_*` values. Defaults to `YES`.
*/
DUCKDB_V2_FUNCTION_PROPERTY_AGG_ORDER_DEPENDENT = 196608,
/*!
* Aggregate only. Whether the aggregate's result is affected by a DISTINCT modifier. Accepts the
* `FUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT_*` values. Defaults to `YES`.
*/
DUCKDB_V2_FUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT = 196864,
DUCKDB_V2_FUNCTION_PROPERTY_KEY_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_FUNCTION_PROPERTY_KEY;
/*!
* A value for a `DUCKDB_V2_FUNCTION_PROPERTY_KEY`. Each key owns a 256-value block: a value `V` is valid for key `K`
* iff `(V & 0xFFFF00) == K`, and shares the key's function-type group (`V & 0xFF0000`) in its high byte. Passing a
* value that does not match the key is rejected with an error. Boolean-like properties are expressed as named values so
* that additional values can be added later without breaking the ABI.
*/
typedef enum DUCKDB_V2_FUNCTION_PROPERTY_VALUE {
//! The function always returns the same result given the same input.
DUCKDB_V2_FUNCTION_PROPERTY_STABILITY_CONSISTENT = 65536,
//! The result may differ per row (e.g. random()).
DUCKDB_V2_FUNCTION_PROPERTY_STABILITY_VOLATILE = 65537,
//! The result is stable within a single query/transaction but may change across queries (e.g. now()).
DUCKDB_V2_FUNCTION_PROPERTY_STABILITY_CONSISTENT_WITHIN_QUERY = 65538,
//! Default NULL handling: if any argument is NULL the result is NULL and the function is not invoked for that row.
DUCKDB_V2_FUNCTION_PROPERTY_NULL_HANDLING_DEFAULT = 65792,
//! The function handles NULL inputs itself and is invoked even when arguments are NULL.
DUCKDB_V2_FUNCTION_PROPERTY_NULL_HANDLING_SPECIAL = 65793,
/*!
* The function never raises a runtime error. Declaring this promises that the callbacks never report an error; an
* error reported anyway becomes an internal error.
*/
DUCKDB_V2_FUNCTION_PROPERTY_FALLIBILITY_INFALLIBLE = 66048,
//! The function may raise a runtime error for some inputs.
DUCKDB_V2_FUNCTION_PROPERTY_FALLIBILITY_FALLIBLE = 66049,
//! The function combines collations from its inputs and propagates them to its result (default).
DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING_PROPAGATE = 66304,
//! Combinable collations are executed on the input arguments before the function runs.
DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING_PUSH_COMBINABLE = 66305,
//! Collations are ignored by the function.
DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING_IGNORE = 66306,
//! The aggregate's result depends on the order in which rows are aggregated (default).
DUCKDB_V2_FUNCTION_PROPERTY_AGG_ORDER_DEPENDENT_YES = 196608,
//! The aggregate's result does not depend on input order.
DUCKDB_V2_FUNCTION_PROPERTY_AGG_ORDER_DEPENDENT_NO = 196609,
//! The aggregate's result is affected by a DISTINCT modifier (default).
DUCKDB_V2_FUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT_YES = 196864,
//! The aggregate's result is not affected by a DISTINCT modifier.
DUCKDB_V2_FUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT_NO = 196865,
DUCKDB_V2_FUNCTION_PROPERTY_VALUE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_FUNCTION_PROPERTY_VALUE;
/* --- Struct forward declarations for function properties --- */
/* --- Types for function properties --- */
/* --- Constants for function properties --- */
/* --- Function pointer typedefs for function properties --- */
/* --- Functions for function properties --- */
/* --- Struct definitions for function properties --- */
/* ============================================================================
* MODULE: arena
* ============================================================================ */
/* --- Enums for arena --- */
/* --- Struct forward declarations for arena --- */
/* --- Types for arena --- */
/* --- Constants for arena --- */
/* --- Function pointer typedefs for arena --- */
/* --- Functions for arena --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Allocate `byte_len` bytes from the arena.
*
* Returns a writable pointer to `byte_len` uninitialized bytes, valid for as long as the arena is. There is no minimum
* or maximum allocation size, and the arena may return a pointer to a block of memory that is larger than `byte_len`.
* The arena will free all allocated memory when it is destroyed, so the caller should not attempt to free the returned
* pointer themselves.
*
* history:
* - unstable: v2.0.0
*
* @param arena The arena to allocate from.
* @param byte_len Number of bytes to reserve. May be 0.
* @param out_ptr Receives a writable pointer to byte_len arena-owned bytes.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arena_allocate(duckdb_v2_arena_handle arena, idx_t byte_len, uint8_t **out_ptr,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for arena --- */
/* ============================================================================
* MODULE: cast
* ============================================================================ */
/* --- Enums for cast --- */
/*!
* The mode a cast is being executed in. A normal cast must either succeed for every row or report an error, which
* aborts the query. A "try" cast (SQL TRY_CAST, and implicit casts the engine probes speculatively) tolerates per-row
* failures: the callback writes NULL for the rows it could not convert instead of aborting. Read with
* `duckdb_v2_cast_function_exec_get_mode()`, and passed to `duckdb_v2_vector_cast()`.
*/
typedef enum DUCKDB_V2_CAST_MODE {
//! A regular cast. A conversion failure reported through the error slot aborts the query.
DUCKDB_V2_CAST_MODE_NORMAL = 0,
/*!
* A "try" cast. Conversion failures should be written as NULLs into the output vector; an error reported through
* the slot is swallowed and the affected rows are left NULL.
*/
DUCKDB_V2_CAST_MODE_TRY = 1,
DUCKDB_V2_CAST_MODE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_CAST_MODE;
/* --- Struct forward declarations for cast --- */
/* --- Types for cast --- */
/*!
* An owned opaque handle to a cast function being built. Created with `duckdb_v2_cast_function_create()`, configured
* with the setter functions (e.g. `duckdb_v2_cast_function_set_source_type()`,
* `duckdb_v2_cast_function_set_exec_callback()`, etc.), made available with
* `duckdb_v2_connection_register_cast_function()` or `duckdb_v2_extension_register_cast_function()`, and destroyed with
* `duckdb_v2_cast_function_destroy()`.
*/
typedef struct _duckdb_v2_cast_function {
void *internal_ptr;
} * duckdb_v2_cast_function_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a cast function during the execution "exec" phase. The "exec"
* callback receives this handle and can use it to access the input vector, the output vector to write into, the number
* of rows to convert, and the mode the cast is running in.
*/
typedef struct _duckdb_v2_cast_function_exec_info {
void *internal_ptr;
} * duckdb_v2_cast_function_exec_info_handle;
/* --- Constants for cast --- */
/* --- Function pointer typedefs for cast --- */
typedef void (*duckdb_v2_cast_function_exec_callback_fn)(duckdb_v2_cast_function_exec_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
/* --- Functions for cast --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new cast function through a factory.
*
* The function starts out empty: configure it with the setter functions (e.g.
* `duckdb_v2_cast_function_set_source_type()`, `duckdb_v2_cast_function_set_exec_callback()`, etc.), then make it
* available with `duckdb_v2_connection_register_cast_function()` or `duckdb_v2_extension_register_cast_function()`. The
* caller owns the returned handle and must destroy it with `duckdb_v2_cast_function_destroy()`, also after
* registration.
*
* The cast function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the cast function through.
* @param function On success, receives the newly created cast function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_create(duckdb_v2_factory_handle factory,
duckdb_v2_cast_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the type the cast converts from.
*
* The type is borrowed and copied. Calling this again replaces the previous source type. A source type must be set
* before registration, and it must be a fully defined concrete type.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the source type of.
* @param source_type The type to cast from. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_set_source_type(duckdb_v2_cast_function_handle function,
duckdb_v2_logical_type_handle source_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the type the cast converts to.
*
* The type is borrowed and copied. Calling this again replaces the previous target type. A target type must be set
* before registration, and it must be a fully defined concrete type.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the target type of.
* @param target_type The type to cast to. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_set_target_type(duckdb_v2_cast_function_handle function,
duckdb_v2_logical_type_handle target_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets what it costs to apply this cast implicitly.
*
* The binder uses the cost to choose between candidate implicit casts: a lower non-negative cost makes the cast more
* likely to be picked, a higher one less likely. Built-in widening casts sit in the [0, 20] range, so a cost above 100
* effectively puts this cast last. A negative cost -- the default -- means the cast is never applied implicitly and is
* reached only through an explicit CAST or TRY_CAST.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the implicit cast cost of.
* @param cost The cost. Negative disables implicit casting.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_set_implicit_cast_cost(duckdb_v2_cast_function_handle function,
int64_t cost,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the cast function.
*
* Associates an opaque pointer with the function, retrievable from the exec callback via
* `duckdb_v2_cast_function_exec_get_user_data()`. The opaque handle bundles the pointer with an optional destructor,
* invoked when the data is no longer needed. The data is read-only during execution: the same pointer is shared by
* every thread running the cast.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_set_user_data(duckdb_v2_cast_function_handle function,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the exec callback of the cast function.
*
* The exec callback implements the conversion: it is invoked during query execution with a batch of input values and
* must fill the output vector. An exec callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the exec callback of.
* @param callback The exec callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_set_exec_callback(
duckdb_v2_cast_function_handle function, duckdb_v2_cast_function_exec_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_cast_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_exec_get_user_data(duckdb_v2_cast_function_exec_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many rows this execution must convert.
*
* The number of rows held by the input vector, and the number of entries the callback must write to the output vector.
* Note that this may be less than a full vector: a constant input is converted as a single row and the result is
* expanded by the engine.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param count Receives the number of rows.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_exec_get_row_count(duckdb_v2_cast_function_exec_info_handle info,
idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the input vector holding the values to convert.
*
* The vector holds the source type's values for the current batch; use `duckdb_v2_cast_function_exec_get_row_count()`
* for the number of rows. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param vector Receives the borrowed input vector.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_exec_get_input(duckdb_v2_cast_function_exec_info_handle info,
duckdb_v2_vector_handle *vector,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the output vector the exec callback must write into.
*
* The callback must write one entry per input row; use `duckdb_v2_cast_function_exec_get_row_count()` for the number of
* rows. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param vector Receives the borrowed output vector to write into.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_exec_get_output(duckdb_v2_cast_function_exec_info_handle info,
duckdb_v2_vector_handle *vector,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the mode the cast is being executed in.
*
* In `CAST_MODE_TRY` a conversion failure should be written as a NULL into the output vector rather than reported
* through the error slot, since the engine discards the error and keeps whatever the callback left in the output.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param mode Receives the cast mode.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_exec_get_mode(duckdb_v2_cast_function_exec_info_handle info,
DUCKDB_V2_CAST_MODE *mode,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the cast function, making it available to CAST and TRY_CAST.
*
* The cast is registered on the connection's database and takes effect immediately for every connection; it is not part
* of the connection's transaction, so a rollback does not undo it. Registration requires a source type, a target type
* and an exec callback; both types must be fully defined concrete types. Registering a cast for a pair that already has
* one replaces it. The cast function must have been created through a factory of the same database. The caller still
* owns the handle after registration and must destroy it with `duckdb_v2_cast_function_destroy()`, which does not
* affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param function The cast function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_cast_function(duckdb_v2_connection_handle conn,
duckdb_v2_cast_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the cast function, making it available to CAST and TRY_CAST.
*
* The cast is registered on the loading extension's database. Use this from the extension's load callback. Registration
* requires a source type, a target type and an exec callback; both types must be fully defined concrete types.
* Registering a cast for a pair that already has one replaces it. The cast function must have been created through a
* factory of the same database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_cast_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The cast function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_cast_function(duckdb_v2_extension_handle extension,
duckdb_v2_cast_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the cast function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_cast_function_destroy(duckdb_v2_cast_function_handle *function);
#endif
/* --- Struct definitions for cast --- */
/* ============================================================================
* MODULE: column_data_collection
* ============================================================================ */
/* --- Enums for column_data_collection --- */
/* --- Struct forward declarations for column_data_collection --- */
/* --- Types for column_data_collection --- */
/*!
* A column data collection represents a set of (buffer-managed) data chunks.
*
* You can append chunks to the collection iteratively, and then scan the collection back to retrieve the chunks in
* order. DuckDB will manage the memory for the chunks, and transparently offload chunks to disk if necessary. A
* collection shall not be scanned while it is being appended to, and vice versa. A collection shall not be appended to
* concurrently, but it can be scanned concurrently by multiple threads using a shared scan state and per-thread worker
* scan states. For concurrent appends, consider creating multiple collections and "combining" them into one collection
* at the end.
*/
typedef struct _duckdb_v2_column_data_collection {
void *internal_ptr;
} * duckdb_v2_column_data_collection_handle;
/*!
* Opaque state handle for shared state across multiple threads scanning a column data collection. This is used to
* coordinate work distribution, track global progress, or store any other state that needs to be shared across threads
* during the scan of the collection.
*/
typedef struct _duckdb_v2_column_data_collection_shared_scan_state {
void *internal_ptr;
} * duckdb_v2_column_data_collection_shared_scan_state_handle;
/*!
* Opaque state handle for local state while scanning a column data collection. This is used to track progress and any
* other state that needs to be maintained on a per-thread basis across calls while scanning the collection. It also
* keeps the buffers backing the most recently scanned chunk alive: chunks are scanned zero-copy, so a scanned chunk's
* data is only valid until the worker state's next scan call or its destruction.
*/
typedef struct _duckdb_v2_column_data_collection_worker_scan_state {
void *internal_ptr;
} * duckdb_v2_column_data_collection_worker_scan_state_handle;
/*!
* Opaque state handle for appending to a column data collection. This is used to track progress and any other state
* that needs to be maintained across calls while appending to the collection.
*/
typedef struct _duckdb_v2_column_data_collection_append_state {
void *internal_ptr;
} * duckdb_v2_column_data_collection_append_state_handle;
/* --- Constants for column_data_collection --- */
/* --- Function pointer typedefs for column_data_collection --- */
/* --- Functions for column_data_collection --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an empty column data collection from a factory.
*
* Allocates a new, empty column data collection, drawing its buffers from the factory's database. The collection starts
* with no chunks and is ready to have chunks appended to it. A collection must have at least one column; an empty types
* array is rejected with INVALID_INPUT.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param types_array Pointer to an array of logical_type handles, one per column. This defines the schema for the
* chunks that will be stored in the collection. All chunks appended to this collection must have vectors that conform
* to these types.
* @param types_count Number of elements in the types_array.
* @param out_collection Receives the new collection handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_create(
duckdb_v2_factory_handle factory, const duckdb_v2_logical_type_handle *types_array, idx_t types_count,
duckdb_v2_column_data_collection_handle *out_collection, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Drops all buffered rows, keeping the column types.
*
* Drops all buffered rows and releases their memory. The column types are unchanged and the collection is immediately
* appendable again. Existing append and scan states are invalidated. Use `duckdb_v2_column_data_collection_clear()`
* instead to keep the memory for the next appends.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to reset.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_reset(duckdb_v2_column_data_collection_handle collection,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Drops all buffered rows, keeping the column types and the memory.
*
* Like `duckdb_v2_column_data_collection_reset()`, but the buffers are retained rather than released, so the next
* appends write into memory that is already allocated. Use this when the collection is refilled repeatedly. The column
* types are unchanged and the collection is immediately appendable again. Existing append and scan states are
* invalidated.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to clear.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_clear(duckdb_v2_column_data_collection_handle collection,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a column data collection and all its chunks.
*
* Cleans up the collection and all resources associated with it, including all contained chunks. Sets the collection
* handle to NULL.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_destroy(duckdb_v2_column_data_collection_handle *collection);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Merges the source collection into the target collection, consuming the source in the process.
*
* Transfers all chunks from the source collection to the target collection. This destroys the source collection,
* setting the source handle to NULL. The two collections must have the same column types, and must have been created
* from factories of the same database: the transferred chunks keep their original buffers, so combining collections
* from different databases would tie the target to a buffer manager it does not own.
*
* history:
* - unstable: v2.0.0
*
* @param target The collection to merge into. After the call, this collection will contain all chunks from both
* collections.
* @param source The collection to merge from. This collection will be destroyed by this operation and its handle set to
* NULL.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_combine(duckdb_v2_column_data_collection_handle target,
duckdb_v2_column_data_collection_handle *source,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the total number of rows across all chunks in the collection.
*
* Sums the row counts of all chunks in the collection. This is the total number of rows represented by the collection,
* which may be more than the number of rows in any individual chunk.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to inspect.
* @param out_row_count Receives the total row count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_row_count(
duckdb_v2_column_data_collection_handle collection, idx_t *out_row_count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Initializes an append state for the collection.
*
* Returns an append state handle that can be used to append chunks to the collection while maintaining any necessary
* state across calls.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to prepare for appending.
* @param out_state Receives the new append state handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_append_state_create(
duckdb_v2_column_data_collection_handle collection, duckdb_v2_column_data_collection_append_state_handle *out_state,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys an append state handle.
*
* Cleans up any resources associated with the append state. After this call, the state handle must not be used again.
*
* history:
* - unstable: v2.0.0
*
* @param state The append state to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_append_state_destroy(duckdb_v2_column_data_collection_append_state_handle *state);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Appends a data chunk to the collection.
*
* Appends a copy of the given chunk to the end of the collection. The chunk's column count and types must equal the
* collection's exactly; a mismatch is rejected with INVALID_INPUT before anything is copied. VARCHAR values must
* already contain valid UTF-8; this function does not validate text. Complex-typed vectors may be flattened in place by
* the copy.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to append to.
* @param state The append state to use this append operation.
* @param chunk The chunk to append.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_append(
duckdb_v2_column_data_collection_handle collection, duckdb_v2_column_data_collection_append_state_handle state,
duckdb_v2_data_chunk_handle chunk, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Initializes a shared scan state for the collection.
*
* Returns a shared scan state handle that can be used by multiple threads to coordinate scanning of the collection.
* Caller owns the returned state and must destroy it via column_data_collection_shared_scan_state_destroy when done.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to prepare for shared scanning.
* @param out_state Receives the new shared scan state handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_shared_scan_state_create(
duckdb_v2_column_data_collection_handle collection,
duckdb_v2_column_data_collection_shared_scan_state_handle *out_state, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a shared scan state handle.
*
* Cleans up any resources associated with the shared scan state. After this call, the state handle must not be used
* again.
*
* history:
* - unstable: v2.0.0
*
* @param state The shared scan state to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_shared_scan_state_destroy(
duckdb_v2_column_data_collection_shared_scan_state_handle *state);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Initializes a worker scan state for the collection.
*
* Returns a "local" scan state handle for a worker thread to use while scanning the collection. This allows each thread
* to maintain its own progress and any other necessary information across multiple scan calls, while still coordinating
* with other threads via the shared scan state.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to prepare for worker scanning.
* @param out_state Receives the new worker scan state handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_worker_scan_state_create(
duckdb_v2_column_data_collection_handle collection,
duckdb_v2_column_data_collection_worker_scan_state_handle *out_state, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a worker scan state handle.
*
* Cleans up any resources associated with the worker scan state. After this call, the state handle must not be used
* again.
*
* history:
* - unstable: v2.0.0
*
* @param state The worker scan state to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_worker_scan_state_destroy(
duckdb_v2_column_data_collection_worker_scan_state_handle *state);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Scans the collection to retrieve the next data chunk, using shared state for coordination across threads and
* worker-local state for individual progress tracking.
*
* Retrieves the next chunk of data from the collection based on the provided shared scan state and worker-local scan
* state. The output chunk's column count and types must equal the collection's exactly; a mismatch is rejected with
* INVALID_INPUT.
*
* The scan is zero-copy where possible: the output chunk's vectors may reference the collection's buffers, kept alive
* by the worker scan state. The chunk's data is therefore only valid until the next scan call with the same worker
* state, or until the worker state or the collection is destroyed, whichever comes first. Copy the data out (or append
* it to another collection) before continuing the scan if it must outlive that window.
*
* history:
* - unstable: v2.0.0
*
* @param collection The collection to scan.
* @param shared_state The shared scan state to use for coordinating across threads.
* @param worker_state The worker-local scan state to use for this thread's scan operation.
* @param out_chunk The output chunk to write to.
* @param did_produce_chunk Receives true when a chunk was produced by this call, or false when the scan has completed
* (the chunk is then reset to empty).
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_data_collection_scan(
duckdb_v2_column_data_collection_handle collection,
duckdb_v2_column_data_collection_shared_scan_state_handle shared_state,
duckdb_v2_column_data_collection_worker_scan_state_handle worker_state, duckdb_v2_data_chunk_handle out_chunk,
bool *did_produce_chunk, duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for column_data_collection --- */
/* ============================================================================
* MODULE: configuration
* ============================================================================ */
/* --- Enums for configuration --- */
/*!
* The scope of an option's value. Writes take DEFAULT, GLOBAL or SESSION: DEFAULT writes to the option's default scope
* (`duckdb_v2_option_get_default_scope()`), like SQL `SET name = value`; GLOBAL writes through to the instance, visible
* to all connections, like `SET GLOBAL`; SESSION writes to one connection's session only, like `SET SESSION`. Reads
* report GLOBAL or SESSION, as DuckDB attributes the value: an option no scope sets reads as GLOBAL, its default, and a
* legacy option read through a connection or context reads as SESSION.
*/
typedef enum DUCKDB_V2_SETTING_SCOPE {
//! Write only: the option's default scope (`duckdb_v2_option_get_default_scope()`), not its default value.
DUCKDB_V2_SETTING_SCOPE_DEFAULT = 0,
//! The instance's value, visible to all connections.
DUCKDB_V2_SETTING_SCOPE_GLOBAL = 1,
//! A connection's session value.
DUCKDB_V2_SETTING_SCOPE_SESSION = 2,
DUCKDB_V2_SETTING_SCOPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_SETTING_SCOPE;
/* --- Struct forward declarations for configuration --- */
/* --- Types for configuration --- */
/* --- Constants for configuration --- */
/* --- Function pointer typedefs for configuration --- */
/* --- Functions for configuration --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the config of an instance: the GLOBAL scope.
*
* Reads report GLOBAL, and writes are `SET GLOBAL`. Writing at SESSION scope returns ERROR_INPUT_INVALID: an instance
* has no session. Options that can only be chosen at startup are passed to `duckdb_v2_instance_create_with_options()`.
* The returned handle is borrowed: it is valid for as long as the instance is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance.
* @param out_config Receives the borrowed config.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_get_config(duckdb_v2_instance_handle instance,
duckdb_v2_config_handle *out_config,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the config of a connection.
*
* Reads follow the connection's cascade: its SESSION value if it set one, otherwise the GLOBAL value, otherwise the
* default. Writes accept any scope the option supports. The returned handle is borrowed: it is valid for as long as the
* connection is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection.
* @param out_config Receives the borrowed config.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_get_config(duckdb_v2_connection_handle conn,
duckdb_v2_config_handle *out_config,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the config of a context.
*
* The same scope `duckdb_v2_connection_get_config()` gives for the context's connection. The returned handle is
* borrowed: it is valid for as long as the context is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param ctx The context.
* @param out_config Receives the borrowed config.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_context_get_config(duckdb_v2_context_handle ctx,
duckdb_v2_config_handle *out_config,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reads the effective value of an option in this config, and the scope it came from.
*
* Aliases resolve transparently, and an unknown name returns ERROR_INPUT_INVALID. The caller destroys the returned
* value.
*
* history:
* - unstable: v2.0.0
*
* @param config The config to read from.
* @param name Option name (canonical or alias).
* @param out_value Receives the value, typed as the option. Owned by the caller.
* @param out_scope Receives the scope the value came from.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_config_get_option_value(duckdb_v2_config_handle config,
const duckdb_v2_identifier_t *name,
duckdb_v2_value_handle *out_value,
DUCKDB_V2_SETTING_SCOPE *out_scope,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes an option in this config.
*
* `scope` chooses the destination, mirroring SQL:
* - DEFAULT writes to the option's default scope, like a bare `SET name = value`.
* - GLOBAL writes through to the instance, visible to all connections, like `SET GLOBAL`.
* - SESSION writes to one connection's session only, like `SET SESSION`.
* A scope neither the option (`duckdb_v2_option_supports_scope()`) nor the config supports returns ERROR_INPUT_INVALID;
* an instance's config supports only GLOBAL. The value is cast to the option's type as SQL `SET` does. An unknown name
* is rejected unless an extension that defines it can be autoloaded. An option that can only be chosen at startup is
* rejected: pass it to `duckdb_v2_instance_create_with_options()`.
*
* history:
* - unstable: v2.0.0
*
* @param config The config to write to.
* @param name Option name (canonical or alias).
* @param value The value, cast to the option's type as SQL `SET` does. Borrowed.
* @param scope Target scope: DEFAULT, GLOBAL, or SESSION.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_config_set_option_value(duckdb_v2_config_handle config,
const duckdb_v2_identifier_t *name,
duckdb_v2_value_handle value,
DUCKDB_V2_SETTING_SCOPE scope,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes an option in this config from text, the form SQL `SET` accepts.
*
* `duckdb_v2_config_set_option_value()` with the text as a VARCHAR value: the engine casts it to the option's type, so
* this is the one-call form for a setting spelled the way SQL spells it, e.g. "1GB" for memory_limit. Scope handling
* and errors are `duckdb_v2_config_set_option_value()`'s.
*
* history:
* - unstable: v2.0.0
*
* @param config The config to write to.
* @param name Option name (canonical or alias).
* @param setting The setting, in the textual form SQL `SET` accepts.
* @param scope Target scope: DEFAULT, GLOBAL, or SESSION.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_config_set_option_text(duckdb_v2_config_handle config,
const duckdb_v2_identifier_t *name,
const duckdb_v2_str *setting,
DUCKDB_V2_SETTING_SCOPE scope,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Describes a config option registered on this config's instance, by name.
*
* Allocates an option descriptor: canonical name, default value, description, supported and default scopes, and
* aliases. Aliases resolve transparently — passing an alias returns the canonical option, with the alias listed in its
* alias array. An unknown name returns ERROR_INPUT_INVALID, which includes an option of an extension that has not
* loaded yet. The caller destroys the returned option.
*
* history:
* - unstable: v2.0.0
*
* @param config The config whose instance registered the options.
* @param name Option name (canonical or alias).
* @param out_option Receives the option descriptor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_config_get_option_by_name(duckdb_v2_config_handle config,
const duckdb_v2_identifier_t *name,
duckdb_v2_option_handle *out_option,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of config options registered on this config's instance.
*
* Counts core options plus the extension options registered on this instance. Aliases are NOT counted separately; each
* one is reachable through its canonical option's alias array.
*
* history:
* - unstable: v2.0.0
*
* @param config The config whose instance registered the options.
* @param out_count Receives the option count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_config_get_option_count(duckdb_v2_config_handle config, idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Describes the config option at the given index on this config's instance.
*
* Index space: [0, core_count) addresses core options, [core_count, total) extension options. The mapping is stable for
* as long as no extension registers new options. An out-of-range index returns ERROR_INPUT_INVALID. The caller destroys
* the returned option.
*
* history:
* - unstable: v2.0.0
*
* @param config The config whose instance registered the options.
* @param index The option index, in [0, option_count).
* @param out_option Receives the option descriptor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_config_get_option_by_index(duckdb_v2_config_handle config, idx_t index,
duckdb_v2_option_handle *out_option,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys an option descriptor.
*
* Frees the handle along with the strings it owns. On success the slot is set to null. Safe to call on an already-null
* slot.
*
* history:
* - unstable: v2.0.0
*
* @param option The option handle to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_destroy(duckdb_v2_option_handle *option);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the option's canonical name.
*
* When the option was resolved from an alias, this still reports the canonical name; the alias is reachable via
* `duckdb_v2_option_get_alias()`.
*
* history:
* - unstable: v2.0.0
*
* @param option The option.
* @param out_name Receives a borrowed view of the option name. Valid until the option is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_get_name(duckdb_v2_option_handle option, duckdb_v2_identifier_t *out_name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the option's static default, as a value of the option's type.
*
* A NULL value for an option whose declaration has no default. The caller destroys the returned value.
*
* history:
* - unstable: v2.0.0
*
* @param option The option.
* @param out_value Receives the default value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_get_default_value(duckdb_v2_option_handle option,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the option's human-readable description.
*
* history:
* - unstable: v2.0.0
*
* @param option The option.
* @param out_description Receives a borrowed view of the description. Valid until the option is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_get_description(duckdb_v2_option_handle option,
duckdb_v2_str *out_description,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports whether the option may be written at a scope.
*
* GLOBAL and SESSION are the scopes to ask about; DEFAULT is supported by every option that supports either. A write at
* an unsupported scope returns ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param option The option.
* @param scope The scope to ask about.
* @param out_supported Receives whether a write at the scope is accepted.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_supports_scope(duckdb_v2_option_handle option,
DUCKDB_V2_SETTING_SCOPE scope, bool *out_supported,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the scope a DEFAULT write of the option goes to: GLOBAL or SESSION.
*
* history:
* - unstable: v2.0.0
*
* @param option The option.
* @param out_scope Receives the default scope.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_get_default_scope(duckdb_v2_option_handle option,
DUCKDB_V2_SETTING_SCOPE *out_scope,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of aliases registered for this option.
*
* Zero for an extension option; extension options carry no aliases.
*
* history:
* - unstable: v2.0.0
*
* @param option The option.
* @param out_count Receives the alias count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_get_alias_count(duckdb_v2_option_handle option, idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the alias name at the given index.
*
* An out-of-range index returns ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param option The option.
* @param index The alias index, in [0, alias_count).
* @param out_alias Receives a borrowed view of the alias. Valid until the option is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_option_get_alias(duckdb_v2_option_handle option, idx_t index,
duckdb_v2_identifier_t *out_alias,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for configuration --- */
/* ============================================================================
* MODULE: connection
* ============================================================================ */
/* --- Enums for connection --- */
/* --- Struct forward declarations for connection --- */
/* --- Types for connection --- */
/* --- Constants for connection --- */
/* --- Function pointer typedefs for connection --- */
/* --- Functions for connection --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Opens a connection to an instance.
*
* Each connection carries its own client context and session-scoped (LOCAL) settings. Connections to the same instance
* share its catalog, buffer pool, and transaction manager. A connection may be created before any database is attached
* to the instance; until one is, only the system catalog and the connection's temporary catalog are visible. The caller
* destroys it via `duckdb_v2_connection_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance to connect to.
* @param out_conn Receives the new connection handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_create(duckdb_v2_instance_handle instance,
duckdb_v2_connection_handle *out_conn,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the connection.
*
* Always succeeds. Releases the connection's reference on the underlying database instance, which survives for as long
* as anything else still references it. On success the handle is set to null. Safe to call on an already-null slot.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_destroy(duckdb_v2_connection_handle *conn);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Interrupts the query currently executing on the connection.
*
* The cross-thread (but not cross-connection) cancellation entry point for streaming results: safe to call from any
* thread within the execution of a query through a connection, including while another thread steps the query's result.
* A no-op when no query is active. Cancellation surfaces on the consuming side as step status CANCELLED
* (`duckdb_v2_result_step()`), or as ERROR_RUNTIME_INTERRUPT (`duckdb_v2_result_fetch_chunk()`).
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection whose active query to interrupt.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_interrupt(duckdb_v2_connection_handle conn,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Captures a snapshot of the active query's execution progress.
*
* Reads the percentage and row counts from one consistent snapshot of the query currently executing on the connection.
* Safe to call from any thread, including while another thread steps the query's result.
*
* Progress is published only when the enable_progress_bar option is set; the bridge does not enable tracking itself.
* Both row counts are 0 when no information is available. The percentage is -1 when tracking is disabled, no query is
* active, or no progress has been published yet.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection.
* @param out_percentage Receives the percentage complete in [0, 100], -1 if tracking is disabled, no query is active,
* or no progress has been published yet.
* @param out_rows_processed Receives the number of rows processed so far.
* @param out_total_rows_to_process Receives the total number of rows the query will process.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_progress_get(duckdb_v2_connection_handle conn, double *out_percentage,
uint64_t *out_rows_processed,
uint64_t *out_total_rows_to_process,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for connection --- */
/* ============================================================================
* MODULE: custom type
* ============================================================================ */
/* --- Enums for custom type --- */
/* --- Struct forward declarations for custom type --- */
/* --- Types for custom type --- */
/*!
* An owned opaque handle to a custom type being built. Created with `duckdb_v2_custom_type_create()`, configured with
* `duckdb_v2_custom_type_set_name()` and `duckdb_v2_custom_type_set_base_type()`, made available with
* `duckdb_v2_connection_register_custom_type()` or `duckdb_v2_extension_register_custom_type()`, and destroyed with
* `duckdb_v2_custom_type_destroy()`.
*/
typedef struct _duckdb_v2_custom_type {
void *internal_ptr;
} * duckdb_v2_custom_type_handle;
/* --- Constants for custom type --- */
/* --- Function pointer typedefs for custom type --- */
/* --- Functions for custom type --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new custom type through a factory.
*
* The type starts out empty: configure it with `duckdb_v2_custom_type_set_name()` and
* `duckdb_v2_custom_type_set_base_type()`, then make it available with `duckdb_v2_connection_register_custom_type()` or
* `duckdb_v2_extension_register_custom_type()`. The caller owns the returned handle and must destroy it with
* `duckdb_v2_custom_type_destroy()`, also after registration.
*
* The custom type can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the custom type through.
* @param type On success, receives the newly created custom type. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_type_create(duckdb_v2_factory_handle factory,
duckdb_v2_custom_type_handle *type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the custom type.
*
* This is the name the type is referred to by in SQL, and the alias carried by every logical type instance of it. The
* name is borrowed and copied. Calling this again replaces the previous name. A name must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param type The type to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_type_set_name(duckdb_v2_custom_type_handle type,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the base type of the custom type.
*
* The custom type shares the base type's internal representation but is logically distinct, so it can carry its own
* cast functions. The type is borrowed and copied. Calling this again replaces the previous base type. A base type must
* be set before registration, and it must be a fully defined concrete type -- ANY is a signature wildcard, not
* something a registered type can be built on.
*
* history:
* - unstable: v2.0.0
*
* @param type The type to set the base type of.
* @param base_type The logical type to base the custom type on. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_type_set_base_type(duckdb_v2_custom_type_handle type,
duckdb_v2_logical_type_handle base_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the custom type, making it available for use in SQL queries.
*
* The type is registered on the connection's database, visible to every connection, in the connection's transaction:
* inside an explicit transaction, it is invisible to other connections until the transaction commits, and a rollback
* undoes it. Registration requires a name and a complete base type. The custom type must have been created through a
* factory of the same database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_custom_type_destroy()`, which does not affect the registered type.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param type The custom type to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_custom_type(duckdb_v2_connection_handle conn,
duckdb_v2_custom_type_handle type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the custom type, making it available for use in SQL queries.
*
* The type is registered on the loading extension's database and attributed to the extension. Use this from the
* extension's load callback. Registration requires a name and a complete base type. The custom type must have been
* created through a factory of the same database. The caller still owns the handle after registration and must destroy
* it with `duckdb_v2_custom_type_destroy()`, which does not affect the registered type.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param type The custom type to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_custom_type(duckdb_v2_extension_handle extension,
duckdb_v2_custom_type_handle type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the custom type, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered type.
*
* history:
* - unstable: v2.0.0
*
* @param type The type to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_type_destroy(duckdb_v2_custom_type_handle *type);
#endif
/* --- Struct definitions for custom type --- */
/* ============================================================================
* MODULE: data_chunk
* ============================================================================ */
/* --- Enums for data_chunk --- */
/* --- Struct forward declarations for data_chunk --- */
/* --- Types for data_chunk --- */
/* --- Constants for data_chunk --- */
/* --- Function pointer typedefs for data_chunk --- */
/* --- Functions for data_chunk --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an empty data chunk with the given column types, drawing its allocator from a factory.
*
* The chunk's vectors are allocated through the factory's database, so the memory is accounted to that database.
* Allocates one FLAT vector per element of the types array, each at default capacity. Every vector starts at size 0;
* set it with vector_set_size once the vector is populated. The chunk is caller-owned and must be destroyed via
* data_chunk_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param types Pointer to an array of logical_type handles, one per column.
* @param column_count Number of elements in the types array.
* @param out_chunk Receives the new chunk handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_create(duckdb_v2_factory_handle factory,
const duckdb_v2_logical_type_handle *types, idx_t column_count,
duckdb_v2_data_chunk_handle *out_chunk,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a deep copy of a data chunk, drawing its allocator from a factory.
*
* Allocates a new chunk with the source chunk's column types and copies all rows into it, through the factory's
* database. The copy is flattened and owns all its data, so it stays valid after the source chunk or whatever backs it
* (such as a column data collection scan state) is destroyed. The returned chunk is caller-owned and must be destroyed
* via data_chunk_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param chunk The chunk to copy. Left unchanged.
* @param out_chunk Receives the new chunk handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_copy(duckdb_v2_factory_handle factory,
duckdb_v2_data_chunk_handle chunk,
duckdb_v2_data_chunk_handle *out_chunk,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a data chunk handle.
*
* Null-safe: passing nullptr or a slot already set to nullptr is a no-op. On success the slot is set to nullptr. Any
* vector previously borrowed from this chunk becomes invalid.
*
* history:
* - unstable: v2.0.0
*
* @param chunk The chunk to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_destroy(duckdb_v2_data_chunk_handle *chunk);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Empties a data chunk so it can be filled again.
*
* The chunk's size becomes 0, and each of its vectors becomes a writable FLAT vector of its type again, as on creation,
* so a chunk can be reused for one batch after another instead of being created for each. Data, views and pointers
* taken from the chunk or its vectors beforehand do not survive this. Must not be called on a chunk DuckDB lends to a
* callback for reading.
*
* history:
* - unstable: v2.0.0
*
* @param chunk The chunk to clear.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_clear(duckdb_v2_data_chunk_handle chunk,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the row count of a data chunk.
*
* history:
* - unstable: v2.0.0
*
* @param chunk The chunk.
* @param out_size Receives the row count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_get_size(duckdb_v2_data_chunk_handle chunk, idx_t *out_size,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of rows a data chunk can hold, e.g. how many rows the exec callback of a table function may write
* into its output chunk in one call.
*
* history:
* - unstable: v2.0.0
*
* @param chunk The chunk.
* @param out_capacity Receives the number of rows the chunk can hold.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_get_capacity(duckdb_v2_data_chunk_handle chunk, idx_t *out_capacity,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of vectors in a data chunk.
*
* Equals the column count of the producing result.
*
* history:
* - unstable: v2.0.0
*
* @param chunk The chunk.
* @param out_count Receives the vector count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_get_vector_count(duckdb_v2_data_chunk_handle chunk, idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the vector at the given index in a data chunk.
*
* The returned handle is borrowed and valid until the chunk is destroyed; do not destroy it. An out-of-range index
* returns ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param chunk The chunk.
* @param index The vector index, in [0, vector_count).
* @param out_vector Receives the borrowed vector handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_data_chunk_get_vector(duckdb_v2_data_chunk_handle chunk, idx_t index,
duckdb_v2_vector_handle *out_vector,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for data_chunk --- */
/* ============================================================================
* MODULE: environment
* ============================================================================ */
/* --- Enums for environment --- */
/* --- Struct forward declarations for environment --- */
/* --- Types for environment --- */
/* --- Constants for environment --- */
/* --- Function pointer typedefs for environment --- */
/* --- Functions for environment --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates the V2 environment. Call once at program start.
*
* history:
* - unstable: v2.0.0
*
* @param out_env Receives the new environment handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_environment_create(duckdb_v2_environment_handle *out_env,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the environment.
*
* Refuses with ERROR_RESOURCE_IN_USE while any instance created through this environment is still alive; destroy those
* instances first, then retry. On success the handle is set to null.
*
* history:
* - unstable: v2.0.0
*
* @param env The environment.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_environment_destroy(duckdb_v2_environment_handle *env);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of instances currently alive under the environment.
*
* A diagnostic accessor, for tracking down leaked instances when `duckdb_v2_environment_destroy()` returns
* ERROR_RESOURCE_IN_USE. The count is a snapshot and may change before the next call.
*
* history:
* - unstable: v2.0.0
*
* @param env The environment.
* @param out_count Receives the number of live instances.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_environment_get_instance_count(duckdb_v2_environment_handle env,
idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for environment --- */
/* ============================================================================
* MODULE: error
* ============================================================================ */
/* --- Enums for error --- */
/* --- Struct forward declarations for error --- */
/* --- Types for error --- */
/* --- Constants for error --- */
/* --- Function pointer typedefs for error --- */
/* --- Functions for error --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the error code associated with an error info handle.
*
* On success, writes the info's error code to `*out_code`. On failure (e.g. if `info` is invalid), leaves `*out_code`
* unchanged and returns a non-success error code.
*
* history:
* - unstable: v2.0.0
*
* @param info The error info handle to query.
* @param out_code The error code associated with the info, if the call succeeds.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_error_info_get_code(duckdb_v2_error_info_handle info, DUCKDB_V2_ERROR *out_code);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the error text associated with an error info handle.
*
* Returns a borrowed pointer to the info's null-terminated error text. The pointer is owned by DuckDB and is valid
* until the info is destroyed or a new text is set; callers must not free it, and must not read it once the info has
* been destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param info The error info handle to query.
* @param out_text Receives a borrowed view of the text. Owned by DuckDB; valid until the info handle is destroyed.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_error_info_get_text(duckdb_v2_error_info_handle info, duckdb_v2_str *out_text);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the error text body without the leading category prefix.
*
* Returns a borrowed view of the same text error_info_get_text reports, minus the leading "<Type> Error: " prefix. This
* is the authoritative unprefixed body: the API exposes no type name, so the prefix cannot be reconstructed and the
* body cannot be derived from error_info_get_text. Unprefixed does not mean plain — the body keeps whatever form it was
* rendered in (a LINE/caret block by default, JSON under errors_as_json). `{NULL, 0}` when there is no text. The
* pointer is owned by DuckDB and valid until the info handle is destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param info The error info handle to query.
* @param out_raw_text Receives a borrowed view of the raw text. Owned by DuckDB; valid until the info handle is
* destroyed.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_error_info_get_raw_text(duckdb_v2_error_info_handle info,
duckdb_v2_str *out_raw_text);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the error code for an error info handle.
*
* On success, replaces the info's error code with the provided one. On failure, nothing is changed. Accepts a `nullptr`
* info handle, in which case the call is a no-op and returns ERROR_NONE.
*
* history:
* - unstable: v2.0.0
*
* @param info The error info handle to set. On success, updated with the provided code.
* @param code The error code to set in the info.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_error_info_set_code(duckdb_v2_error_info_handle info, DUCKDB_V2_ERROR code);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the error text for an error info handle.
*
* On success, replaces the info's text with the provided one; DuckDB allocates its own copy of the string. On failure,
* nothing is changed. Accepts a `nullptr` info handle, in which case the call is a no-op and returns ERROR_NONE.
*
* history:
* - unstable: v2.0.0
*
* @param info The error info handle to set. On success, updated with the provided text.
* @param text The error text to set in the info.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_error_info_set_text(duckdb_v2_error_info_handle info, const duckdb_v2_str *text);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys an error info handle and frees its resources.
*
* Null-safe: calling with a null handle, or a null pointer-to-handle, is a no-op and returns ERROR_NONE. On return
* `*info` is set to nullptr. Safe to call on any info DuckDB returned.
*
* history:
* - unstable: v2.0.0
*
* @param info The error info handle to destroy. Set to nullptr on return.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_error_info_destroy(duckdb_v2_error_info_handle *info);
#endif
/* --- Struct definitions for error --- */
/* ============================================================================
* MODULE: extension
* ============================================================================ */
/* --- Enums for extension --- */
/* --- Struct forward declarations for extension --- */
typedef struct duckdb_v2_extension_input duckdb_v2_extension_input;
/* --- Types for extension --- */
/* --- Constants for extension --- */
/* --- Function pointer typedefs for extension --- */
/*!
* Hands back the function-pointer table for the API version the extension was built against, or NULL if this DuckDB
* cannot serve it.
*
* The extension calls it exactly once, first, through DUCKDB_EXTENSION_API_INIT; nothing else in the API may be called
* before it succeeds. A NULL return means the load has already failed and DuckDB has recorded why, so the entrypoint
* must return without touching the error slot. Statically linked extensions resolve DuckDB's symbols at link time and
* never call it, so for those the field is NULL.
*/
typedef const void *(*duckdb_v2_extension_get_api_fn)(duckdb_v2_extension_handle extension, const char *version);
/* --- Functions for extension --- */
/* --- Struct definitions for extension --- */
/*!
* The single argument to a V2 C extension entrypoint. Borrowed for the duration of the call: none of its fields outlive
* the entrypoint, and the extension destroys none of them.
*/
struct duckdb_v2_extension_input {
//! Fetches the versioned function-pointer table. NULL for a statically linked extension.
duckdb_v2_extension_get_api_fn get_api;
//! The extension being loaded, and the token get_api takes.
duckdb_v2_extension_handle extension;
/*!
* A borrowed context to read and run queries through, with a transaction already active. Valid only until the
* extension entrypoint returns; do not retain or destroy it.
*/
duckdb_v2_context_handle context;
/*!
* A live error slot: never NULL, and never pointing at NULL. Populate it with error_info_set_code, and optionally
* error_info_set_text, to fail the load. Do not destroy it -- DuckDB owns it. Pass a slot of your own to calls
* whose failure you intend to handle, so only a failure you mean to abort the load with lands here.
*/
duckdb_v2_error_info_handle *err;
};
/* ============================================================================
* MODULE: factory
* ============================================================================ */
/* --- Enums for factory --- */
/* --- Struct forward declarations for factory --- */
/* --- Types for factory --- */
/* --- Constants for factory --- */
/* --- Function pointer typedefs for factory --- */
/* --- Functions for factory --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the factory of an instance.
*
* The factory creates the built-in types and their values, casts with the built-in casts only, and allocates data
* chunks and column data collections through the instance. Anything that needs a catalog — catalog-registered types,
* qualified type names — returns ERROR_INPUT_INVALID. The returned handle is borrowed: it is valid for as long as the
* instance is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance.
* @param out_factory Receives the borrowed factory.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_get_factory(duckdb_v2_instance_handle instance,
duckdb_v2_factory_handle *out_factory,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the factory of a connection.
*
* The factory reaches the connection's catalog and settings. Catalog lookups run in the connection's active
* transaction, or in a transaction of their own when none is open; nothing else opens a transaction. The returned
* handle is borrowed: it is valid for as long as the connection is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection.
* @param out_factory Receives the borrowed factory.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_get_factory(duckdb_v2_connection_handle conn,
duckdb_v2_factory_handle *out_factory,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the factory of a context.
*
* The factory reaches the context's catalog and settings, within the transaction the context already has. The returned
* handle is borrowed: it is valid for as long as the context is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param ctx The context.
* @param out_factory Receives the borrowed factory.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_context_get_factory(duckdb_v2_context_handle ctx,
duckdb_v2_factory_handle *out_factory,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for factory --- */
/* ============================================================================
* MODULE: file system
* ============================================================================ */
/* --- Enums for file system --- */
/*!
* How `duckdb_v2_file_system_open()` opens a file. These are not a bitmask -- apply them one at a time with
* `duckdb_v2_file_open_options_set_flag()`, calling it once per behaviour you want, e.g. `FILE_FLAG_WRITE` then
* `FILE_FLAG_CREATE` to write to a file and create it when it does not exist.
*/
typedef enum DUCKDB_V2_FILE_FLAG {
//! Not a flag. The zero value, so that an uninitialized variable does not name a behaviour; applying it is an
//! error.
DUCKDB_V2_FILE_FLAG_INVALID = 0,
//! Open the file with "read" capabilities.
DUCKDB_V2_FILE_FLAG_READ = 1,
//! Open the file with "write" capabilities.
DUCKDB_V2_FILE_FLAG_WRITE = 2,
//! Create the file if it does not exist, and open it as it is if it does.
DUCKDB_V2_FILE_FLAG_CREATE = 3,
/*!
* Create the file if it does not exist, and truncate it to empty if it does. To fail instead of truncating, combine
* `FILE_FLAG_CREATE` with `FILE_FLAG_EXCLUSIVE_CREATE`.
*/
DUCKDB_V2_FILE_FLAG_CREATE_NEW = 4,
//! Open the file in "append" mode.
DUCKDB_V2_FILE_FLAG_APPEND = 5,
//! Fail if the file already exists. A modifier on `FILE_FLAG_CREATE`, and meaningless without it.
DUCKDB_V2_FILE_FLAG_EXCLUSIVE_CREATE = 6,
/*!
* The file will be read and written at explicit offsets from several threads at once. Pass it whenever
* `duckdb_v2_file_read_at()` or `duckdb_v2_file_write_at()` are used concurrently -- a file system that would
* otherwise assume sequential access, by caching, buffering, or keeping a single cursor, needs to know not to.
*/
DUCKDB_V2_FILE_FLAG_PARALLEL_ACCESS = 7,
/*!
* Read the file through DuckDB's external file cache, which keeps the bytes that were read in memory, so that later
* reads of the same file - also by later queries - do not have to read them again. Whether a local file is cached
* is decided by the `cache_local_files` setting. Only meaningful for reading.
*/
DUCKDB_V2_FILE_FLAG_EXTERNAL_FILE_CACHE = 8,
DUCKDB_V2_FILE_FLAG_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_FILE_FLAG;
/* --- Struct forward declarations for file system --- */
/* --- Types for file system --- */
/*!
* A borrowed opaque handle to a file system. Obtained from `duckdb_v2_instance_get_file_system()`,
* `duckdb_v2_connection_get_file_system()` or `duckdb_v2_context_get_file_system()`, and used to open files with
* `duckdb_v2_file_system_open()`. Borrowed: the handle belongs to the instance, connection or context it came from, is
* valid only for as long as that is, and must not be destroyed.
*/
typedef struct _duckdb_v2_file_system {
void *internal_ptr;
} * duckdb_v2_file_system_handle;
/*!
* An owned opaque handle to the options a file is opened with. Created with `duckdb_v2_file_open_options_create()`,
* configured with `duckdb_v2_file_open_options_set_flag()` and `duckdb_v2_file_open_options_set_value()`, passed to
* `duckdb_v2_file_system_open()`, and destroyed with `duckdb_v2_file_open_options_destroy()`. One options object can
* open any number of files, and destroying it does not affect files already opened with it.
*/
typedef struct _duckdb_v2_file_open_options {
void *internal_ptr;
} * duckdb_v2_file_open_options_handle;
/*!
* An owned opaque handle to an open file, produced by `duckdb_v2_file_system_open()` and destroyed with
* `duckdb_v2_file_destroy()`. Read, write, seek and sync through the `file_*` functions. Only usable while the file
* system it was opened through is still valid.
*/
typedef struct _duckdb_v2_file {
void *internal_ptr;
} * duckdb_v2_file_handle;
/* --- Constants for file system --- */
/* --- Function pointer typedefs for file system --- */
/*!
* Receives one path matched by `duckdb_v2_file_system_path_glob()`.
*
* The view is borrowed for the duration of the call only, and is not guaranteed to be null-terminated. Report an error
* through `err`, a live slot that must not be destroyed, to stop the glob: `duckdb_v2_file_system_path_glob()` then
* fails with that error. The callback must not throw or unwind across the boundary.
*/
typedef void (*duckdb_v2_file_system_path_glob_callback_fn)(const duckdb_v2_str *path, void *user_data,
duckdb_v2_error_info_handle *err);
/* --- Functions for file system --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the file system of a context.
*
* The returned handle is borrowed: it is valid only for as long as the context is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param context The context to take the file system from.
* @param file_system Receives the borrowed file system.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_context_get_file_system(duckdb_v2_context_handle context,
duckdb_v2_file_system_handle *file_system,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the file system of an instance.
*
* Paths are resolved with the instance's GLOBAL settings and secrets, and file I/O is not attributed to any query.
*
* The returned handle is borrowed: it is valid only for as long as the instance is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance to take the file system from.
* @param file_system Receives the borrowed file system.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_get_file_system(duckdb_v2_instance_handle instance,
duckdb_v2_file_system_handle *file_system,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the file system of a connection.
*
* Paths are resolved with the connection's settings and secrets, and file I/O is attributed to its running query, as
* through `duckdb_v2_context_get_file_system()` in a callback.
*
* The returned handle is borrowed: it is valid only for as long as the connection is, and must not be destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to take the file system from.
* @param file_system Receives the borrowed file system.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_get_file_system(duckdb_v2_connection_handle conn,
duckdb_v2_file_system_handle *file_system,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a set of open options for a file system.
*
* The options start out empty: give them flags with `duckdb_v2_file_open_options_set_flag()`, which is required, and
* optionally attach values with `duckdb_v2_file_open_options_set_value()`. They are then passed to
* `duckdb_v2_file_system_open()`, and can be reused for as many opens as you like. The caller owns the returned handle
* and must destroy it with `duckdb_v2_file_open_options_destroy()`.
*
* The options belong to the file system they were created from, since which values mean anything depends on which file
* system ends up handling the path.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system the options are for.
* @param options On success, receives the new options. Owned by the caller; destroy via
* `duckdb_v2_file_open_options_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_open_options_create(duckdb_v2_file_system_handle file_system,
duckdb_v2_file_open_options_handle *options,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Applies one flag to the options.
*
* Additive: call it once per behaviour you want, and applying the same flag twice is harmless. At least one flag must
* be applied before the options can open anything, since the flags are what say whether the file is being read or
* written. There is no way to take a flag back -- build a fresh set of options instead.
*
* `FILE_FLAG_INVALID` names no behaviour and is rejected, as is any value that is not a `DUCKDB_V2_FILE_FLAG`.
*
* history:
* - unstable: v2.0.0
*
* @param options The options to apply the flag to.
* @param flag The flag to apply.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_open_options_set_flag(duckdb_v2_file_open_options_handle options,
DUCKDB_V2_FILE_FLAG flag,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Attaches a named value to the options.
*
* These are hints for whichever file system ends up handling the path, and what they mean is that file system's
* business: a value it does not recognise is ignored rather than rejected, and the same name can mean different things
* to different file systems. They are the same values a file system reports when listing files, so a known file size or
* modification time learned from a listing can be handed straight back to avoid re-reading it.
*
* The name and the value are borrowed and copied, so the caller may destroy the value immediately after. Setting the
* same name again replaces the previous value. Names are case-sensitive.
*
* history:
* - unstable: v2.0.0
*
* @param options The options to set the value on.
* @param name The name of the value. Borrowed and copied.
* @param value The value. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_open_options_set_value(duckdb_v2_file_open_options_handle options,
const duckdb_v2_str *name,
duckdb_v2_value_handle value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the options, releasing their resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Files already opened with these options are unaffected.
*
* history:
* - unstable: v2.0.0
*
* @param options The options to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_open_options_destroy(duckdb_v2_file_open_options_handle *options);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Opens a file.
*
* Opens the file at the given path through the file system, which routes it the way the engine would -- a path handled
* by a registered virtual or remote file system goes there rather than to local disk. The returned handle is owned by
* the caller and must be destroyed with `duckdb_v2_file_destroy()`.
*
* The options carry the flags and any file-system-specific values; see `duckdb_v2_file_open_options_create()`. Opening
* without having set flags fails, since the flags are what say whether the file is being read or written.
*
* Failure to open -- a missing file without `FILE_FLAG_CREATE`, insufficient permissions, an existing file under
* `FILE_FLAG_EXCLUSIVE_CREATE` -- is reported as an error.
*
* Flag combinations that contradict each other, such as naming neither read nor write or combining `FILE_FLAG_CREATE`
* with `FILE_FLAG_CREATE_NEW`, are a programming error rather than a supported input. An assertion build catches them;
* elsewhere the behaviour is whatever the underlying file system does with them.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system to open the file through.
* @param file_path The path of the file to open. Borrowed for the call only.
* @param options How to open the file. Borrowed for the call only, and reusable across opens.
* @param file On success, receives the open file. Owned by the caller; destroy via `duckdb_v2_file_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_system_open(duckdb_v2_file_system_handle file_system,
const duckdb_v2_str *file_path,
duckdb_v2_file_open_options_handle options,
duckdb_v2_file_handle *file, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports whether a file exists at the given path.
*
* The path is routed the way `duckdb_v2_file_system_open()` routes it, so asking about a path handled by a remote file
* system may reach out to it. A directory is not a file, and reports false.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system to ask.
* @param path The path to check. Borrowed for the call only.
* @param out_exists Receives whether a file exists at the path.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_system_path_exists(duckdb_v2_file_system_handle file_system,
const duckdb_v2_str *path, bool *out_exists,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports whether a path names a remote file, e.g. one under `s3://`, `https://`, `gcs://` or `azure://`.
*
* Decided from the path alone: no file system is consulted, so it answers even when the extension providing the remote
* file system is not loaded.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system the path is meant for.
* @param path The path to check. Borrowed for the call only.
* @param out_is_remote Receives whether the path names a remote file.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_system_path_is_remote(duckdb_v2_file_system_handle file_system,
const duckdb_v2_str *path, bool *out_is_remote,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Expands a path as the file system does when opening it: a leading `~` becomes the home directory, as the
* `home_directory` setting configures it.
*
* A path without anything to expand is handed back as it is. The expanded path is handed to `sink` in a single call.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system whose settings expand the path.
* @param path The path to expand. Borrowed for the call only.
* @param sink Receives the expanded path in a single call. Borrowed for the duration of that call; see text_sink for
* the full contract.
* @param user_data Opaque pointer passed through to sink untouched. May be NULL.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_system_path_expand(duckdb_v2_file_system_handle file_system,
const duckdb_v2_str *path, duckdb_v2_text_sink_fn sink,
void *user_data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Finds the files matching a glob pattern, e.g. `*.csv` or `data_?.json` in a directory, handing each matched path to
* `callback`.
*
* The pattern is routed the way `duckdb_v2_file_system_open()` routes a path, so globbing a remote path may reach out
* to the file system handling it, and is only supported where that file system supports it. A pattern without glob
* characters matches the file it names, if there is one. Matching nothing is not an error. In which order the paths are
* handed over is up to the file system.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system to glob in.
* @param pattern The glob pattern. Borrowed for the call only.
* @param callback Invoked once per matched path.
* @param user_data Opaque pointer passed through to `callback` untouched. May be NULL.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_system_path_glob(duckdb_v2_file_system_handle file_system,
const duckdb_v2_str *pattern,
duckdb_v2_file_system_path_glob_callback_fn callback,
void *user_data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Moves, or renames, a file from one path to another.
*
* The move is handled by the file system `source` routes to, the way `duckdb_v2_file_system_open()` routes a path;
* moving a file between two file systems is not supported. Whether an existing file at `target` is replaced, and
* whether the move is atomic, is up to that file system.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system to move the file in.
* @param source The path of the file to move. Borrowed for the call only.
* @param target The path to move the file to. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_system_path_move(duckdb_v2_file_system_handle file_system,
const duckdb_v2_str *source, const duckdb_v2_str *target,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Removes the file at a path, if there is one.
*
* The path is routed the way `duckdb_v2_file_system_open()` routes it. A path with no file is not an error:
* `out_removed` then receives false. A file that exists but cannot be removed is.
*
* history:
* - unstable: v2.0.0
*
* @param file_system The file system to remove the file from.
* @param path The path of the file to remove. Borrowed for the call only.
* @param out_removed Optional. Receives whether a file was removed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_system_path_remove(duckdb_v2_file_system_handle file_system,
const duckdb_v2_str *path, bool *out_removed,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reads from the file into a caller-supplied buffer.
*
* Reads up to `buffer_size` bytes from the file's current position, advancing it by however many were read. Fewer bytes
* than asked for is normal at the end of the file, and zero means there is nothing left; neither is an error. The file
* must have been opened with `FILE_FLAG_READ`.
*
* Use `duckdb_v2_file_read_at()` to read at an explicit offset instead, which leaves the position alone and so can run
* on several threads at once.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to read from.
* @param buffer A caller-owned buffer of at least `buffer_size` bytes, receiving what was read.
* @param buffer_size The maximum number of bytes to read.
* @param bytes_read Receives how many bytes were actually read, which may be fewer than `buffer_size` at the end of the
* file.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_read(duckdb_v2_file_handle file, void *buffer, idx_t buffer_size,
idx_t *bytes_read, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes a caller-supplied buffer to the file.
*
* Writes up to `buffer_size` bytes at the file's current position, advancing it by however many were written. The file
* must have been opened with `FILE_FLAG_WRITE` or `FILE_FLAG_APPEND`. Writes may be buffered; use
* `duckdb_v2_file_sync()` to force them out.
*
* Use `duckdb_v2_file_write_at()` to write at an explicit offset instead, which leaves the position alone and so can
* run on several threads at once.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to write to.
* @param buffer A caller-owned buffer of at least `buffer_size` bytes, holding what to write.
* @param buffer_size The number of bytes to write.
* @param bytes_written Receives how many bytes were actually written.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_write(duckdb_v2_file_handle file, const void *buffer, idx_t buffer_size,
idx_t *bytes_written, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reads from a fixed offset, without moving the file's position.
*
* Reads exactly `buffer_size` bytes starting at `location`. Unlike `duckdb_v2_file_read()`, a short read is an error
* rather than a result: reaching the end of the file before `buffer_size` bytes fails, so there is no count to report
* back. The file's read/write position is untouched, which is what makes this safe to call from several threads at once
* -- provided the file was opened with `FILE_FLAG_PARALLEL_ACCESS`.
*
* The file must have been opened with `FILE_FLAG_READ`.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to read from.
* @param buffer A caller-owned buffer of at least `buffer_size` bytes, receiving what was read.
* @param buffer_size The number of bytes to read. All of them are read, or the call fails.
* @param location The absolute byte offset to read from, measured from the start of the file.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_read_at(duckdb_v2_file_handle file, void *buffer, idx_t buffer_size,
idx_t location, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes at a fixed offset, without moving the file's position.
*
* Writes exactly `buffer_size` bytes starting at `location`, extending the file when the offset is past its end. Unlike
* `duckdb_v2_file_write()` there is no count to report back: all of the bytes are written, or the call fails. The
* file's read/write position is untouched, which is what makes this safe to call from several threads at once --
* provided the file was opened with `FILE_FLAG_PARALLEL_ACCESS`, and that the threads write disjoint ranges.
*
* The file must have been opened with `FILE_FLAG_WRITE`. Writes may be buffered; use `duckdb_v2_file_sync()` to force
* them out.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to write to.
* @param buffer A caller-owned buffer of at least `buffer_size` bytes, holding what to write.
* @param buffer_size The number of bytes to write. All of them are written, or the call fails.
* @param location The absolute byte offset to write at, measured from the start of the file.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_write_at(duckdb_v2_file_handle file, const void *buffer, idx_t buffer_size,
idx_t location, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the file's current read/write position, as a byte offset from the start of the file.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to query.
* @param position Receives the current position, as a byte offset from the start of the file.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_tell(duckdb_v2_file_handle file, idx_t *position,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the total size of the file in bytes.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to query.
* @param size Receives the total size of the file in bytes.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_size(duckdb_v2_file_handle file, idx_t *size,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Moves the file's read/write position.
*
* Sets the position to an absolute byte offset from the start of the file; subsequent reads and writes start there.
* Seeking past the end is allowed, and reading from there yields nothing.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to seek within.
* @param position The absolute byte offset to seek to, measured from the start of the file.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_seek(duckdb_v2_file_handle file, idx_t position,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Flushes buffered writes to persistent storage.
*
* Forces anything still buffered out to storage, which is what makes writes durable across a crash or a process exit.
* Closing or destroying the handle flushes as well.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to synchronize.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_sync(duckdb_v2_file_handle file, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Closes the file without destroying the handle.
*
* Releases the operating-system resources behind the file, such as its descriptor. The handle itself stays valid and
* must still be destroyed with `duckdb_v2_file_destroy()`, but it can no longer read, write or seek.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to close.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_close(duckdb_v2_file_handle file, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the file, closing it if it is still open.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction.
*
* history:
* - unstable: v2.0.0
*
* @param file The file to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_file_destroy(duckdb_v2_file_handle *file);
#endif
/* --- Struct definitions for file system --- */
/* ============================================================================
* MODULE: function
* ============================================================================ */
/* --- Enums for function --- */
/* --- Struct forward declarations for function --- */
/* --- Types for function --- */
/*!
* A borrowed opaque handle to the call site a bind callback is binding. Every function family's bind callback receives
* this handle next to its own bind info. It gives access to the arguments of the call, the function's user data, and
* the bind data.
*
* The arguments form one list in four parts, in this order: one argument per positional-only and standard parameter, in
* declaration order; the arguments `*args` received, in call order; one argument per named-only parameter, in
* declaration order; and the arguments `**kwargs` received, in call order. How the caller passed an argument does not
* matter: a standard parameter passed by name is at its declared position. A parameter the call omitted is present with
* its default value. See `duckdb_v2_function_bind_get_arg_count()` for the size of each part.
*/
typedef struct _duckdb_v2_function_bind_info {
void *internal_ptr;
} * duckdb_v2_function_bind_info_handle;
/* --- Constants for function --- */
/* --- Function pointer typedefs for function --- */
/* --- Functions for function --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set on the function being bound, e.g. via `duckdb_v2_scalar_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_bind_get_user_data(duckdb_v2_function_bind_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's "bind data" from the bind callback.
*
* The bind data is stored with the bound call site and retrievable from every later callback. The opaque handle bundles
* the pointer with an optional destructor, invoked when the bind data is no longer needed, and an optional equality
* callback used when comparing two bound call sites; without one, pointer equality is used. Scalar functions set their
* bind data through `duckdb_v2_scalar_function_bind_set_bind_data()` instead.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param data Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_bind_set_bind_data(duckdb_v2_function_bind_info_handle info,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of arguments of the call site being bound, split into the four parts of the argument list.
*
* The parts follow each other in this order: the positional-only and standard parameters, the arguments `*args`
* received, the named-only parameters, and the arguments `**kwargs` received. The argument at index `i` of the
* named-only part is therefore at index `positional_fixed + positional_variadic + i`. Valid indices for the other
* argument functions are [0, the sum of the four counts). Every out-parameter may be NULL, in which case nothing is
* written to it.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param positional_fixed Optional. Receives the number of positional-only and standard parameters.
* @param positional_variadic Optional. Receives the number of arguments `*args` received, 0 when the signature has
* none.
* @param named_fixed Optional. Receives the number of named-only parameters.
* @param named_variadic Optional. Receives the number of arguments `**kwargs` received, 0 when the signature has none.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_bind_get_arg_count(duckdb_v2_function_bind_info_handle info,
idx_t *positional_fixed, idx_t *positional_variadic,
idx_t *named_fixed, idx_t *named_variadic,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the type of the argument at the given index.
*
* Fails if the index is out of bounds. The returned type is owned by the caller and must be destroyed via
* `duckdb_v2_logical_type_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the argument.
* @param type Receives the argument type. Owned by the caller; destroy via `duckdb_v2_logical_type_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_bind_get_arg_type(duckdb_v2_function_bind_info_handle info, idx_t index,
duckdb_v2_logical_type_handle *type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Folds the argument at the given index to a constant value.
*
* Fails if the argument is not constant, e.g. a column reference, or if the index is out of bounds. The arguments of a
* table or pragma function are always constant. The resulting value may be NULL. The returned value is owned by the
* caller and must be destroyed via `duckdb_v2_value_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the argument.
* @param value Receives the constant value. Owned by the caller; destroy via `duckdb_v2_value_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_bind_get_arg_value(duckdb_v2_function_bind_info_handle info,
idx_t index, duckdb_v2_value_handle *value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the name of the argument at the given index.
*
* For an argument of a declared parameter, this is the parameter name. For an argument `**kwargs` received, it is the
* name the caller passed, which may be the name of a positional-only parameter. An argument `*args` received has no
* name, and yields an empty name. Fails if the index is out of bounds. The name is borrowed and valid only for the
* duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the argument.
* @param name Receives a borrowed view of the argument name. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_bind_get_arg_name(duckdb_v2_function_bind_info_handle info, idx_t index,
duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Looks up the index of an argument by name.
*
* Names are matched case-insensitively, against the names a caller can pass an argument by: those of the standard and
* named-only parameters, and those `**kwargs` received. Positional-only parameters are skipped, so `f(1, x := 2)` with
* a positional-only `x` finds the argument `**kwargs` received. A name the call did not pass is not an error: `found`
* receives false and `index` is left untouched. A standard or named-only parameter is always found, as the call either
* passed it or it carries its default value.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param name The name to look up. Borrowed for the call only.
* @param index Receives the index of the argument, if found.
* @param found Receives whether the call has an argument of that name.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_bind_get_arg_index(duckdb_v2_function_bind_info_handle info,
const duckdb_v2_identifier_t *name, idx_t *index,
bool *found, duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for function --- */
/* ============================================================================
* MODULE: function docs
* ============================================================================ */
/* --- Enums for function docs --- */
/* --- Struct forward declarations for function docs --- */
/* --- Types for function docs --- */
/*!
* A borrowed opaque handle to the documentation of a function overload. Taken from the function it documents with
* `duckdb_v2_scalar_function_get_docs()`, `duckdb_v2_aggregate_function_get_docs()`,
* `duckdb_v2_table_function_get_docs()`, `duckdb_v2_pragma_function_get_docs()` or
* `duckdb_v2_macro_function_get_docs()`, and valid for as long as that function handle is; the caller never destroys
* it.
*/
typedef struct _duckdb_v2_function_docs {
void *internal_ptr;
} * duckdb_v2_function_docs_handle;
/* --- Constants for function docs --- */
/* --- Function pointer typedefs for function docs --- */
/* --- Functions for function docs --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the description of the function overload.
*
* The description is borrowed and copied. Calling this again replaces the previous description.
*
* history:
* - unstable: v2.0.0
*
* @param docs The documentation to set the description of.
* @param description The description to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_docs_set_description(duckdb_v2_function_docs_handle docs,
const duckdb_v2_str *description,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Adds an example of calling the function overload.
*
* The title and the example are borrowed and copied, and examples are reported in the order they were added.
*
* history:
* - unstable: v2.0.0
*
* @param docs The documentation to add the example to.
* @param title Optional. The title of the example; NULL or an empty view for none. Borrowed and copied.
* @param example The example, e.g. a SQL expression calling the function. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_docs_add_example(duckdb_v2_function_docs_handle docs,
const duckdb_v2_str *title,
const duckdb_v2_str *example,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Adds a category the function overload belongs to, e.g. "string" or "aggregate".
*
* The category is borrowed and copied, and categories are reported in the order they were added.
*
* history:
* - unstable: v2.0.0
*
* @param docs The documentation to add the category to.
* @param category The category. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_docs_add_category(duckdb_v2_function_docs_handle docs,
const duckdb_v2_str *category,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for function docs --- */
/* ============================================================================
* MODULE: function signature
* ============================================================================ */
/* --- Enums for function signature --- */
/*!
* How a caller passes the argument for a parameter, following Python's parameter kinds. A signature orders its
* parameters by kind, in the order the values are listed here. Pass one of these to
* `duckdb_v2_function_signature_add_parameter()`.
*/
typedef enum DUCKDB_V2_FUNCTION_PARAMETER_KIND {
/*!
* Passed by position only. The name is invisible to a caller: a named argument with the same name is received by
* `**kwargs`, or rejected when the signature has none.
*/
DUCKDB_V2_FUNCTION_PARAMETER_KIND_POSITIONAL_ONLY = 0,
//! Passed by position or by name.
DUCKDB_V2_FUNCTION_PARAMETER_KIND_STANDARD = 1,
/*!
* `*args`: receives the positional arguments left over after the positional-only and standard parameters, each cast
* to the parameter type. ANY leaves them un-cast.
*/
DUCKDB_V2_FUNCTION_PARAMETER_KIND_POSITIONAL_VARIADIC = 2,
//! Passed by name only.
DUCKDB_V2_FUNCTION_PARAMETER_KIND_NAMED_ONLY = 3,
/*!
* `**kwargs`: receives the named arguments that match no other parameter, each cast to the parameter type. ANY
* leaves them un-cast.
*/
DUCKDB_V2_FUNCTION_PARAMETER_KIND_NAMED_VARIADIC = 4,
DUCKDB_V2_FUNCTION_PARAMETER_KIND_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_FUNCTION_PARAMETER_KIND;
/* --- Struct forward declarations for function signature --- */
/* --- Types for function signature --- */
//! An opaque handle to a function signature. Carries the function's parameters and return type.
typedef struct _duckdb_v2_function_signature {
void *internal_ptr;
} * duckdb_v2_function_signature_handle;
/* --- Constants for function signature --- */
/* --- Function pointer typedefs for function signature --- */
/* --- Functions for function signature --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Adds a parameter to a signature.
*
* The kind decides how a caller passes the argument; see `DUCKDB_V2_FUNCTION_PARAMETER_KIND`. The signature keeps its
* parameters ordered by kind, and parameters of the same kind in the order they were added, so parameters of different
* kinds can be added in any order. A default value makes the parameter optional; `*args` and `**kwargs` cannot have
* one.
*
* Registration fails when two parameters share a name, when the signature has more than one `*args` or `**kwargs`
* parameter, or when a standard parameter without a default value follows one with a default value.
*
* history:
* - unstable: v2.0.0
*
* @param sig The signature to configure.
* @param name The parameter name. Borrowed and copied.
* @param type The parameter type. ANY accepts an argument of any type without casting it. Borrowed and copied.
* @param value Optional default value, borrowed and copied. Will be cast to the parameter type.
* @param kind How a caller passes the argument for the parameter.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_signature_add_parameter(
duckdb_v2_function_signature_handle sig, const duckdb_v2_identifier_t *name, duckdb_v2_logical_type_handle type,
duckdb_v2_value_handle value, DUCKDB_V2_FUNCTION_PARAMETER_KIND kind, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the return type of a signature.
*
* Sets the signature's return type. The type is borrowed and copied. Calling this again overwrites the previous return
* type. An INVALID type is rejected with ERROR_INPUT_INVALID. Whether a concrete return type is required, and whether
* ANY is accepted, depends on the function family and is enforced when the signature is registered with a builder.
*
* history:
* - unstable: v2.0.0
*
* @param sig The signature to configure.
* @param type The return type. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_function_signature_set_return_type(duckdb_v2_function_signature_handle sig,
duckdb_v2_logical_type_handle type,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for function signature --- */
/* ============================================================================
* MODULE: identifier
* ============================================================================ */
/* --- Enums for identifier --- */
/* --- Struct forward declarations for identifier --- */
/* --- Types for identifier --- */
/* --- Constants for identifier --- */
/* --- Function pointer typedefs for identifier --- */
/* --- Functions for identifier --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Renders a name as a SQL identifier, quoting and escaping only when required.
*
* Produces the SQL text for the name: the name itself when it is already a legal bare identifier, or the name
* double-quoted with interior double quotes doubled when it is a keyword or contains characters that require quoting.
* This is the engine's own identifier rendering, so the result parses back to a name equal to the input.
*
* Writes into a caller-supplied buffer, so nothing is allocated on the caller's behalf and nothing has to be freed.
* Pass out_text = NULL to size the buffer without rendering into it: out_length then receives the length, and
* out_capacity is ignored. With out_text != NULL, out_capacity must be at least out_length + 1, or the call returns
* ERROR_INPUT_OBJECT_SIZE with out_length set to the required length and out_text left untouched.
*
* out_length never counts the terminator, but a successful write always appends one, so the buffer is usable as a C
* string.
*
* history:
* - unstable: v2.0.0
*
* @param name The name to render. Borrowed for the call only.
* @param out_text Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required
* length in out_length.
* @param out_capacity Bytes available in out_text, terminator included. Ignored when out_text is NULL.
* @param out_length Receives the text length excluding the null terminator — written on success and on
* ERROR_INPUT_OBJECT_SIZE.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_identifier_render_quoted(const duckdb_v2_identifier_t *name, char *out_text,
idx_t out_capacity, idx_t *out_length,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for identifier --- */
/* ============================================================================
* MODULE: instance
* ============================================================================ */
/* --- Enums for instance --- */
/* --- Struct forward declarations for instance --- */
/* --- Types for instance --- */
/*!
* An opaque, owned handle to the `(KEY value)` options of one `duckdb_v2_instance_attach()` call, as SQL `ATTACH`
* accepts them. Created from the instance handle it will be used with via `duckdb_v2_attach_options_create()`; destroy
* it via `duckdb_v2_attach_options_destroy()`.
*/
typedef struct _duckdb_v2_attach_options {
void *internal_ptr;
} * duckdb_v2_attach_options_handle;
/* --- Constants for instance --- */
/* --- Function pointer typedefs for instance --- */
/* --- Functions for instance --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an instance under the environment with no startup options.
*
* The instance is ready on return, with no database attached: attach one with `duckdb_v2_instance_attach()` and pick
* the default with `duckdb_v2_instance_set_default()`, or connect with `duckdb_v2_connection_create()`. To choose an
* option that cannot change once the instance exists, such as access_mode, use
* `duckdb_v2_instance_create_with_options()` instead. The caller destroys the instance via
* `duckdb_v2_instance_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param env The environment.
* @param out_instance Receives the new instance handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_create(duckdb_v2_environment_handle env,
duckdb_v2_instance_handle *out_instance,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an instance under the environment, configured with startup options.
*
* Behaves as `duckdb_v2_instance_create()`, applying the startup options first.
*
* Startup options are (name, value) pairs in two parallel arrays, the values in the textual form SQL `SET` accepts.
* They are the only way to choose an option that cannot change once the instance exists, such as access_mode or
* allow_unsigned_extensions; every other option can be written now or later through `duckdb_v2_instance_get_config()`.
* An option that needs a running instance (the logging options, allowed_directories, allowed_paths,
* disabled_filesystems) returns ERROR_INPUT_INVALID here: write it through the instance's config after creation. A name
* no core option or loaded extension defines is kept for an extension to consume while the instance starts up, and
* creation fails with the names none claimed. The caller destroys the instance via `duckdb_v2_instance_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param env The environment.
* @param option_names Optional. An array of option_count option names (canonical or alias). Pass NULL when option_count
* is 0.
* @param option_values Optional. An array of option_count values, parallel to option_names, in the textual form SQL
* `SET` accepts. Pass NULL when option_count is 0.
* @param option_count The number of startup options.
* @param out_instance Receives the new instance handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_create_with_options(
duckdb_v2_environment_handle env, const duckdb_v2_str *option_names, const duckdb_v2_str *option_values,
idx_t option_count, duckdb_v2_instance_handle *out_instance, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the instance handle.
*
* Always succeeds. Every attached database is closed with the instance. The instance itself stays alive for as long as
* any connection still references it; when the last reference drops, it is destroyed and its database files become
* available to open again. On success the handle is set to null. Safe to call on an already-null slot.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance handle to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_destroy(duckdb_v2_instance_handle *instance);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Attaches a database to the instance.
*
* Attaches the database at `path` exactly like `ATTACH 'path'`:
* - `:memory:` or an empty view attaches a fresh in-memory database.
* - any other path attaches that file, creating it if it does not exist.
* `name` is the name to attach under, like `ATTACH ... AS name`; it is how `duckdb_v2_instance_detach()` and
* `duckdb_v2_instance_set_default()` refer to the database. Null, or an empty view, derives the name from the path the
* way SQL `ATTACH` without `AS` does:
* - `memory` for `:memory:` or an empty view;
* - otherwise the file name up to its first `.`, without any `?query` parameters (`/data/sales.2024.db` attaches as
* `sales`), with `_db` appended when that is a reserved name such as `system` or `temp`. Naming is how two files with
* the same base name, or `:memory:` twice, attach side by side. `options` may be null; it carries the `(KEY value)`
* options of SQL `ATTACH`, for per-database options such as READ_ONLY, BLOCK_SIZE or ENCRYPTION_KEY, and must have been
* created from this instance handle. `make_default` makes the attached database the default for connections created
* afterwards, exactly as a `duckdb_v2_instance_set_default()` call right after the attach would; otherwise the default
* is left alone. A path that is already attached on this or any other instance of the environment returns
* ERROR_RESOURCE_IN_USE, and a name that is already attached fails. Options that only apply at startup are passed to
* `duckdb_v2_instance_create_with_options()`.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance handle.
* @param name Optional. The name to attach under; null or an empty view for the name derived from the path. Borrowed
* and copied.
* @param path Path to the database file, or `:memory:` / an empty view for an in-memory database.
* @param options Optional attach options created from `instance`, or null to attach with defaults under the derived
* name.
* @param make_default Whether to make the attached database the default for connections created afterwards.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_attach(duckdb_v2_instance_handle instance,
const duckdb_v2_identifier_t *name, const duckdb_v2_str *path,
duckdb_v2_attach_options_handle options, bool make_default,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Detaches the database attached under `name`.
*
* Detaches it like `DETACH`, checkpointing a file database first. Unlike SQL, the default database may be detached too;
* new connections then start without a default until `duckdb_v2_instance_set_default()` names another, and existing
* connections bound to it keep it alive until their transaction on it ends and fail unqualified DDL afterwards. Returns
* ERROR_INPUT_INVALID when no database is attached under that name. Connections that still reference the database keep
* it alive until they release it.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance handle.
* @param name The name the database is attached under. Borrowed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_detach(duckdb_v2_instance_handle instance,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Makes the database attached under `name` the default database for connections created from now on.
*
* A connection binds to the default database when it is created, so this does not retarget existing connections: their
* default stays what it was when they connected, or what they chose with `USE`. The default is where unqualified DDL
* and unqualified table lookups that miss the temporary catalog go. It stays the default for new connections until
* another `duckdb_v2_instance_set_default()` call or until it is detached; a connection whose default has been detached
* fails unqualified DDL with a message saying so until it selects another with `USE`. Returns ERROR_INPUT_INVALID when
* no database is attached under that name.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance handle.
* @param name The name the database is attached under. Borrowed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_set_default(duckdb_v2_instance_handle instance,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an empty set of attach options for use with `duckdb_v2_instance_attach()` on `instance`.
*
* Starts empty. The caller destroys it via `duckdb_v2_attach_options_destroy()`; the options may be destroyed as soon
* as the attach call returns, and reused for further attaches before that.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance handle the options will be used with.
* @param out_options Receives the new options handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_attach_options_create(duckdb_v2_instance_handle instance,
duckdb_v2_attach_options_handle *out_options,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets one attach option, like a `(KEY value)` entry of SQL `ATTACH`.
*
* The key is matched case-insensitively, as an unquoted SQL identifier is. The setting is passed on as the text a
* quoted SQL literal would produce: the engine casts the options it knows (READ_ONLY, RECOVERY_MODE, TYPE,
* DEFAULT_TABLE, VACUUM_REBUILD_INDEXES, BLOCK_SIZE, ENCRYPTION_KEY, ...) and hands the rest to the storage extension
* that ends up owning the database, which decides what they mean. Keys must be valid UTF-8; an unknown or ill-typed
* option fails the attach. Both views are borrowed and copied. Setting the same key again replaces it.
*
* history:
* - unstable: v2.0.0
*
* @param options The attach options.
* @param key The option name, e.g. READ_ONLY.
* @param setting The option value, in the textual form a quoted SQL literal would carry.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_attach_options_set(duckdb_v2_attach_options_handle options,
const duckdb_v2_identifier_t *key,
const duckdb_v2_str *setting,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys an attach options handle.
*
* On success the slot is set to null. Safe to call on an already-null slot.
*
* history:
* - unstable: v2.0.0
*
* @param options The attach options to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_attach_options_destroy(duckdb_v2_attach_options_handle *options);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the version of the linked DuckDB library.
*
* history:
* - unstable: v2.0.0
*
* @param out_version The version string.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_library_version(duckdb_v2_str *out_version, duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for instance --- */
/* ============================================================================
* MODULE: logging
* ============================================================================ */
/* --- Enums for logging --- */
/*!
* Severity of a log message. Mirrors DuckDB's own log levels, and is compared against the configured threshold: an
* entry below it is dropped.
*/
typedef enum DUCKDB_V2_LOG_LEVEL {
//! Finest detail; off in any default configuration.
DUCKDB_V2_LOG_LEVEL_TRACE = 10,
//! Diagnostic detail.
DUCKDB_V2_LOG_LEVEL_DEBUG = 20,
//! Ordinary progress information.
DUCKDB_V2_LOG_LEVEL_INFO = 30,
//! A recoverable problem.
DUCKDB_V2_LOG_LEVEL_WARNING = 40,
//! An operation failed.
DUCKDB_V2_LOG_LEVEL_ERROR = 50,
//! An unrecoverable failure.
DUCKDB_V2_LOG_LEVEL_FATAL = 60,
DUCKDB_V2_LOG_LEVEL_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_LOG_LEVEL;
/* --- Struct forward declarations for logging --- */
/* --- Types for logging --- */
/* --- Constants for logging --- */
/* --- Function pointer typedefs for logging --- */
/* --- Functions for logging --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes a message to DuckDB's log.
*
* The entry is attributed to the context's connection scope, so it carries that connection's ids. Whether it is
* recorded at all is up to the database's log configuration: if logging is off, or level is below the configured
* threshold, or log_type is not among the enabled types, the call succeeds and writes nothing. An empty log_type
* selects the default type. Read entries back with `SELECT * FROM duckdb_logs`.
*
* history:
* - unstable: v2.0.0
*
* @param ctx The context to log through.
* @param level Severity of the message.
* @param log_type The log type to record under, matched case-sensitively. Empty selects the default type.
* @param message The message body. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_context_log(duckdb_v2_context_handle ctx, DUCKDB_V2_LOG_LEVEL level,
const duckdb_v2_str *log_type, const duckdb_v2_str *message,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes a message to DuckDB's log.
*
* The entry is attributed to the database scope: it carries no connection or query ids. Whether it is recorded at all
* is up to the database's log configuration: if logging is off, or level is below the configured threshold, or log_type
* is not among the enabled types, the call succeeds and writes nothing. An empty log_type selects the default type.
* Read entries back with `SELECT * FROM duckdb_logs`.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance to log through.
* @param level Severity of the message.
* @param log_type The log type to record under, matched case-sensitively. Empty selects the default type.
* @param message The message body. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_log(duckdb_v2_instance_handle instance, DUCKDB_V2_LOG_LEVEL level,
const duckdb_v2_str *log_type, const duckdb_v2_str *message,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes a message to DuckDB's log.
*
* The entry is attributed to the connection scope, so it carries the connection's ids. Whether it is recorded at all is
* up to the database's log configuration: if logging is off, or level is below the configured threshold, or log_type is
* not among the enabled types, the call succeeds and writes nothing. An empty log_type selects the default type. Read
* entries back with `SELECT * FROM duckdb_logs`.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to log through.
* @param level Severity of the message.
* @param log_type The log type to record under, matched case-sensitively. Empty selects the default type.
* @param message The message body. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_log(duckdb_v2_connection_handle conn, DUCKDB_V2_LOG_LEVEL level,
const duckdb_v2_str *log_type, const duckdb_v2_str *message,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for logging --- */
/* ============================================================================
* MODULE: qname
* ============================================================================ */
/* --- Enums for qname --- */
/* --- Struct forward declarations for qname --- */
/* --- Types for qname --- */
/*!
* An owned qualified name: an ordered path of one to three non-empty identifier parts whose last element is the object
* name. Construct with `duckdb_v2_qname_parse()` or `duckdb_v2_qname_create()`, read with
* `duckdb_v2_qname_get_part_count()` and `duckdb_v2_qname_get_part()`, render back to SQL with
* `duckdb_v2_qname_render()`, compare with `duckdb_v2_qname_equals()`, and destroy with `duckdb_v2_qname_destroy()`.
* Two handles are compared with `duckdb_v2_qname_equals()`, never by pointer.
*/
typedef struct _duckdb_v2_qname {
void *internal_ptr;
} * duckdb_v2_qname_handle;
/* --- Constants for qname --- */
/* --- Function pointer typedefs for qname --- */
/* --- Functions for qname --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Parses SQL text into a qualified name.
*
* Applies the engine's qualified-name rules: dots separate parts, and a double-quoted part may contain dots and doubled
* interior quotes. More than three parts and an unterminated quote are rejected with the parser's own error. Invalid
* UTF-8 and text without at least one non-empty part are rejected with `ERROR_INPUT_INVALID`. When the parts are
* already separate, build the name with `duckdb_v2_qname_create()` rather than joining them and parsing the result.
*
* history:
* - unstable: v2.0.0
*
* @param text The name text to parse. Borrowed for the call only.
* @param name On success, receives the qualified name. Owned by the caller; destroy via `duckdb_v2_qname_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_parse(const duckdb_v2_str *text, duckdb_v2_qname_handle *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a qualified name from its parts.
*
* The parts are ordered outermost first, so the last one is the object name. Between one and three parts are accepted
* -- the engine qualifies at most catalog.schema.name today -- and every part must be non-empty: partial qualification
* is expressed by passing fewer parts, never by empty placeholders. Zero parts, more than three, and an empty part are
* all rejected with `ERROR_INPUT_INVALID`. The parts are borrowed and copied.
*
* history:
* - unstable: v2.0.0
*
* @param parts An array of `part_count` non-empty identifier views, outermost first.
* @param part_count The number of parts, between one and three.
* @param name On success, receives the qualified name. Owned by the caller; destroy via `duckdb_v2_qname_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_create(const duckdb_v2_identifier_t *parts, idx_t part_count,
duckdb_v2_qname_handle *name, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many parts the qualified name has.
*
* Always at least one. Valid indices for `duckdb_v2_qname_get_part()` are [0, count), and the object name is the part
* at count - 1.
*
* history:
* - unstable: v2.0.0
*
* @param name The qualified name.
* @param count Receives the number of parts.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_get_part_count(duckdb_v2_qname_handle name, idx_t *count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows one part of the qualified name.
*
* Parts are ordered outermost first, so the object name is the part at `duckdb_v2_qname_get_part_count()` - 1. The view
* is valid until the qualified name is destroyed. An index outside [0, count) is rejected with
* `ERROR_INPUT_OUT_OF_RANGE`.
*
* history:
* - unstable: v2.0.0
*
* @param name The qualified name.
* @param index Zero-based part index.
* @param part Receives a borrowed view of the part, valid until the qualified name is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_get_part(duckdb_v2_qname_handle name, idx_t index,
duckdb_v2_identifier_t *part, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Renders the qualified name as SQL text.
*
* Joins the parts with dots, quoting and escaping each one only where the identifier requires it, so the result parses
* back through `duckdb_v2_qname_parse()` to an equal name.
*
* Writes into a caller-supplied buffer, so nothing is allocated on the caller's behalf and nothing has to be freed.
* Pass out_text = NULL to size the buffer without rendering into it: out_length then receives the length, and
* out_capacity is ignored. With out_text != NULL, out_capacity must be at least out_length + 1, or the call returns
* ERROR_INPUT_OBJECT_SIZE with out_length set to the required length and out_text left untouched.
*
* out_length never counts the terminator, but a successful write always appends one, so the buffer is usable as a C
* string.
*
* history:
* - unstable: v2.0.0
*
* @param name The qualified name to render.
* @param out_text Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required
* length in out_length.
* @param out_capacity Bytes available in out_text, terminator included. Ignored when out_text is NULL.
* @param out_length Receives the text length excluding the null terminator — written on success and on
* ERROR_INPUT_OBJECT_SIZE.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_render(duckdb_v2_qname_handle name, char *out_text, idx_t out_capacity,
idx_t *out_length, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Compares two qualified names.
*
* True when both have the same number of parts and every part matches case-insensitively, which is the engine's own
* identifier equality: casing never distinguishes two names. This is the only way to compare names; two handles holding
* equal names are still distinct pointers.
*
* history:
* - unstable: v2.0.0
*
* @param left The first qualified name.
* @param right The second qualified name.
* @param result Receives whether the two names are equal.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_equals(duckdb_v2_qname_handle left, duckdb_v2_qname_handle right,
bool *result, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Hashes a qualified name.
*
* Consistent with `duckdb_v2_qname_equals()`: names that compare equal hash equal, casing differences included. The
* value is not stable across processes or library versions, so use it for in-process lookup tables only and never
* persist it.
*
* history:
* - unstable: v2.0.0
*
* @param name The qualified name to hash.
* @param hash Receives the hash value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_hash(duckdb_v2_qname_handle name, uint64_t *hash,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the qualified name, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Any part views borrowed from it become dangling.
*
* history:
* - unstable: v2.0.0
*
* @param name The qualified name to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_qname_destroy(duckdb_v2_qname_handle *name);
#endif
/* --- Struct definitions for qname --- */
/* ============================================================================
* MODULE: query metrics
* ============================================================================ */
/* --- Enums for query metrics --- */
/* --- Struct forward declarations for query metrics --- */
/* --- Types for query metrics --- */
/*!
* An owned snapshot of the metrics of a query. Taken with `duckdb_v2_connection_get_query_metrics()`, read from its
* root node via `duckdb_v2_query_metrics_get_root()`, and destroyed with `duckdb_v2_query_metrics_destroy()`. Later
* queries do not update it.
*/
typedef struct _duckdb_v2_query_metrics {
void *internal_ptr;
} * duckdb_v2_query_metrics_handle;
/*!
* A borrowed opaque handle to one node of a query metrics snapshot, valid for as long as the snapshot is. Read its name
* with `duckdb_v2_query_metrics_node_get_name()`, its metrics with `duckdb_v2_query_metrics_node_get_metric()` or by
* index, and its children with `duckdb_v2_query_metrics_node_get_child()`.
*/
typedef struct _duckdb_v2_query_metrics_node {
void *internal_ptr;
} * duckdb_v2_query_metrics_node_handle;
/* --- Constants for query metrics --- */
/* --- Function pointer typedefs for query metrics --- */
/* --- Functions for query metrics --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Takes a snapshot of the metrics of the last query the connection finished.
*
* The snapshot is owned by the caller and does not change afterwards. It holds the metrics DuckDB's profiling
* configuration gathered: without profiling enabled, the root node carries no metrics and has no children. A snapshot
* is not promised to be complete; any metric, and any operator node, may be missing.
*
* Fails with `ERROR_RESOURCE_IN_USE` while a query is running on the connection, i.e. while a result of it has not yet
* been drained or destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to take the snapshot of.
* @param metrics On success, receives the owned snapshot. Destroy via `duckdb_v2_query_metrics_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_get_query_metrics(duckdb_v2_connection_handle conn,
duckdb_v2_query_metrics_handle *metrics,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Enables or disables profiling for the queries the connection runs from now on.
*
* While profiling is enabled, DuckDB gathers the metrics `duckdb_v2_connection_get_query_metrics()` reports. Profiling
* also prints the profile of every query, as configured by the `enable_profiling` and `profiling_output` options, which
* by default print a query tree to the standard output: set `enable_profiling` to `no_output` to only gather the
* metrics. Disabling profiling stops both.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to enable or disable profiling for.
* @param enabled Whether to enable profiling.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_enable_profiling(duckdb_v2_connection_handle conn, bool enabled,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the root node of the snapshot, which describes the query as a whole. Its children, if any, describe the
* operators that executed the query.
*
* history:
* - unstable: v2.0.0
*
* @param metrics The snapshot.
* @param node Receives the borrowed root node. Valid until the snapshot is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_get_root(duckdb_v2_query_metrics_handle metrics,
duckdb_v2_query_metrics_node_handle *node,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the name of the node: `QUERY` for the root node, and the name of the operator, e.g. `TABLE_SCAN`, for the
* other nodes.
*
* history:
* - unstable: v2.0.0
*
* @param node The node.
* @param name Receives a borrowed view of the name. Valid until the snapshot is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_node_get_name(duckdb_v2_query_metrics_node_handle node,
duckdb_v2_str *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of children of the node. Valid indices for `duckdb_v2_query_metrics_node_get_child()` are [0,
* count).
*
* history:
* - unstable: v2.0.0
*
* @param node The node.
* @param count Receives the number of children.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_node_get_child_count(duckdb_v2_query_metrics_node_handle node,
idx_t *count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the child of the node at index. An out-of-range index is rejected with `ERROR_INPUT_OUT_OF_RANGE`.
*
* history:
* - unstable: v2.0.0
*
* @param node The node.
* @param index Zero-based child index.
* @param child Receives the borrowed child. Valid until the snapshot is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_node_get_child(duckdb_v2_query_metrics_node_handle node,
idx_t index,
duckdb_v2_query_metrics_node_handle *child,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of metrics the node carries. Valid indices for `duckdb_v2_query_metrics_node_get_metric_name()`
* and `duckdb_v2_query_metrics_node_get_metric_value()` are [0, count); the order of the metrics is unspecified.
*
* history:
* - unstable: v2.0.0
*
* @param node The node.
* @param count Receives the number of metrics.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_node_get_metric_count(duckdb_v2_query_metrics_node_handle node,
idx_t *count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the name of the metric at index, e.g. `query.total_time`. An out-of-range index is rejected with
* `ERROR_INPUT_OUT_OF_RANGE`.
*
* history:
* - unstable: v2.0.0
*
* @param node The node.
* @param index Zero-based metric index.
* @param name Receives a borrowed view of the name. Valid until the snapshot is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_node_get_metric_name(duckdb_v2_query_metrics_node_handle node,
idx_t index, duckdb_v2_str *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value of the metric at index, a number such as a UBIGINT count or a DOUBLE duration. An out-of-range
* index is rejected with `ERROR_INPUT_OUT_OF_RANGE`.
*
* history:
* - unstable: v2.0.0
*
* @param node The node.
* @param index Zero-based metric index.
* @param value Receives the owned value. Destroy via `duckdb_v2_value_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_node_get_metric_value(duckdb_v2_query_metrics_node_handle node,
idx_t index, duckdb_v2_value_handle *value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Looks up a metric of the node by name, e.g. `query.total_time`. When the node does not carry it, `present` receives
* false and `value` receives null.
*
* history:
* - unstable: v2.0.0
*
* @param node The node.
* @param name The name of the metric, matched exactly. Borrowed for the call only.
* @param value Receives the owned value, if present. Destroy via `duckdb_v2_value_destroy()`.
* @param present Receives whether the node carries the metric.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_node_get_metric(duckdb_v2_query_metrics_node_handle node,
const duckdb_v2_str *name,
duckdb_v2_value_handle *value, bool *present,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the snapshot, releasing its resources and invalidating the nodes borrowed from it.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction.
*
* history:
* - unstable: v2.0.0
*
* @param metrics The snapshot to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_query_metrics_destroy(duckdb_v2_query_metrics_handle *metrics);
#endif
/* --- Struct definitions for query metrics --- */
/* ============================================================================
* MODULE: schema
* ============================================================================ */
/* --- Enums for schema --- */
/* --- Struct forward declarations for schema --- */
/* --- Types for schema --- */
/*!
* An owned, ordered list of (name, type) fields. Read with schema_get_count and schema_get_field. Destroy via
* schema_destroy.
*/
typedef struct _duckdb_v2_schema {
void *internal_ptr;
} * duckdb_v2_schema_handle;
/* --- Constants for schema --- */
/* --- Function pointer typedefs for schema --- */
/* --- Functions for schema --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of fields in a schema.
*
* history:
* - unstable: v2.0.0
*
* @param schema The schema.
* @param out_count Receives the field count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_schema_get_count(duckdb_v2_schema_handle schema, idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the name and type of the field at the given index.
*
* out_name and out_type are valid only until the schema is destroyed, and out_type must not be destroyed. An
* out-of-range index is rejected with ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param schema The schema.
* @param index Zero-based field index.
* @param out_name Receives a borrowed view of the field name. Valid until the schema is destroyed.
* @param out_type Receives a borrowed field type. Valid until the schema is destroyed; do not destroy it.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_schema_get_field(duckdb_v2_schema_handle schema, idx_t index,
duckdb_v2_identifier_t *out_name,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a schema handle.
*
* Frees the handle along with the names and types it owns. On success the slot is set to null. Safe to call on an
* already-null slot.
*
* history:
* - unstable: v2.0.0
*
* @param schema The schema handle to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_schema_destroy(duckdb_v2_schema_handle *schema);
#endif
/* --- Struct definitions for schema --- */
/* ============================================================================
* MODULE: tokenizer
* ============================================================================ */
/* --- Enums for tokenizer --- */
//! The lexical class of a token.
typedef enum DUCKDB_V2_TOKEN_TYPE {
//! Not an actual token class; out_type is set to this when `duckdb_v2_token_iterator_next()` fails.
DUCKDB_V2_TOKEN_TYPE_INVALID = 0,
//! A keyword of the connection's grammar.
DUCKDB_V2_TOKEN_TYPE_KEYWORD = 1,
//! A bare or double-quoted identifier, quotes included.
DUCKDB_V2_TOKEN_TYPE_IDENTIFIER = 2,
//! A quoted or dollar-quoted string, delimiters included.
DUCKDB_V2_TOKEN_TYPE_STRING_LITERAL = 3,
//! A numeric literal.
DUCKDB_V2_TOKEN_TYPE_NUMBER_LITERAL = 4,
//! An operator or punctuation run other than the statement terminator.
DUCKDB_V2_TOKEN_TYPE_OPERATOR = 5,
//! A line or block comment, delimiters included.
DUCKDB_V2_TOKEN_TYPE_COMMENT = 6,
//! A statement-terminating semicolon.
DUCKDB_V2_TOKEN_TYPE_TERMINATOR = 7,
/*!
* Not a token; reported by token_iterator_next once the input is exhausted, with start equal to the input length
* and length 0.
*/
DUCKDB_V2_TOKEN_TYPE_END_OF_INPUT = 8,
DUCKDB_V2_TOKEN_TYPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_TOKEN_TYPE;
/* --- Struct forward declarations for tokenizer --- */
/* --- Types for tokenizer --- */
//! An opaque, owned handle to an iterator over the tokens of a SQL string, produced by tokenize_sql.
typedef struct _duckdb_v2_token_iterator {
void *internal_ptr;
} * duckdb_v2_token_iterator_handle;
/* --- Constants for tokenizer --- */
/* --- Function pointer typedefs for tokenizer --- */
/* --- Functions for tokenizer --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Tokenizes a SQL string into an iterator over its tokens.
*
* Lexical tokenization, in the context of whatever grammar extensions are loaded on the given connection. Closing the
* connection or changing settings afterwards does not affect the tokens. The SQL string is borrowed for the call only,
* the caller may free it once this call returns. Whitespace is not a token. Malformed input is not an error;
* `duckdb_v2_token_iterator_ends_unterminated()` reports whether the input ended inside an open token.
*
* *out_iterator is set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection supplying the grammar.
* @param sql The SQL text. Borrowed for the call only; may contain interior null bytes. {NULL, 0} is the empty input.
* @param out_iterator Receives the new iterator handle. Destroy via token_iterator_destroy.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_tokenize_sql(duckdb_v2_connection_handle conn, const duckdb_v2_str *sql,
duckdb_v2_token_iterator_handle *out_iterator,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Yields the next token, or END_OF_INPUT once exhausted.
*
* On success writes the token's class, byte offset and byte length into the out-parameters. The lexeme is the input
* bytes [start, start + length). Once the input is exhausted, every call gives TOKEN_TYPE_END_OF_INPUT with start equal
* to the input length and length 0. On failure out params are set to TOKEN_TYPE_INVALID, 0, 0.
*
* history:
* - unstable: v2.0.0
*
* @param iterator The iterator to advance.
* @param out_type Receives the token's class, or TOKEN_TYPE_END_OF_INPUT once exhausted.
* @param out_start Receives the token's byte offset into the input; the input length for END_OF_INPUT.
* @param out_length Receives the token's byte length; 0 for END_OF_INPUT.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_token_iterator_next(duckdb_v2_token_iterator_handle iterator,
DUCKDB_V2_TOKEN_TYPE *out_type, idx_t *out_start,
idx_t *out_length, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports whether the input ended before the closing delimiter of its last token.
*
* True when the input ends inside an open string, quoted identifier, block comment or dollar-quoted string, or in a
* line comment with no trailing newline; false otherwise, including for empty or whitespace-only input. Equivalently,
* the last token `duckdb_v2_token_iterator_next()` yields before TOKEN_TYPE_END_OF_INPUT is the open one, so its class
* and lexeme say which delimiter is missing. A property of the input, not of the iterator position: the answer is the
* same before, during and after draining. The only failure is a null argument.
*
* history:
* - unstable: v2.0.0
*
* @param iterator The iterator.
* @param out_ends_unterminated Receives whether the input ended inside an open token.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_token_iterator_ends_unterminated(duckdb_v2_token_iterator_handle iterator,
bool *out_ends_unterminated,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a token iterator handle.
*
* history:
* - unstable: v2.0.0
*
* @param iterator The iterator to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_token_iterator_destroy(duckdb_v2_token_iterator_handle *iterator);
#endif
/* --- Struct definitions for tokenizer --- */
/* ============================================================================
* MODULE: aggregate
* ============================================================================ */
/* --- Enums for aggregate --- */
/* --- Struct forward declarations for aggregate --- */
/* --- Types for aggregate --- */
/*!
* An owned opaque handle to a custom aggregate function being built. Created with
* `duckdb_v2_aggregate_function_create()`, configured with the setter functions (e.g.
* `duckdb_v2_aggregate_function_set_name()`, `duckdb_v2_aggregate_function_set_update_callback()`, etc.) and the
* signature obtained via `duckdb_v2_aggregate_function_get_signature()`, made available with
* `duckdb_v2_connection_register_aggregate_function()` or `duckdb_v2_extension_register_aggregate_function()`, and
* destroyed with `duckdb_v2_aggregate_function_destroy()`.
*/
typedef struct _duckdb_v2_aggregate_function {
void *internal_ptr;
} * duckdb_v2_aggregate_function_handle;
/*!
* A borrowed opaque handle to the result of an aggregate function's "bind" phase. The "bind" callback receives this
* handle next to a `duckdb_v2_function_bind_info_handle`, which gives access to the arguments, the user data and the
* bind data, and can use it to set the return type of the call site being bound.
*/
typedef struct _duckdb_v2_aggregate_function_bind_info {
void *internal_ptr;
} * duckdb_v2_aggregate_function_bind_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to an aggregate function during the state sizing "size" phase. The
* "size" callback receives this handle and must use it to report the size of a single aggregate state in bytes.
*/
typedef struct _duckdb_v2_aggregate_function_size_info {
void *internal_ptr;
} * duckdb_v2_aggregate_function_size_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to an aggregate function during the state initialization "init"
* phase. The "init" callback receives this handle and can use it to access the array of aggregate states it must
* initialize in place.
*/
typedef struct _duckdb_v2_aggregate_function_init_info {
void *internal_ptr;
} * duckdb_v2_aggregate_function_init_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to an aggregate function during the "update" phase. The "update"
* callback receives this handle and can use it to access the input argument vectors, the number of rows to process, and
* the aggregate state each row must be aggregated into.
*/
typedef struct _duckdb_v2_aggregate_function_update_info {
void *internal_ptr;
} * duckdb_v2_aggregate_function_update_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to an aggregate function during the "combine" phase. The "combine"
* callback receives this handle and can use it to access the source and target aggregate state arrays to merge.
*/
typedef struct _duckdb_v2_aggregate_function_combine_info {
void *internal_ptr;
} * duckdb_v2_aggregate_function_combine_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to an aggregate function during the "finalize" phase. The
* "finalize" callback receives this handle and can use it to access the aggregate states and the result vector and
* offset to write their final values to.
*/
typedef struct _duckdb_v2_aggregate_function_finalize_info {
void *internal_ptr;
} * duckdb_v2_aggregate_function_finalize_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to an aggregate function during the state destruction "destroy"
* phase. The "destroy" callback receives this handle and can use it to access the array of aggregate states whose
* resources must be released.
*/
typedef struct _duckdb_v2_aggregate_function_destroy_info {
void *internal_ptr;
} * duckdb_v2_aggregate_function_destroy_info_handle;
/* --- Constants for aggregate --- */
/* --- Function pointer typedefs for aggregate --- */
typedef void (*duckdb_v2_aggregate_function_bind_callback_fn)(duckdb_v2_function_bind_info_handle info,
duckdb_v2_aggregate_function_bind_info_handle result,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_aggregate_function_size_callback_fn)(duckdb_v2_aggregate_function_size_info_handle info,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_aggregate_function_init_callback_fn)(duckdb_v2_aggregate_function_init_info_handle info,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_aggregate_function_update_callback_fn)(duckdb_v2_aggregate_function_update_info_handle info,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_aggregate_function_combine_callback_fn)(duckdb_v2_aggregate_function_combine_info_handle info,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_aggregate_function_finalize_callback_fn)(
duckdb_v2_aggregate_function_finalize_info_handle info, duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_aggregate_function_destroy_callback_fn)(duckdb_v2_aggregate_function_destroy_info_handle info,
duckdb_v2_error_info_handle *err);
/* --- Functions for aggregate --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new aggregate function through a factory.
*
* The function starts out empty: configure it with the setter functions (e.g.
* `duckdb_v2_aggregate_function_set_name()`, `duckdb_v2_aggregate_function_set_update_callback()`, etc.) and the
* signature obtained via `duckdb_v2_aggregate_function_get_signature()`, then make it available with
* `duckdb_v2_connection_register_aggregate_function()` or `duckdb_v2_extension_register_aggregate_function()`. The
* caller owns the returned handle and must destroy it with `duckdb_v2_aggregate_function_destroy()`, also after
* registration.
*
* The aggregate function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the aggregate function through.
* @param function On success, receives the newly created aggregate function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_create(duckdb_v2_factory_handle factory,
duckdb_v2_aggregate_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the aggregate function.
*
* The name is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_name(duckdb_v2_aggregate_function_handle function,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the documentation of the function so it can be filled in.
*
* Set a description with `duckdb_v2_function_docs_set_description()`, and add examples and categories with
* `duckdb_v2_function_docs_add_example()` and `duckdb_v2_function_docs_add_category()`. The documentation is modified
* in place, describes this overload only, and is registered with the function. Optional.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the documentation of.
* @param docs The returned documentation. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_get_docs(duckdb_v2_aggregate_function_handle function,
duckdb_v2_function_docs_handle *docs,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the function's signature so it can be configured.
*
* Add parameters with `duckdb_v2_function_signature_add_parameter()` and set the return type with
* `duckdb_v2_function_signature_set_return_type()`. The signature is modified in place; the function must be given a
* signature with a return type before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the signature of.
* @param sig The returned signature. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_get_signature(duckdb_v2_aggregate_function_handle function,
duckdb_v2_function_signature_handle *sig,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the aggregate function.
*
* Associates an opaque pointer with the function, retrievable from each callback via its user data accessor (e.g.
* `duckdb_v2_function_bind_get_user_data()`, `duckdb_v2_aggregate_function_update_get_user_data()`, etc.). The opaque
* handle bundles the pointer with an optional destructor, invoked when the data is no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_user_data(duckdb_v2_aggregate_function_handle function,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets a property on the aggregate function.
*
* Configures a function property that influences planning and execution, such as stability, NULL handling, fallibility,
* collation handling, or the aggregate-specific order/DISTINCT dependence. The value must be one of the
* `DUCKDB_V2_FUNCTION_PROPERTY_VALUE` entries belonging to `key`; passing a value that does not belong to the key, or a
* key that is not valid for aggregate functions, results in an error.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the property of.
* @param key The property to set.
* @param value The value to set for the property. Must belong to `key`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_property(duckdb_v2_aggregate_function_handle function,
DUCKDB_V2_FUNCTION_PROPERTY_KEY key,
DUCKDB_V2_FUNCTION_PROPERTY_VALUE value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional bind callback of the aggregate function.
*
* The bind callback is invoked during query planning for each call site of the function. Through its
* `duckdb_v2_function_bind_info_handle` it can inspect the argument types and constant argument values and set "bind
* data" that is shared with the other callbacks. Through its `duckdb_v2_aggregate_function_bind_info_handle` it can set
* a concrete return type.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the bind callback of.
* @param callback The bind callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_bind_callback(
duckdb_v2_aggregate_function_handle function, duckdb_v2_aggregate_function_bind_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the size callback of the aggregate function.
*
* The size callback reports the size of a single aggregate state in bytes via
* `duckdb_v2_aggregate_function_size_set_state_size()`; DuckDB uses it to allocate state memory. A size callback must
* be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the size callback of.
* @param callback The size callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_size_callback(
duckdb_v2_aggregate_function_handle function, duckdb_v2_aggregate_function_size_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the init callback of the aggregate function.
*
* The init callback initializes freshly allocated aggregate states in place, obtained via
* `duckdb_v2_aggregate_function_init_get_states()`. An init callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the init callback of.
* @param callback The init callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_init_callback(
duckdb_v2_aggregate_function_handle function, duckdb_v2_aggregate_function_init_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the update callback of the aggregate function.
*
* The update callback is invoked during query execution with a batch of input rows: row i of every argument vector must
* be aggregated into state i of the state array. An update callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the update callback of.
* @param callback The update callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_update_callback(
duckdb_v2_aggregate_function_handle function, duckdb_v2_aggregate_function_update_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the combine callback of the aggregate function.
*
* The combine callback merges partial aggregate states computed in parallel: source state i must be combined into
* target state i. A combine callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the combine callback of.
* @param callback The combine callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_combine_callback(
duckdb_v2_aggregate_function_handle function, duckdb_v2_aggregate_function_combine_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the finalize callback of the aggregate function.
*
* The finalize callback produces the function's result: state i must be finalized into result row offset + i of the
* result vector. A finalize callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the finalize callback of.
* @param callback The finalize callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_finalize_callback(
duckdb_v2_aggregate_function_handle function, duckdb_v2_aggregate_function_finalize_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the destroy callback for the aggregate function. Optional: only needed when aggregate states own resources that
* must be released. The callback runs on states that are discarded without being finalized; it must not fail, an error
* reported through its error slot is ignored.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the destroy callback of.
* @param callback The destroy callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_set_destroy_callback(
duckdb_v2_aggregate_function_handle function, duckdb_v2_aggregate_function_destroy_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the concrete return type of the call site being bound.
*
* Overrides the return type declared in the signature. Register the function with an ANY return type and set the
* concrete type here, derived from the argument types, to build a function whose result type depends on its input. The
* type is borrowed and copied.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param return_type The return type to set. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_bind_set_return_type(
duckdb_v2_aggregate_function_bind_info_handle info, duckdb_v2_logical_type_handle return_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_aggregate_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The size info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_size_get_user_data(
duckdb_v2_aggregate_function_size_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The size info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_size_get_bind_data(
duckdb_v2_aggregate_function_size_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the size of a single aggregate state, in bytes. The size callback must set this; DuckDB uses it to allocate
* state memory.
*
* history:
* - unstable: v2.0.0
*
* @param info The size info handle.
* @param size The size of a single aggregate state, in bytes.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_size_set_state_size(
duckdb_v2_aggregate_function_size_info_handle info, idx_t size, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_aggregate_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_init_get_user_data(
duckdb_v2_aggregate_function_init_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_init_get_bind_data(
duckdb_v2_aggregate_function_init_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many aggregate states this invocation must initialize. This is the length of the array returned by
* `duckdb_v2_aggregate_function_init_get_states()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param count Receives the number of states.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_init_get_state_count(
duckdb_v2_aggregate_function_init_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the array of aggregate states to initialize, one pointer per state. Each state points to uninitialized memory
* of the size reported by the size callback; the init callback must initialize all of them in place.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param states Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_init_get_states(
duckdb_v2_aggregate_function_init_info_handle info, void ***states, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_aggregate_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_update_get_user_data(
duckdb_v2_aggregate_function_update_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_update_get_bind_data(
duckdb_v2_aggregate_function_update_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many input rows this invocation carries. This is the length of the argument vectors and of the state
* array: row i of every argument vector must be aggregated into state i.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param count Receives the number of rows.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_update_get_row_count(
duckdb_v2_aggregate_function_update_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many argument vectors this invocation carries, split into the four parts of the argument list.
*
* The parts and their order are those the bind callback saw through `duckdb_v2_function_bind_get_arg_count()`, and the
* vectors are at the same indices. Valid indices for `duckdb_v2_aggregate_function_update_get_arg()` are [0, the sum of
* the four counts). Every out-parameter may be NULL, in which case nothing is written to it.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param positional_fixed Optional. Receives the number of positional-only and standard parameters.
* @param positional_variadic Optional. Receives the number of arguments `*args` received, 0 when the signature has
* none.
* @param named_fixed Optional. Receives the number of named-only parameters.
* @param named_variadic Optional. Receives the number of arguments `**kwargs` received, 0 when the signature has none.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_update_get_arg_count(
duckdb_v2_aggregate_function_update_info_handle info, idx_t *positional_fixed, idx_t *positional_variadic,
idx_t *named_fixed, idx_t *named_variadic, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the argument vector at the given index.
*
* The index is the one the bind callback used for the argument, e.g. the index
* `duckdb_v2_function_bind_get_arg_index()` found for a name. The vector holds the argument's values for the current
* batch; use `duckdb_v2_aggregate_function_update_get_row_count()` for the number of rows. Fails if the index is out of
* bounds. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param index The index of the argument.
* @param vector Receives the borrowed argument vector.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_update_get_arg(duckdb_v2_aggregate_function_update_info_handle info, idx_t index,
duckdb_v2_vector_handle *vector, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the array of aggregate states to update, one pointer per input row: row i of every argument vector must be
* aggregated into state i. Different rows may point to the same state.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param states Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_update_get_states(
duckdb_v2_aggregate_function_update_info_handle info, void ***states, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_aggregate_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The combine info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_combine_get_user_data(
duckdb_v2_aggregate_function_combine_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The combine info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_combine_get_bind_data(
duckdb_v2_aggregate_function_combine_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many source/target state pairs this invocation must combine. This is the length of both the sources and
* the targets array.
*
* history:
* - unstable: v2.0.0
*
* @param info The combine info handle.
* @param count Receives the number of state pairs.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_combine_get_state_count(
duckdb_v2_aggregate_function_combine_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the array of source aggregate states, one pointer per pair. Source i must be combined into target i; the
* source must not be modified.
*
* history:
* - unstable: v2.0.0
*
* @param info The combine info handle.
* @param states Receives the array of source aggregate state pointers. Borrowed; valid only for the duration of the
* callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_combine_get_sources(
duckdb_v2_aggregate_function_combine_info_handle info, void ***states, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the array of target aggregate states, one pointer per pair. Source i must be combined into target i.
*
* history:
* - unstable: v2.0.0
*
* @param info The combine info handle.
* @param states Receives the array of target aggregate state pointers. Borrowed; valid only for the duration of the
* callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_combine_get_targets(
duckdb_v2_aggregate_function_combine_info_handle info, void ***states, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_aggregate_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_finalize_get_user_data(
duckdb_v2_aggregate_function_finalize_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_finalize_get_bind_data(
duckdb_v2_aggregate_function_finalize_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many aggregate states this invocation must finalize. This is the length of the state array and the number
* of rows to write to the result vector.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param count Receives the number of states.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_finalize_get_state_count(
duckdb_v2_aggregate_function_finalize_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the array of aggregate states to finalize, one pointer per state. State i must be finalized into result row
* offset + i.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param states Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_finalize_get_states(
duckdb_v2_aggregate_function_finalize_info_handle info, void ***states, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the result vector the finalize callback must write into.
*
* State i must be finalized into result row offset + i, with the offset from
* `duckdb_v2_aggregate_function_finalize_get_result_offset()`. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param vector Receives the borrowed result vector to write into.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_finalize_get_result(duckdb_v2_aggregate_function_finalize_info_handle info,
duckdb_v2_vector_handle *vector, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the offset in the result vector at which to start writing: state i must be finalized into result row offset +
* i.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param offset Receives the result offset.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_finalize_get_result_offset(
duckdb_v2_aggregate_function_finalize_info_handle info, idx_t *offset, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_aggregate_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The destroy info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_destroy_get_user_data(
duckdb_v2_aggregate_function_destroy_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The destroy info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_destroy_get_bind_data(
duckdb_v2_aggregate_function_destroy_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many aggregate states this invocation must destroy. This is the length of the state array.
*
* history:
* - unstable: v2.0.0
*
* @param info The destroy info handle.
* @param count Receives the number of states.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_destroy_get_state_count(
duckdb_v2_aggregate_function_destroy_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the array of aggregate states to destroy, one pointer per state. The callback must release any resources the
* states own.
*
* history:
* - unstable: v2.0.0
*
* @param info The destroy info handle.
* @param states Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_destroy_get_states(
duckdb_v2_aggregate_function_destroy_info_handle info, void ***states, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the aggregate function, making it available for use in SQL queries.
*
* The function is registered on the connection's database, visible to every connection, in the connection's
* transaction: inside an explicit transaction, it is invisible to other connections until the transaction commits, and
* a rollback undoes it. Registration requires a name, the size, init, update, combine and finalize callbacks, and a
* signature with a complete return type; an ANY return type is accepted only together with a bind callback that sets
* the concrete type per call site. The aggregate function must have been created through a factory of the same
* database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_aggregate_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param function The aggregate function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_aggregate_function(
duckdb_v2_connection_handle conn, duckdb_v2_aggregate_function_handle function, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the aggregate function, making it available for use in SQL queries.
*
* The function is registered on the loading extension's database and attributed to the extension. Use this from the
* extension's load callback. Registration requires a name, the size, init, update, combine and finalize callbacks, and
* a signature with a complete return type; an ANY return type is accepted only together with a bind callback that sets
* the concrete type per call site. The aggregate function must have been created through a factory of the same
* database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_aggregate_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The aggregate function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_aggregate_function(
duckdb_v2_extension_handle extension, duckdb_v2_aggregate_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the aggregate function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_aggregate_function_destroy(duckdb_v2_aggregate_function_handle *function);
#endif
/* --- Struct definitions for aggregate --- */
/* ============================================================================
* MODULE: catalog
* ============================================================================ */
/* --- Enums for catalog --- */
/* --- Struct forward declarations for catalog --- */
/* --- Types for catalog --- */
/*!
* An owned snapshot of one base table taken at creation: where the name resolved, the table's columns, and per-column
* catalog facts. Later DDL does not update it. Create with `duckdb_v2_connection_describe_table()`, read the resolved
* location via `duckdb_v2_table_description_get_qname()`, and the columns via
* `duckdb_v2_table_description_get_column_count()` and `duckdb_v2_table_description_get_column()`. Destroy via
* `duckdb_v2_table_description_destroy()`.
*/
typedef struct _duckdb_v2_table_description {
void *internal_ptr;
} * duckdb_v2_table_description_handle;
/*!
* An owned snapshot of one column of a described table: its name, type, and catalog facts. Obtain with
* `duckdb_v2_table_description_get_column()`, read with `duckdb_v2_column_description_get_name()`,
* `duckdb_v2_column_description_get_type()`, `duckdb_v2_column_description_has_default()` and
* `duckdb_v2_column_description_has_generated()`, and destroy with `duckdb_v2_column_description_destroy()`.
*/
typedef struct _duckdb_v2_column_description {
void *internal_ptr;
} * duckdb_v2_column_description_handle;
/* --- Constants for catalog --- */
/* --- Function pointer typedefs for catalog --- */
/* --- Functions for catalog --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Resolves a table name and snapshots its description.
*
* Resolves name in the connection's catalogs and returns an owned description of the table it names. name may be
* partial: an unqualified or schema-qualified name resolves through the connection's search path, exactly as the same
* name resolves in SQL. A two-part name tries the first part as a schema and as an attached database, as SQL does, and
* is rejected when both readings exist. A name that resolves to nothing is rejected with the engine's missing-table
* error; a name that resolves to a view is rejected with the engine's not-a-table error, since a description snapshots
* a base table.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection whose catalogs and search path resolve the name.
* @param name The possibly partial table name to resolve. Borrowed for the call only.
* @param desc On success, receives the owned description. Destroy via `duckdb_v2_table_description_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_describe_table(duckdb_v2_connection_handle conn,
duckdb_v2_qname_handle name,
duckdb_v2_table_description_handle *desc,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the resolved qualified name of the described table.
*
* Returns an owned copy of the fully resolved name: the catalog, schema, and table the lookup landed on, with the
* casing the table was created with, never an echo of the requested name. Rendering it produces SQL that pins the
* described table regardless of search path.
*
* history:
* - unstable: v2.0.0
*
* @param desc The description.
* @param name Receives the owned resolved name. Destroy via `duckdb_v2_qname_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_description_get_qname(duckdb_v2_table_description_handle desc,
duckdb_v2_qname_handle *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns whether the described table's catalog is read-only.
*
* True when the catalog the name resolved into was attached read-only, in which case no write to the table can succeed.
* False does not by itself prove a write will succeed; it clears the catalog-level check only.
*
* history:
* - unstable: v2.0.0
*
* @param desc The description.
* @param readonly Receives whether the catalog is read-only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_description_is_readonly(duckdb_v2_table_description_handle desc,
bool *readonly, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns of the described table.
*
* Counts every column in declared order, generated columns included. Valid indices for
* `duckdb_v2_table_description_get_column()` are [0, count).
*
* history:
* - unstable: v2.0.0
*
* @param desc The description.
* @param count Receives the column count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_description_get_column_count(duckdb_v2_table_description_handle desc,
idx_t *count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns an owned description of the column at index.
*
* Columns are numbered in declared order, generated columns included. An out-of-range index is rejected with
* `ERROR_INPUT_OUT_OF_RANGE`.
*
* history:
* - unstable: v2.0.0
*
* @param desc The description.
* @param index Zero-based column index.
* @param column Receives the owned column description. Destroy via `duckdb_v2_column_description_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_description_get_column(duckdb_v2_table_description_handle desc,
idx_t index,
duckdb_v2_column_description_handle *column,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the table description, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Column descriptions obtained from it are independent and stay valid.
*
* history:
* - unstable: v2.0.0
*
* @param desc The description to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_description_destroy(duckdb_v2_table_description_handle *desc);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the name of the column.
*
* The name carries the casing the column was declared with.
*
* history:
* - unstable: v2.0.0
*
* @param column The column description.
* @param name Receives a borrowed view of the column name. Valid until the column description is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_description_get_name(duckdb_v2_column_description_handle column,
duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the type of the column.
*
* history:
* - unstable: v2.0.0
*
* @param column The column description.
* @param type Receives the borrowed column type. Valid until the column description is destroyed; do not destroy it.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_description_get_type(duckdb_v2_column_description_handle column,
duckdb_v2_logical_type_handle *type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns whether the column has a default value.
*
* True when the column declares a default expression; the engine evaluates it for rows that omit the column. Generated
* columns report false.
*
* history:
* - unstable: v2.0.0
*
* @param column The column description.
* @param has_default Receives whether the column has a default value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_description_has_default(duckdb_v2_column_description_handle column,
bool *has_default,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns whether the column is generated.
*
* True when the column is a generated column, computed by the engine from a generation expression and not writable.
*
* history:
* - unstable: v2.0.0
*
* @param column The column description.
* @param has_generated Receives whether the column is generated.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_description_has_generated(duckdb_v2_column_description_handle column,
bool *has_generated,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the column description, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Any name or type borrowed from it becomes dangling.
*
* history:
* - unstable: v2.0.0
*
* @param column The column description to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_column_description_destroy(duckdb_v2_column_description_handle *column);
#endif
/* --- Struct definitions for catalog --- */
/* ============================================================================
* MODULE: copy
* ============================================================================ */
/* --- Enums for copy --- */
/* --- Struct forward declarations for copy --- */
/* --- Types for copy --- */
/*!
* An owned opaque handle to a custom copy function being built: an output format for `COPY ... TO`, an input format for
* `COPY ... FROM`, or both. Created with `duckdb_v2_copy_function_create()`, configured with the setter functions (e.g.
* `duckdb_v2_copy_function_set_name()`, `duckdb_v2_copy_to_set_batch_callback()`,
* `duckdb_v2_copy_from_set_exec_callback()`, etc.), made available with `duckdb_v2_connection_register_copy_function()`
* or `duckdb_v2_extension_register_copy_function()`, and destroyed with `duckdb_v2_copy_function_destroy()`.
*/
typedef struct _duckdb_v2_copy_function {
void *internal_ptr;
} * duckdb_v2_copy_function_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the query preparation "bind" phase of a
* `COPY ... TO` statement. The "bind" callback receives this handle and can use it to e.g. inspect the names and types
* of the columns being written, read the statement's options and initialize some constant state.
*/
typedef struct _duckdb_v2_copy_to_bind_info {
void *internal_ptr;
} * duckdb_v2_copy_to_bind_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the "batch size" phase of a `COPY ...
* TO` statement. The "batch size" callback receives this handle and must use it to report how many rows a batch should
* carry.
*/
typedef struct _duckdb_v2_copy_to_batch_size_info {
void *internal_ptr;
} * duckdb_v2_copy_to_batch_size_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the per-file "init" phase of a `COPY ...
* TO` statement. The "init" callback receives this handle and can use it to e.g. read the path of the file being
* written and set up the state shared by every batch written to that file.
*/
typedef struct _duckdb_v2_copy_to_init_info {
void *internal_ptr;
} * duckdb_v2_copy_to_init_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the "batch" phase of a `COPY ... TO`
* statement. The "batch" callback receives this handle and can use it to take ownership of the rows of the batch and to
* set the prepared form of the batch handed to the "flush" callback.
*/
typedef struct _duckdb_v2_copy_to_batch_info {
void *internal_ptr;
} * duckdb_v2_copy_to_batch_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the "flush" phase of a `COPY ... TO`
* statement. The "flush" callback receives this handle and can use it to access the prepared batch and write it to the
* output.
*/
typedef struct _duckdb_v2_copy_to_flush_info {
void *internal_ptr;
} * duckdb_v2_copy_to_flush_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the per-file "finalize" phase of a `COPY
* ... TO` statement. The "finalize" callback receives this handle and can use it to e.g. close the file after every
* batch has been flushed to it.
*/
typedef struct _duckdb_v2_copy_to_finalize_info {
void *internal_ptr;
} * duckdb_v2_copy_to_finalize_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function when a `COPY ... TO` statement reports
* statistics about the files it wrote (e.g. with `RETURN_STATS`). The "statistics" callback receives this handle and
* uses it to report the statistics of one written file.
*/
typedef struct _duckdb_v2_copy_to_statistics_info {
void *internal_ptr;
} * duckdb_v2_copy_to_statistics_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the query preparation "bind" phase of a
* `COPY ... FROM` statement. The "bind" callback receives this handle and can use it to e.g. read the path of the file
* to read, inspect the names and types of the columns the target table expects, read the statement's options, hint at
* the number of rows the read will produce and initialize some constant state.
*/
typedef struct _duckdb_v2_copy_from_bind_info {
void *internal_ptr;
} * duckdb_v2_copy_from_bind_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the global state initialization "init
* global" phase of a `COPY ... FROM` statement. The "init global" callback receives this handle and can use it to e.g.
* set up the state shared by every thread reading the file, and to declare how many threads may read it.
*/
typedef struct _duckdb_v2_copy_from_init_global_info {
void *internal_ptr;
} * duckdb_v2_copy_from_init_global_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the local state initialization "init
* local" phase of a `COPY ... FROM` statement. The "init local" callback receives this handle and can use it to e.g.
* set up worker-local state, typically by claiming work from the shared global state.
*/
typedef struct _duckdb_v2_copy_from_init_local_info {
void *internal_ptr;
} * duckdb_v2_copy_from_init_local_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the execution "exec" phase of a `COPY
* ... FROM` statement. The "exec" callback receives this handle and can use it to e.g. access the global and local
* state and write the next batch of rows to the output chunk.
*/
typedef struct _duckdb_v2_copy_from_exec_info {
void *internal_ptr;
} * duckdb_v2_copy_from_exec_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a copy function during the "progress" phase of a `COPY ...
* FROM` statement. The "progress" callback receives this handle and can use it to report how far the read has advanced.
*/
typedef struct _duckdb_v2_copy_from_progress_info {
void *internal_ptr;
} * duckdb_v2_copy_from_progress_info_handle;
/* --- Constants for copy --- */
/* --- Function pointer typedefs for copy --- */
typedef void (*duckdb_v2_copy_to_bind_callback_fn)(duckdb_v2_copy_to_bind_info_handle info,
duckdb_v2_context_handle context, duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_to_batch_size_callback_fn)(duckdb_v2_copy_to_batch_size_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_to_init_callback_fn)(duckdb_v2_copy_to_init_info_handle info,
duckdb_v2_context_handle context, duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_to_batch_callback_fn)(duckdb_v2_copy_to_batch_info_handle info,
duckdb_v2_context_handle context, duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_to_flush_callback_fn)(duckdb_v2_copy_to_flush_info_handle info,
duckdb_v2_context_handle context, duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_to_finalize_callback_fn)(duckdb_v2_copy_to_finalize_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_to_statistics_callback_fn)(duckdb_v2_copy_to_statistics_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_from_bind_callback_fn)(duckdb_v2_copy_from_bind_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_from_init_global_callback_fn)(duckdb_v2_copy_from_init_global_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_from_init_local_callback_fn)(duckdb_v2_copy_from_init_local_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_from_exec_callback_fn)(duckdb_v2_copy_from_exec_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_copy_from_progress_callback_fn)(duckdb_v2_copy_from_progress_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
/* --- Functions for copy --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new copy function through a factory.
*
* A copy function implements a file format for `COPY`: once registered, SQL reaches it with `COPY ... TO 'path' (FORMAT
* name)` and `COPY table FROM 'path' (FORMAT name)`. The function starts out empty: configure it with the setter
* functions (e.g. `duckdb_v2_copy_function_set_name()`, the `copy_to_set_*` callbacks for writing, the
* `copy_from_set_*` callbacks for reading, or both), then make it available with
* `duckdb_v2_connection_register_copy_function()` or `duckdb_v2_extension_register_copy_function()`. The caller owns
* the returned handle and must destroy it with `duckdb_v2_copy_function_destroy()`, also after registration.
*
* The copy function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the copy function through.
* @param function On success, receives the newly created copy function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_function_create(duckdb_v2_factory_handle factory,
duckdb_v2_copy_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the copy function.
*
* The name is the format SQL selects the function with: `COPY ... TO 'path' (FORMAT name)` or `COPY table FROM 'path'
* (FORMAT name)`. It is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_function_set_name(duckdb_v2_copy_function_handle function,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the file extension of the files the copy function writes, without the leading dot, e.g. `parquet`.
*
* DuckDB uses it when it names files itself, e.g. the files of `COPY ... TO 'dir' (PARTITION_BY ...)` or
* `(PER_THREAD_OUTPUT)`. A statement can override it with the `FILE_EXTENSION` option. An extension starting with a dot
* is rejected. The extension is borrowed and copied. Calling this again replaces the previous extension. Optional, but
* without it the names DuckDB gives files end in a bare dot, e.g. `data_0.`.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the file extension of.
* @param extension The extension to set, without the leading dot. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_function_set_file_extension(duckdb_v2_copy_function_handle function,
const duckdb_v2_str *extension,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the copy function.
*
* Associates an opaque pointer with the function, retrievable from each callback of either side via its user data
* accessor (e.g. `duckdb_v2_copy_to_bind_get_user_data()`, `duckdb_v2_copy_from_exec_get_user_data()`, etc.). The
* opaque handle bundles the pointer with an optional destructor, invoked when the data is no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_function_set_user_data(duckdb_v2_copy_function_handle function,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional bind callback of the `COPY ... TO` side.
*
* The bind callback is invoked during query planning for each `COPY ... TO` statement that uses the function. It can
* inspect the names and types of the columns being written, read the statement's options and set "bind data" that is
* shared with the other `COPY ... TO` callbacks.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_set_bind_callback(duckdb_v2_copy_function_handle function,
duckdb_v2_copy_to_bind_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional batch size callback of the `COPY ... TO` side.
*
* The batch size callback is invoked during query planning, after the bind callback, for each `COPY ... TO` statement
* that does not set `BATCH_SIZE` itself. It should report how many rows a batch should carry via
* `duckdb_v2_copy_to_batch_size_set_target()`; the engine then cuts the rows being written into batches of that size
* and hands each to the batch callback. Without a batch size from either the statement or the callback, a batch is cut
* for every chunk of rows sunk, i.e. a vector at a time. A batch may still be smaller than the reported size (the last
* one of a file, or when `BATCH_SIZE_BYTES` cuts it first).
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_set_batch_size_callback(
duckdb_v2_copy_function_handle function, duckdb_v2_copy_to_batch_size_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional init callback of the `COPY ... TO` side.
*
* The init callback is invoked once per output file, before any batch destined for that file is prepared. It can read
* the path of the file via `duckdb_v2_copy_to_init_get_file_path()` and set "init data" that is shared with the batch,
* flush and finalize callbacks of that file. A statement may write several files, e.g. when its output is partitioned;
* each gets its own init data.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_set_init_callback(duckdb_v2_copy_function_handle function,
duckdb_v2_copy_to_init_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the batch callback of the `COPY ... TO` side.
*
* The batch callback is invoked during query execution with a batch of the rows being written, taken via
* `duckdb_v2_copy_to_batch_take_input()`. It prepares the batch for writing, e.g. by encoding it into the output
* format, and sets "batch data" via `duckdb_v2_copy_to_batch_set_batch_data()` that is handed to the flush callback.
* Batches may be prepared by several threads at once, so the callback must synchronize its own access to the init data.
* A batch callback must be set for the `COPY ... TO` side to be registered.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_set_batch_callback(duckdb_v2_copy_function_handle function,
duckdb_v2_copy_to_batch_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the flush callback of the `COPY ... TO` side.
*
* The flush callback is invoked once per prepared batch to write its batch data, available via
* `duckdb_v2_copy_to_flush_get_batch_data()`, to the output. Flushes of the same file never run concurrently. A flush
* callback must be set for the `COPY ... TO` side to be registered.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_set_flush_callback(duckdb_v2_copy_function_handle function,
duckdb_v2_copy_to_flush_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional finalize callback of the `COPY ... TO` side.
*
* The finalize callback is invoked once per output file after the last batch destined for that file has been flushed.
* It can e.g. write a footer and close the file.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_set_finalize_callback(duckdb_v2_copy_function_handle function,
duckdb_v2_copy_to_finalize_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_user_data(duckdb_v2_copy_to_bind_info_handle info, void **data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's "bind data" from the bind callback.
*
* The bind data is stored with the bound statement and retrievable from the other callbacks of the same side. The
* opaque handle bundles the pointer with an optional destructor, invoked when the bind data is no longer needed, and an
* optional equality callback used when comparing two bound statements; without one, pointer equality is used.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param data Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_set_bind_data(duckdb_v2_copy_to_bind_info_handle info,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the path the `COPY ... TO` statement writes to, as written in the statement.
*
* This is the target before the engine's own rewrites: the path of each file actually being written, e.g. a temporary
* name or a per-partition path, is only known to the init callback via `duckdb_v2_copy_to_init_get_file_path()`. The
* path is borrowed and valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param path Receives a borrowed view of the file path. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_file_path(duckdb_v2_copy_to_bind_info_handle info,
duckdb_v2_str *path,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns being written, i.e. the columns of the rows every batch carries.
*
* Valid indices for `duckdb_v2_copy_to_bind_get_column_type()` and `duckdb_v2_copy_to_bind_get_column_name()` are [0,
* count).
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param count Receives the number of columns.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_column_count(duckdb_v2_copy_to_bind_info_handle info,
idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the type of the column at the given index.
*
* Fails if the index is out of bounds. The returned type is owned by the caller and must be destroyed via
* `duckdb_v2_logical_type_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the column to get the type of.
* @param type Receives the column type. Owned by the caller; destroy via `duckdb_v2_logical_type_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_column_type(duckdb_v2_copy_to_bind_info_handle info,
idx_t index, duckdb_v2_logical_type_handle *type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the name of the column at the given index.
*
* Fails if the index is out of bounds. The name is borrowed and valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the column to get the name of.
* @param name Receives a borrowed view of the column name. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_column_name(duckdb_v2_copy_to_bind_info_handle info,
idx_t index, duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of options the `COPY` statement passed to the function.
*
* The engine's own options (e.g. `USE_TMP_FILE` or `BATCH_SIZE`) are handled before the function sees the statement and
* are not included. Valid indices for `duckdb_v2_copy_to_bind_get_option_name()` and
* `duckdb_v2_copy_to_bind_get_option_value()` are [0, count). The options are ordered by name.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param count Receives the number of options.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_option_count(duckdb_v2_copy_to_bind_info_handle info,
idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the name of the option at the given index.
*
* Option names are SQL identifiers, matched case-insensitively. Fails if the index is out of bounds. The name is
* borrowed and valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the option to get the name of.
* @param name Receives a borrowed view of the option name. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_option_name(duckdb_v2_copy_to_bind_info_handle info,
idx_t index, duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the value of the option at the given index.
*
* An option written with a single value (e.g. `DELIM ','`) yields that value. An option written as a bare name (e.g.
* `HEADER`) yields the BOOLEAN `true`. An option written with a parenthesized list (e.g. `KEYS (a, b)`) yields a tuple:
* an unnamed STRUCT with one field per element, in order. Fails if the index is out of bounds. The returned value is
* owned by the caller and must be destroyed via `duckdb_v2_value_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the option.
* @param value Receives the option's value. Owned by the caller; destroy via `duckdb_v2_value_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_bind_get_option_value(duckdb_v2_copy_to_bind_info_handle info,
idx_t index, duckdb_v2_value_handle *value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch size info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_size_get_user_data(duckdb_v2_copy_to_batch_size_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... TO` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch size info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_size_get_bind_data(duckdb_v2_copy_to_batch_size_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the number of rows a batch should carry, as the target the engine cuts batches at. The batch size callback must
* set this to a value greater than 0; the statement fails otherwise. DuckDB defines the `BATCH_SIZE` on omission of
* calling the function.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch size info handle.
* @param rows The number of rows a batch should carry. Must be greater than 0.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_size_set_target(duckdb_v2_copy_to_batch_size_info_handle info,
idx_t rows, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_init_get_user_data(duckdb_v2_copy_to_init_info_handle info, void **data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... TO` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_init_get_bind_data(duckdb_v2_copy_to_init_info_handle info, void **data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the path of the file the init callback is preparing.
*
* This is the path the batches of this file are to be written to, after the engine has applied its own rewrites (e.g. a
* temporary name while the file is being written, or a per-partition path). The path is borrowed and valid only for the
* duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param path Receives a borrowed view of the file path. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_init_get_file_path(duckdb_v2_copy_to_init_info_handle info,
duckdb_v2_str *path,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's "init data" from the init callback.
*
* The init data lives for the duration of the file being written and is retrievable from the batch, flush and finalize
* callbacks of that file. Batches may be prepared by several threads at once, so the function must synchronize its own
* access to it from the batch callback. The opaque handle bundles the pointer with an optional destructor, invoked when
* the file is done with the data.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Opaque handle bundling the init data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_init_set_init_data(duckdb_v2_copy_to_init_info_handle info,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_get_user_data(duckdb_v2_copy_to_batch_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... TO` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_get_bind_data(duckdb_v2_copy_to_batch_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the init data set by the function's `COPY ... TO` init callback for the file this batch belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch info handle.
* @param data Receives the init data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_get_init_data(duckdb_v2_copy_to_batch_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Takes ownership of the rows of the batch to prepare.
*
* The collection holds one column per column reported by `duckdb_v2_copy_to_bind_get_column_count()`, in the same
* order, and can be scanned with `duckdb_v2_column_data_collection_scan()`. The batch can only be taken once: a second
* call fails. Once taken, the caller owns the collection and must destroy it via
* `duckdb_v2_column_data_collection_destroy()`, e.g. by keeping it as the batch data with that destructor. A batch that
* is never taken is destroyed when the callback returns.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch info handle.
* @param collection Receives the collection holding the rows of the batch. Owned by the caller; destroy via
* `duckdb_v2_column_data_collection_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_take_input(duckdb_v2_copy_to_batch_info_handle info,
duckdb_v2_column_data_collection_handle *collection,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the prepared "batch data" from the batch callback.
*
* The batch data is the prepared form of the batch and is handed to the flush callback via
* `duckdb_v2_copy_to_flush_get_batch_data()`. The opaque handle bundles the pointer with an optional destructor,
* invoked once the batch has been flushed.
*
* history:
* - unstable: v2.0.0
*
* @param info The batch info handle.
* @param data Opaque handle bundling the batch data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_batch_set_batch_data(duckdb_v2_copy_to_batch_info_handle info,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The flush info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_flush_get_user_data(duckdb_v2_copy_to_flush_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... TO` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The flush info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_flush_get_bind_data(duckdb_v2_copy_to_flush_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the init data set by the function's `COPY ... TO` init callback for the file this batch belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param info The flush info handle.
* @param data Receives the init data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_flush_get_init_data(duckdb_v2_copy_to_flush_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the batch data set by the function's batch callback for the batch being flushed.
*
* history:
* - unstable: v2.0.0
*
* @param info The flush info handle.
* @param data Receives the batch data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_flush_get_batch_data(duckdb_v2_copy_to_flush_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_finalize_get_user_data(duckdb_v2_copy_to_finalize_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... TO` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_finalize_get_bind_data(duckdb_v2_copy_to_finalize_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the init data set by the function's `COPY ... TO` init callback for the file being finalized.
*
* history:
* - unstable: v2.0.0
*
* @param info The finalize info handle.
* @param data Receives the init data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_finalize_get_init_data(duckdb_v2_copy_to_finalize_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the bind callback of the `COPY ... FROM` side.
*
* The bind callback is invoked during query planning for each `COPY ... FROM` statement that uses the function. It can
* read the path of the file to read and the statement's options, inspect the names and types of the columns the target
* table expects, hint at the number of rows the read will produce, and set "bind data" that is shared with the other
* `COPY ... FROM` callbacks. The columns are fixed by the target table: the function must produce them as they are. A
* bind callback must be set for the `COPY ... FROM` side to be registered.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_set_bind_callback(duckdb_v2_copy_function_handle function,
duckdb_v2_copy_from_bind_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional global init callback of the `COPY ... FROM` side.
*
* The global init callback is invoked once per statement, at the start of execution. It can set "global state" shared
* by every thread reading the file, and declare how many threads may read it in parallel via
* `duckdb_v2_copy_from_init_global_set_max_threads()`.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_set_init_global_callback(
duckdb_v2_copy_function_handle function, duckdb_v2_copy_from_init_global_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional local init callback of the `COPY ... FROM` side.
*
* The local init callback is invoked once per thread that will read the file. It can set worker-local "local state",
* retrievable from the exec callback, typically derived from the shared global state.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_set_init_local_callback(
duckdb_v2_copy_function_handle function, duckdb_v2_copy_from_init_local_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the exec callback of the `COPY ... FROM` side.
*
* The exec callback implements the read: it is invoked repeatedly during query execution and writes the next batch of
* rows to the output chunk, until it produces an empty batch to signal the end of the read. An exec callback must be
* set for the `COPY ... FROM` side to be registered.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_set_exec_callback(duckdb_v2_copy_function_handle function,
duckdb_v2_copy_from_exec_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional progress callback of the `COPY ... FROM` side.
*
* The progress callback is invoked on demand during execution to report how far the read has advanced, which the engine
* surfaces as the query's progress. It is invoked concurrently with the exec callback, so it must read the global state
* in a thread-safe way.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_set_progress_callback(
duckdb_v2_copy_function_handle function, duckdb_v2_copy_from_progress_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_user_data(duckdb_v2_copy_from_bind_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's "bind data" from the bind callback.
*
* The bind data is stored with the bound statement and retrievable from the other callbacks of the same side. The
* opaque handle bundles the pointer with an optional destructor, invoked when the bind data is no longer needed, and an
* optional equality callback used when comparing two bound statements; without one, pointer equality is used.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param data Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_set_bind_data(duckdb_v2_copy_from_bind_info_handle info,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the path the `COPY ... FROM` statement reads from, as written in the statement.
*
* The engine does not expand globs or check that the file exists; both are left to the function. The path is borrowed
* and valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param path Receives a borrowed view of the file path. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_file_path(duckdb_v2_copy_from_bind_info_handle info,
duckdb_v2_str *path,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns the target table expects, i.e. the columns every batch the exec callback produces must
* carry, in this order.
*
* Valid indices for `duckdb_v2_copy_from_bind_get_column_type()` and `duckdb_v2_copy_from_bind_get_column_name()` are
* [0, count).
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param count Receives the number of columns.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_column_count(duckdb_v2_copy_from_bind_info_handle info,
idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the type of the column at the given index.
*
* Fails if the index is out of bounds. The returned type is owned by the caller and must be destroyed via
* `duckdb_v2_logical_type_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the column to get the type of.
* @param type Receives the column type. Owned by the caller; destroy via `duckdb_v2_logical_type_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_column_type(duckdb_v2_copy_from_bind_info_handle info,
idx_t index, duckdb_v2_logical_type_handle *type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the name of the column at the given index.
*
* Fails if the index is out of bounds. The name is borrowed and valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the column to get the name of.
* @param name Receives a borrowed view of the column name. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_column_name(duckdb_v2_copy_from_bind_info_handle info,
idx_t index, duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of options the `COPY` statement passed to the function.
*
* Every option other than `FORMAT` is included. Valid indices for `duckdb_v2_copy_from_bind_get_option_name()` and
* `duckdb_v2_copy_from_bind_get_option_value()` are [0, count). The options are ordered by name.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param count Receives the number of options.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_option_count(duckdb_v2_copy_from_bind_info_handle info,
idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the name of the option at the given index.
*
* Option names are SQL identifiers, matched case-insensitively. Fails if the index is out of bounds. The name is
* borrowed and valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the option to get the name of.
* @param name Receives a borrowed view of the option name. Valid only for the duration of the callback.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_option_name(duckdb_v2_copy_from_bind_info_handle info,
idx_t index, duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the value of the option at the given index.
*
* An option written with a single value (e.g. `DELIM ','`) yields that value. An option written as a bare name (e.g.
* `HEADER`) yields the BOOLEAN `true`. An option written with a parenthesized list (e.g. `KEYS (a, b)`) yields a tuple:
* an unnamed STRUCT with one field per element, in order. Fails if the index is out of bounds. The returned value is
* owned by the caller and must be destroyed via `duckdb_v2_value_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param index The index of the option.
* @param value Receives the option's value. Owned by the caller; destroy via `duckdb_v2_value_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_get_option_value(duckdb_v2_copy_from_bind_info_handle info,
idx_t index, duckdb_v2_value_handle *value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports the estimated number of rows the read will produce.
*
* The estimate is a hint for the optimizer, not a limit: producing a different number of rows is not an error. Without
* it, the optimizer falls back on its own defaults.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param cardinality The estimated number of rows.
* @param is_exact Whether the estimate is exact, which also makes it an upper bound on the row count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_bind_set_cardinality(duckdb_v2_copy_from_bind_info_handle info,
idx_t cardinality, bool is_exact,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_global_get_user_data(
duckdb_v2_copy_from_init_global_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... FROM` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_global_get_bind_data(
duckdb_v2_copy_from_init_global_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's "global state" from the global init callback.
*
* The global state lives for the duration of the read and is retrievable from the local init, exec and progress
* callbacks. Every thread reading the file shares it, so the function must synchronize its own access to it. The opaque
* handle bundles the pointer with an optional destructor, invoked when the read is done with the state.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param data Opaque handle bundling the global state pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_global_set_global_state(
duckdb_v2_copy_from_init_global_info_handle info, duckdb_v2_opaque *data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets how many threads may read the file in parallel.
*
* Defaults to 1, a single-threaded read. The engine creates at most this many local states, and therefore runs at most
* this many exec callbacks concurrently. It is an upper bound, not a request: the engine may use fewer threads.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param max_threads The maximum number of threads. Must be at least 1.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_global_set_max_threads(
duckdb_v2_copy_from_init_global_info_handle info, idx_t max_threads, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_local_get_user_data(
duckdb_v2_copy_from_init_local_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... FROM` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_local_get_bind_data(
duckdb_v2_copy_from_init_local_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* Shared with every other thread reading the file; access to it must be synchronized by the function.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_local_get_global_state(
duckdb_v2_copy_from_init_local_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's worker-local "local state" from the local init callback.
*
* The local state is associated with the executing thread for the duration of the read and retrievable from the exec
* callback via `duckdb_v2_copy_from_exec_get_local_state()`. No other thread observes it, so it needs no
* synchronization. The opaque handle bundles the pointer with an optional destructor, invoked when the local state is
* no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Opaque handle bundling the local state pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_init_local_set_local_state(
duckdb_v2_copy_from_init_local_info_handle info, duckdb_v2_opaque *data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_exec_get_user_data(duckdb_v2_copy_from_exec_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... FROM` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_exec_get_bind_data(duckdb_v2_copy_from_exec_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* Shared with every other thread reading the file; access to it must be synchronized by the function.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_exec_get_global_state(duckdb_v2_copy_from_exec_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the worker-local local state set by the function's local init callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the local state pointer for the executing thread, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_exec_get_local_state(duckdb_v2_copy_from_exec_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the output chunk the exec callback must write the next batch of rows into.
*
* The chunk holds one vector per column reported by `duckdb_v2_copy_from_bind_get_column_count()`, in the same order;
* reach them with `duckdb_v2_data_chunk_get_vector()`. The chunk starts out empty on every invocation: write the rows,
* then declare how many there are with `duckdb_v2_vector_set_size()` on the first vector, which the engine takes as the
* batch's row count and propagates to the other vectors. Producing an empty batch signals the end of the read, after
* which the callback is not invoked again on that thread. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param chunk Receives the borrowed output chunk to write into.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_exec_get_output_chunk(duckdb_v2_copy_from_exec_info_handle info,
duckdb_v2_data_chunk_handle *chunk,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_progress_get_user_data(duckdb_v2_copy_from_progress_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... FROM` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_progress_get_bind_data(duckdb_v2_copy_from_progress_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* The progress callback runs concurrently with the exec callbacks reading the file, so it must read the global state in
* a thread-safe way.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_progress_get_global_state(
duckdb_v2_copy_from_progress_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports how far the read has advanced.
*
* A fraction between 0.0 (nothing read yet) and 1.0 (done); values outside that range are clamped. A progress callback
* that returns without calling this reports no progress.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param progress The fraction of the read that is complete, in [0.0, 1.0].
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_from_progress_set_progress(duckdb_v2_copy_from_progress_info_handle info,
double progress,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the copy function, making it available as a `COPY` format.
*
* The function is registered on the connection's database, visible to every connection, in the connection's
* transaction: inside an explicit transaction, it is invisible to other connections until the transaction commits, and
* a rollback undoes it. Registration requires a name and at least one configured side: a `COPY ... TO` side needs its
* batch and flush callbacks, a `COPY ... FROM` side needs its bind and exec callbacks. A statement in a direction the
* function does not implement fails with an error. The copy function must have been created through a factory of the
* same database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_copy_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param function The copy function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_copy_function(duckdb_v2_connection_handle conn,
duckdb_v2_copy_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the copy function, making it available as a `COPY` format.
*
* The function is registered on the loading extension's database and attributed to the extension. Use this from the
* extension's load callback. Registration requires a name and at least one configured side: a `COPY ... TO` side needs
* its batch and flush callbacks, a `COPY ... FROM` side needs its bind and exec callbacks. A statement in a direction
* the function does not implement fails with an error. The copy function must have been created through a factory of
* the same database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_copy_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The copy function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_copy_function(duckdb_v2_extension_handle extension,
duckdb_v2_copy_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the copy function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_function_destroy(duckdb_v2_copy_function_handle *function);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional statistics callback of the `COPY ... TO` side.
*
* The statistics callback reports statistics about a written file, such as the number of rows and bytes it holds, which
* `COPY ... TO` returns when the statement asks for them with `RETURN_STATS`. It is invoked once per output file, after
* the finalize callback of that file, and only when the statement asks for the statistics. Without a statistics
* callback, `RETURN_STATS` is rejected for the function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_set_statistics_callback(
duckdb_v2_copy_function_handle function, duckdb_v2_copy_to_statistics_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set on the copy function via `duckdb_v2_copy_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The statistics info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_statistics_get_user_data(duckdb_v2_copy_to_statistics_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's `COPY ... TO` bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The statistics info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_statistics_get_bind_data(duckdb_v2_copy_to_statistics_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the init data set by the function's `COPY ... TO` init callback for the file being reported.
*
* history:
* - unstable: v2.0.0
*
* @param info The statistics info handle.
* @param data Receives the init data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_statistics_get_init_data(duckdb_v2_copy_to_statistics_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports how many rows were written to the file. Reported as 0 when the callback does not set it.
*
* history:
* - unstable: v2.0.0
*
* @param info The statistics info handle.
* @param row_count The number of rows written to the file.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_statistics_set_row_count(duckdb_v2_copy_to_statistics_info_handle info,
idx_t row_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports the size of the written file in bytes. Reported as 0 when the callback does not set it.
*
* history:
* - unstable: v2.0.0
*
* @param info The statistics info handle.
* @param file_size_bytes The size of the file in bytes.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_copy_to_statistics_set_file_size(duckdb_v2_copy_to_statistics_info_handle info,
idx_t file_size_bytes,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for copy --- */
/* ============================================================================
* MODULE: custom_option
* ============================================================================ */
/* --- Enums for custom_option --- */
/* --- Struct forward declarations for custom_option --- */
/* --- Types for custom_option --- */
/*!
* An owned opaque handle to a custom option being built. Created with `duckdb_v2_custom_option_create()`, configured
* with the setter functions (e.g. `duckdb_v2_custom_option_set_name()`, `duckdb_v2_custom_option_set_type()`, etc.),
* made available with `duckdb_v2_connection_register_custom_option()` or
* `duckdb_v2_extension_register_custom_option()`, and destroyed with `duckdb_v2_custom_option_destroy()`.
*/
typedef struct _duckdb_v2_custom_option {
void *internal_ptr;
} * duckdb_v2_custom_option_handle;
/*!
* A borrowed opaque handle to an update of a custom option, received by its update callback. It gives access to the new
* value, the scope it is written at and the user data, and can replace the value.
*/
typedef struct _duckdb_v2_custom_option_update_info {
void *internal_ptr;
} * duckdb_v2_custom_option_update_info_handle;
/* --- Constants for custom_option --- */
/* --- Function pointer typedefs for custom_option --- */
typedef void (*duckdb_v2_custom_option_update_callback_fn)(duckdb_v2_custom_option_update_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
/* --- Functions for custom_option --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new custom option through a factory.
*
* The option starts out empty: configure it with the setter functions, then make it available with
* `duckdb_v2_connection_register_custom_option()` or `duckdb_v2_extension_register_custom_option()`. The caller owns
* the returned handle and must destroy it with `duckdb_v2_custom_option_destroy()`, also after registration.
*
* The custom option can only be registered on the instance the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the custom option through.
* @param option On success, receives the newly created custom option. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_create(duckdb_v2_factory_handle factory,
duckdb_v2_custom_option_handle *option,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the custom option, as `SET` and the config functions refer to it.
*
* The name is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_name(duckdb_v2_custom_option_handle option,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the type of the custom option. Every value written to the option is cast to it, as SQL `SET` does.
*
* The type is borrowed and copied. Optional when a default value is set, whose type the option then takes.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to set the type of.
* @param type The type to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_type(duckdb_v2_custom_option_handle option,
duckdb_v2_logical_type_handle type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the default value of the custom option: its value until it is set, and the value `RESET` restores.
*
* The value is borrowed and copied, and cast to the option's type at registration, which fails when the cast does.
* Without a default value the option reads as NULL until it is set.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to set the default value of.
* @param value The default value. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_default_value(duckdb_v2_custom_option_handle option,
duckdb_v2_value_handle value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the description of the custom option, as `duckdb_v2_option_get_description()` and `duckdb_settings()` report it.
*
* The description is borrowed and copied. Calling this again replaces the previous description.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to set the description of.
* @param description The description to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_description(duckdb_v2_custom_option_handle option,
const duckdb_v2_str *description,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the scope a write at `SETTING_SCOPE_DEFAULT` goes to, like SQL `SET name = value`.
*
* Must be GLOBAL or SESSION, and a scope the option supports. Defaults to SESSION, or to GLOBAL when the option does
* not support SESSION.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to set the default scope of.
* @param scope The default scope, GLOBAL or SESSION.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_default_scope(duckdb_v2_custom_option_handle option,
DUCKDB_V2_SETTING_SCOPE scope,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets whether the custom option can be written at a scope, as `duckdb_v2_option_supports_scope()` reports it.
*
* A custom option supports both GLOBAL and SESSION unless told otherwise. A write at a scope it does not support fails,
* from SQL as from `duckdb_v2_config_set_option_value()`. Registration fails when the option supports neither scope.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to configure.
* @param scope The scope, GLOBAL or SESSION.
* @param supported Whether the option can be written at the scope.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_supports_scope(duckdb_v2_custom_option_handle option,
DUCKDB_V2_SETTING_SCOPE scope, bool supported,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the custom option.
*
* Associates an opaque pointer with the option, retrievable from the update callback via
* `duckdb_v2_custom_option_update_get_user_data()`. The opaque handle bundles the pointer with an optional destructor,
* invoked when the data is no longer needed: once the custom option handle is destroyed and, if it was registered, the
* instance is too.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_user_data(duckdb_v2_custom_option_handle option,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional update callback of the custom option.
*
* The callback is invoked whenever the option is set or reset, from SQL as from `duckdb_v2_config_set_option_value()`,
* after the new value is cast to the option's type and before it is stored. It may replace the value with
* `duckdb_v2_custom_option_update_set_value()`, or refuse it by reporting an error. It is not invoked for the default
* value at registration, nor for a value given to the instance at startup. The callback must not write options itself.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to set the update callback of.
* @param callback The update callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_set_update_callback(
duckdb_v2_custom_option_handle option, duckdb_v2_custom_option_update_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_custom_option_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_update_get_user_data(
duckdb_v2_custom_option_update_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the value the option is updated to, already cast to the option's type. On a reset this is the default
* value, which may be NULL. The returned value is owned by the caller and must be destroyed via
* `duckdb_v2_value_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param value Receives the new value. Owned by the caller; destroy via `duckdb_v2_value_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_update_get_value(duckdb_v2_custom_option_update_info_handle info,
duckdb_v2_value_handle *value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Replaces the value the option is updated to, e.g. to normalize it. The value is borrowed and copied, and cast to the
* option's type, which fails when the cast does.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param value The value to store instead. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_update_set_value(duckdb_v2_custom_option_update_info_handle info,
duckdb_v2_value_handle value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the scope the value is written at: GLOBAL or SESSION, a DEFAULT write already resolved to the option's
* default scope.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param scope Receives the scope.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_update_get_scope(duckdb_v2_custom_option_update_info_handle info,
DUCKDB_V2_SETTING_SCOPE *scope,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves whether the update is a reset to the default value, like SQL `RESET`.
*
* history:
* - unstable: v2.0.0
*
* @param info The update info handle.
* @param is_reset Receives whether the update is a reset.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_update_is_reset(duckdb_v2_custom_option_update_info_handle info,
bool *is_reset, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the custom option on the connection's instance, visible to every connection.
*
* Registration is not transactional: it takes effect at once, also inside an explicit transaction, and a rollback does
* not undo it. Registration requires a name and a type, or a default value to take the type from, and fails when an
* option of the same name already exists. A value given for the option at startup is picked up. The custom option must
* have been created through a factory of the same instance. The caller still owns the handle after registration and
* must destroy it with `duckdb_v2_custom_option_destroy()`, which does not affect the registered option.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param option The custom option to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_custom_option(duckdb_v2_connection_handle conn,
duckdb_v2_custom_option_handle option,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the custom option on the loading extension's instance, visible to every connection.
*
* Use this from the extension's load callback. Registration is not transactional, requires a name and a type, or a
* default value to take the type from, and fails when an option of the same name already exists. A value given for the
* option at startup is picked up. The custom option must have been created through a factory of the same instance. The
* caller still owns the handle after registration and must destroy it with `duckdb_v2_custom_option_destroy()`, which
* does not affect the registered option.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param option The custom option to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_custom_option(duckdb_v2_extension_handle extension,
duckdb_v2_custom_option_handle option,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the custom option, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered option.
*
* history:
* - unstable: v2.0.0
*
* @param option The option to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_custom_option_destroy(duckdb_v2_custom_option_handle *option);
#endif
/* --- Struct definitions for custom_option --- */
/* ============================================================================
* MODULE: expression
* ============================================================================ */
/* --- Enums for expression --- */
/*!
* The type of a bound expression node. The values mirror the engine's own expression types, restricted to the node
* types a filter predicate can contain; every other node type is reported as `EXPRESSION_TYPE_INVALID`.
*
* Comparisons, `BETWEEN` and casts are regular scalar function calls once bound: they have the function's children and
* name, and only their type tells them apart from any other function. A `CAST` therefore has one child, the value being
* cast, and its target type is the node's return type.
*/
typedef enum DUCKDB_V2_EXPRESSION_TYPE {
//! A node type this API does not model. Its children can still be walked.
DUCKDB_V2_EXPRESSION_TYPE_INVALID = 0,
/*!
* A cast. One child; the target type is the node's return type and `duckdb_v2_expression_cast_get_mode()` tells a
* `TRY_CAST` apart.
*/
DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_CAST = 12,
//! Logical `NOT`. One child.
DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_NOT = 13,
//! `IS NULL`. One child.
DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_IS_NULL = 14,
//! `IS NOT NULL`. One child.
DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_IS_NOT_NULL = 15,
//! `=`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_EQUAL = 25,
//! `<>`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_NOTEQUAL = 26,
//! `<`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_LESSTHAN = 27,
//! `>`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_GREATERTHAN = 28,
//! `<=`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_LESSTHANOREQUALTO = 29,
//! `>=`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_GREATERTHANOREQUALTO = 30,
//! `IN`. The first child is the value tested, the remaining children are the candidates.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_IN = 35,
//! `NOT IN`. The first child is the value tested, the remaining children are the candidates.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_NOT_IN = 36,
//! `IS DISTINCT FROM`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_DISTINCT_FROM = 37,
//! `BETWEEN`. Three children: the value tested, the lower bound and the upper bound.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_BETWEEN = 38,
//! `IS NOT DISTINCT FROM`. Two children.
DUCKDB_V2_EXPRESSION_TYPE_COMPARE_NOT_DISTINCT_FROM = 40,
//! Logical `AND`. Two or more children.
DUCKDB_V2_EXPRESSION_TYPE_CONJUNCTION_AND = 50,
//! Logical `OR`. Two or more children.
DUCKDB_V2_EXPRESSION_TYPE_CONJUNCTION_OR = 51,
//! A constant. No children; read it with `duckdb_v2_expression_constant_get_value()`.
DUCKDB_V2_EXPRESSION_TYPE_VALUE_CONSTANT = 75,
//! A prepared statement parameter whose value is not known yet. No children.
DUCKDB_V2_EXPRESSION_TYPE_VALUE_PARAMETER = 76,
/*!
* A call to a scalar function other than the ones listed above. The children are its arguments; read the name with
* `duckdb_v2_expression_function_get_name()`.
*/
DUCKDB_V2_EXPRESSION_TYPE_BOUND_FUNCTION = 141,
//! A `CASE` expression. The children are each `WHEN` condition followed by its `THEN` result, then the `ELSE`
//! result.
DUCKDB_V2_EXPRESSION_TYPE_CASE_EXPR = 150,
//! `COALESCE`. One or more children.
DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_COALESCE = 152,
//! A reference to a column. No children; read it with `duckdb_v2_expression_column_ref_get_index()`.
DUCKDB_V2_EXPRESSION_TYPE_BOUND_COLUMN_REF = 228,
DUCKDB_V2_EXPRESSION_TYPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_EXPRESSION_TYPE;
/* --- Struct forward declarations for expression --- */
/* --- Types for expression --- */
/*!
* A borrowed opaque handle to a node of a bound expression tree. Read-only and owned by the engine: valid only for the
* duration of the callback that handed it out, and never destroyed by the caller. Child nodes borrowed via
* `duckdb_v2_expression_get_child()` share their parent's lifetime.
*/
typedef struct _duckdb_v2_expression {
void *internal_ptr;
} * duckdb_v2_expression_handle;
/* --- Constants for expression --- */
/* --- Function pointer typedefs for expression --- */
/* --- Functions for expression --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the type of an expression node.
*
* The type decides which of the type-specific accessors apply, and what the node's children mean; see
* `EXPRESSION_TYPE`. A node of a type this API does not model reports `EXPRESSION_TYPE_INVALID`.
*
* history:
* - unstable: v2.0.0
*
* @param expression The expression node.
* @param type Receives the node type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_get_type(duckdb_v2_expression_handle expression,
DUCKDB_V2_EXPRESSION_TYPE *type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the logical type the expression node evaluates to.
*
* For a cast this is the target type. The returned type is owned by the caller and must be destroyed via
* `duckdb_v2_logical_type_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param expression The expression node.
* @param type Receives the owned logical type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_get_return_type(duckdb_v2_expression_handle expression,
duckdb_v2_logical_type_handle *type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of child nodes of an expression node.
*
* Works for every node type, including `EXPRESSION_TYPE_INVALID`. Constants, parameters and column references have no
* children.
*
* history:
* - unstable: v2.0.0
*
* @param expression The expression node.
* @param count Receives the number of children.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_get_child_count(duckdb_v2_expression_handle expression, idx_t *count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves a child node of an expression node by index.
*
* Fails if the index is out of bounds. Children are ordered as the node type describes (see `EXPRESSION_TYPE`). The
* child is borrowed and shares the lifetime of its parent.
*
* history:
* - unstable: v2.0.0
*
* @param expression The expression node.
* @param index The index of the child to retrieve.
* @param child Receives the borrowed child node.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_get_child(duckdb_v2_expression_handle expression, idx_t index,
duckdb_v2_expression_handle *child,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value of a constant node.
*
* Fails if the node is not of type `EXPRESSION_TYPE_VALUE_CONSTANT`. The returned value is owned by the caller and must
* be destroyed via `duckdb_v2_value_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param expression The constant node.
* @param value Receives the owned constant value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_constant_get_value(duckdb_v2_expression_handle expression,
duckdb_v2_value_handle *value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the column a column reference node points at.
*
* Fails if the node is not of type `EXPRESSION_TYPE_BOUND_COLUMN_REF`. The index counts the columns of the operator the
* predicate is evaluated against, which is not necessarily the full set of columns that operator can produce: a
* callback resolves it through whatever handed it the expression, e.g.
* `duckdb_v2_table_function_filter_pushdown_get_column_index()` for a filter offered to a table function.
*
* history:
* - unstable: v2.0.0
*
* @param expression The column reference node.
* @param index Receives the column index.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_column_ref_get_index(duckdb_v2_expression_handle expression,
idx_t *index, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the name of the scalar function a function node calls.
*
* Applies to `EXPRESSION_TYPE_BOUND_FUNCTION` and to the node types that are function calls underneath: the
* comparisons, `EXPRESSION_TYPE_COMPARE_BETWEEN` and `EXPRESSION_TYPE_OPERATOR_CAST`. Fails for any other node type.
* For a comparison the name is its operator, e.g. `<`; for `BETWEEN` and casts it is an internal name, so dispatch on
* the type rather than the name for those. The name is borrowed and shares the lifetime of the node.
*
* history:
* - unstable: v2.0.0
*
* @param expression The function node.
* @param name Receives a borrowed view of the function name.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_function_get_name(duckdb_v2_expression_handle expression,
duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the qualified name of the scalar function a function node calls.
*
* Applies to the same node types as `duckdb_v2_expression_function_get_name()`, and fails for any other. The name is
* qualified with the catalog and schema the function was resolved in, where known. The returned name is owned by the
* caller and must be destroyed via `duckdb_v2_qname_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param expression The function node.
* @param name Receives the owned qualified name.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_function_get_qname(duckdb_v2_expression_handle expression,
duckdb_v2_qname_handle *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns whether a cast node is a regular `CAST` or a `TRY_CAST`.
*
* Fails if the node is not of type `EXPRESSION_TYPE_OPERATOR_CAST`. A `TRY_CAST` yields NULL for a value it cannot
* convert where a regular `CAST` would fail the query.
*
* history:
* - unstable: v2.0.0
*
* @param expression The cast node.
* @param mode Receives the cast mode.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_expression_cast_get_mode(duckdb_v2_expression_handle expression,
DUCKDB_V2_CAST_MODE *mode,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for expression --- */
/* ============================================================================
* MODULE: log sink
* ============================================================================ */
/* --- Enums for log sink --- */
//! The scope a log entry was written in, which decides which of its ids are present.
typedef enum DUCKDB_V2_LOG_SCOPE {
//! Written for the database as a whole, carrying no connection, transaction or query id.
DUCKDB_V2_LOG_SCOPE_DATABASE = 10,
//! Written by a connection, carrying its connection id and, inside one, the transaction and query ids.
DUCKDB_V2_LOG_SCOPE_CONNECTION = 20,
//! Written by a thread executing a query, carrying the thread id next to the connection's ids.
DUCKDB_V2_LOG_SCOPE_THREAD = 30,
DUCKDB_V2_LOG_SCOPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_LOG_SCOPE;
/* --- Struct forward declarations for log sink --- */
/* --- Types for log sink --- */
/*!
* An owned opaque handle to a log sink being built. Created with `duckdb_v2_log_sink_create()`, configured with
* `duckdb_v2_log_sink_set_name()`, `duckdb_v2_log_sink_set_write_callback()` and the other setters, made available with
* `duckdb_v2_instance_register_log_sink()` or `duckdb_v2_extension_register_log_sink()`, and destroyed with
* `duckdb_v2_log_sink_destroy()`.
*/
typedef struct _duckdb_v2_log_sink {
void *internal_ptr;
} * duckdb_v2_log_sink_handle;
/*!
* A borrowed opaque handle to the context of a log entry, received by a log sink's write callback next to the entry
* itself, and valid only for the duration of that call. Read the ids `duckdb_logs` reports for the entry through its
* getters, e.g. `duckdb_v2_log_sink_write_info_get_connection_id()`.
*/
typedef struct _duckdb_v2_log_sink_write_info {
void *internal_ptr;
} * duckdb_v2_log_sink_write_info_handle;
/*!
* A borrowed opaque handle received by a log sink's flush callback, and valid only for the duration of that call. It
* carries nothing yet.
*/
typedef struct _duckdb_v2_log_sink_flush_info {
void *internal_ptr;
} * duckdb_v2_log_sink_flush_info_handle;
/* --- Constants for log sink --- */
/* --- Function pointer typedefs for log sink --- */
typedef void (*duckdb_v2_log_sink_write_callback_fn)(duckdb_v2_log_sink_write_info_handle info, void *user_data,
int64_t timestamp, DUCKDB_V2_LOG_LEVEL level,
DUCKDB_V2_LOG_SCOPE scope, const duckdb_v2_str *type,
const duckdb_v2_str *message, duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_log_sink_flush_callback_fn)(duckdb_v2_log_sink_flush_info_handle info, void *user_data,
duckdb_v2_error_info_handle *err);
/* --- Functions for log sink --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new log sink through a factory.
*
* The log sink starts out empty: configure it with the setter functions, then make it available with
* `duckdb_v2_instance_register_log_sink()` or `duckdb_v2_extension_register_log_sink()`. The caller owns the returned
* handle and must destroy it with `duckdb_v2_log_sink_destroy()`, also after registration.
*
* The log sink can only be registered on the instance the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the log sink through.
* @param sink On success, receives the newly created log sink. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_create(duckdb_v2_factory_handle factory,
duckdb_v2_log_sink_handle *sink,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name the logging configuration refers to the log sink by.
*
* Names are matched case-insensitively. The name is borrowed and copied. Calling this again replaces the previous name.
* A name must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param sink The log sink to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_set_name(duckdb_v2_log_sink_handle sink,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the log sink.
*
* Associates an opaque pointer with the sink, handed to its write and flush callbacks. The opaque handle bundles the
* pointer with an optional destructor, invoked when the data is no longer needed: when the instance is destroyed if the
* sink was registered, else when the log sink handle is.
*
* history:
* - unstable: v2.0.0
*
* @param sink The log sink to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_set_user_data(duckdb_v2_log_sink_handle sink, duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the write callback of the log sink, invoked for every entry the logging configuration directs to the sink.
*
* The callback must return quickly, must be safe to run concurrently and on any thread, and must not log or change the
* logging configuration. A write callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param sink The log sink to set the write callback of.
* @param callback The write callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_set_write_callback(duckdb_v2_log_sink_handle sink,
duckdb_v2_log_sink_write_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional flush callback of the log sink, invoked when DuckDB flushes its log, so entries the sink holds on
* to can be written out. When DuckDB flushes is up to DuckDB; entries still held when the instance is destroyed are for
* the user data's destructor to write out.
*
* Like the write callback, it must be safe to run on any thread, and must not log or change the logging configuration.
*
* history:
* - unstable: v2.0.0
*
* @param sink The log sink to set the flush callback of.
* @param callback The flush callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_set_flush_callback(duckdb_v2_log_sink_handle sink,
duckdb_v2_log_sink_flush_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the id of the connection that wrote the entry, as `duckdb_logs` reports it. An entry written for the
* database as a whole has none: `present` then receives false and `id` is left untouched.
*
* history:
* - unstable: v2.0.0
*
* @param info The write info handle of the entry.
* @param id Receives the connection id, if present.
* @param present Receives whether the entry has a connection id.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_write_info_get_connection_id(duckdb_v2_log_sink_write_info_handle info,
idx_t *id, bool *present,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the id of the transaction the entry was written in, as `duckdb_logs` reports it. An entry written outside a
* transaction has none: `present` then receives false and `id` is left untouched.
*
* history:
* - unstable: v2.0.0
*
* @param info The write info handle of the entry.
* @param id Receives the transaction id, if present.
* @param present Receives whether the entry has a transaction id.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_write_info_get_transaction_id(duckdb_v2_log_sink_write_info_handle info,
idx_t *id, bool *present,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the id of the query the entry was written for, as `duckdb_logs` reports it. An entry written outside a
* query has none: `present` then receives false and `id` is left untouched.
*
* history:
* - unstable: v2.0.0
*
* @param info The write info handle of the entry.
* @param id Receives the query id, if present.
* @param present Receives whether the entry has a query id.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_write_info_get_query_id(duckdb_v2_log_sink_write_info_handle info,
idx_t *id, bool *present,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the id of the thread that wrote the entry, as `duckdb_logs` reports it. Only an entry written in the thread
* scope has one: otherwise `present` receives false and `id` is left untouched. The id identifies the thread that
* logged, which need not be the thread the write callback runs on.
*
* history:
* - unstable: v2.0.0
*
* @param info The write info handle of the entry.
* @param id Receives the thread id, if present.
* @param present Receives whether the entry has a thread id.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_write_info_get_thread_id(duckdb_v2_log_sink_write_info_handle info,
idx_t *id, bool *present,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the log sink on the instance, making it available to the logging configuration under its name.
*
* Registering does not direct any entries to the sink by itself; the logging configuration does. Registration is not
* transactional, requires a name and a write callback, and fails when the name is taken: by a sink DuckDB provides
* itself, such as `memory`, `stdout` or `file`, or by a sink registered before. The log sink must have been created
* through a factory of the same instance. Its user data passes to the registered sink. The caller still owns the handle
* after registration and must destroy it with `duckdb_v2_log_sink_destroy()`, which does not affect the registered
* sink.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance to register on.
* @param sink The log sink to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_register_log_sink(duckdb_v2_instance_handle instance,
duckdb_v2_log_sink_handle sink,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the log sink on the loading extension's instance, making it available to the logging configuration under
* its name.
*
* Use this from the extension's load callback. Registration follows the rules of
* `duckdb_v2_instance_register_log_sink()`.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param sink The log sink to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_log_sink(duckdb_v2_extension_handle extension,
duckdb_v2_log_sink_handle sink,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the log sink, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered sink.
*
* history:
* - unstable: v2.0.0
*
* @param sink The log sink to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_log_sink_destroy(duckdb_v2_log_sink_handle *sink);
#endif
/* --- Struct definitions for log sink --- */
/* ============================================================================
* MODULE: logical_type
* ============================================================================ */
/* --- Enums for logical_type --- */
/*!
* Logical type identifier. The values are the same integers DuckDB uses internally, so round-tripping is lossless. The
* bind- and UDF-only ids (UNKNOWN, ANY, TEMPLATE) appear here for completeness; they do not show up in result column
* types in practice.
*/
typedef enum DUCKDB_V2_LOGICAL_TYPE_ID {
//! Invalid / unset.
DUCKDB_V2_LOGICAL_TYPE_ID_INVALID = 0,
//! NULL constant type.
DUCKDB_V2_LOGICAL_TYPE_ID_SQLNULL = 1,
//! Unknown — used for unresolved parameter expressions.
DUCKDB_V2_LOGICAL_TYPE_ID_UNKNOWN = 2,
//! ANY — used for functions that accept any type.
DUCKDB_V2_LOGICAL_TYPE_ID_ANY = 3,
//! A type carried as a value (type parameters). Values of this type are built via value_create_type.
DUCKDB_V2_LOGICAL_TYPE_ID_TYPE = 6,
DUCKDB_V2_LOGICAL_TYPE_ID_BOOLEAN = 10,
DUCKDB_V2_LOGICAL_TYPE_ID_TINYINT = 11,
DUCKDB_V2_LOGICAL_TYPE_ID_SMALLINT = 12,
DUCKDB_V2_LOGICAL_TYPE_ID_INTEGER = 13,
DUCKDB_V2_LOGICAL_TYPE_ID_BIGINT = 14,
//! 32-bit days since epoch.
DUCKDB_V2_LOGICAL_TYPE_ID_DATE = 15,
//! 64-bit microseconds since midnight.
DUCKDB_V2_LOGICAL_TYPE_ID_TIME = 16,
//! 64-bit seconds since epoch.
DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_SEC = 17,
//! 64-bit milliseconds since epoch.
DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_MS = 18,
//! 64-bit microseconds since epoch.
DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP = 19,
//! 64-bit nanoseconds since epoch.
DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_NS = 20,
//! Decimal with width and scale parameters.
DUCKDB_V2_LOGICAL_TYPE_ID_DECIMAL = 21,
DUCKDB_V2_LOGICAL_TYPE_ID_FLOAT = 22,
DUCKDB_V2_LOGICAL_TYPE_ID_DOUBLE = 23,
DUCKDB_V2_LOGICAL_TYPE_ID_VARCHAR = 25,
DUCKDB_V2_LOGICAL_TYPE_ID_BLOB = 26,
DUCKDB_V2_LOGICAL_TYPE_ID_INTERVAL = 27,
DUCKDB_V2_LOGICAL_TYPE_ID_UTINYINT = 28,
DUCKDB_V2_LOGICAL_TYPE_ID_USMALLINT = 29,
DUCKDB_V2_LOGICAL_TYPE_ID_UINTEGER = 30,
DUCKDB_V2_LOGICAL_TYPE_ID_UBIGINT = 31,
//! 64-bit microseconds since epoch, timezone-aware.
DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_TZ = 32,
//! 64-bit nanoseconds since epoch, timezone-aware.
DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_TZ_NS = 33,
//! 64-bit microseconds since midnight + 32-bit offset.
DUCKDB_V2_LOGICAL_TYPE_ID_TIME_TZ = 34,
//! 64-bit nanoseconds since midnight.
DUCKDB_V2_LOGICAL_TYPE_ID_TIME_NS = 35,
DUCKDB_V2_LOGICAL_TYPE_ID_BIT = 36,
//! Arbitrary-precision integer (VARINT-encoded).
DUCKDB_V2_LOGICAL_TYPE_ID_BIGNUM = 39,
DUCKDB_V2_LOGICAL_TYPE_ID_UHUGEINT = 49,
DUCKDB_V2_LOGICAL_TYPE_ID_HUGEINT = 50,
DUCKDB_V2_LOGICAL_TYPE_ID_UUID = 54,
//! Geometry (spatial extension).
DUCKDB_V2_LOGICAL_TYPE_ID_GEOMETRY = 60,
DUCKDB_V2_LOGICAL_TYPE_ID_STRUCT = 100,
DUCKDB_V2_LOGICAL_TYPE_ID_LIST = 101,
DUCKDB_V2_LOGICAL_TYPE_ID_MAP = 102,
DUCKDB_V2_LOGICAL_TYPE_ID_ENUM = 104,
DUCKDB_V2_LOGICAL_TYPE_ID_UNION = 107,
DUCKDB_V2_LOGICAL_TYPE_ID_ARRAY = 108,
DUCKDB_V2_LOGICAL_TYPE_ID_VARIANT = 109,
//! Unnamed struct; shares the physical representation of STRUCT.
DUCKDB_V2_LOGICAL_TYPE_ID_TUPLE = 110,
DUCKDB_V2_LOGICAL_TYPE_ID_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_LOGICAL_TYPE_ID;
/* --- Struct forward declarations for logical_type --- */
/* --- Types for logical_type --- */
/* --- Constants for logical_type --- */
/* --- Function pointer typedefs for logical_type --- */
/* --- Functions for logical_type --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a logical type from a type id plus value parameters.
*
* The id-keyed twin of factory_create_type_from_name: the type id names the kind, and the parameters bind it. With
* param_count 0 it instantiates a primitive directly, without touching the catalog: BOOLEAN, TINYINT..BIGINT,
* UTINYINT..UBIGINT, HUGEINT, UHUGEINT, FLOAT, DOUBLE, DATE, every TIME and TIMESTAMP variant, INTERVAL, VARCHAR, BLOB,
* BIT, BIGNUM, and UUID. ANY is accepted as well.
*
* ANY is a function-signature wildcard, constructible here so it can be passed to the function parameter and varargs
* setters, as a fixed-arity ANY parameter or an ANY varargs type. Data-creating surfaces reject it: value and data
* chunk creation, scalar and aggregate return types, table function result columns, cast source and target types, and
* custom type registration.
*
* With parameters, the id resolves to its canonical built-in type and binds through the same constructors as
* factory_create_type_from_name, so the parameterized kinds construct here too: decimal(width, scale); list(T);
* array(T, size); map(K, V); struct(fields); union(members); enum(entries); and varchar with a named "collation"
* parameter. Parameters are (name, value) pairs in two parallel arrays, exactly as for factory_create_type_from_name.
*
* Returns ERROR_INPUT_INVALID when param_count is 0 and the id needs parameters (DECIMAL, LIST, STRUCT, TUPLE, MAP,
* ARRAY, UNION, ENUM, VARIANT, GEOMETRY), for the bind-time-only ids (SQLNULL, UNKNOWN), for TYPE — construct that via
* factory_create_type_from_text — and for INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to resolve the type in.
* @param type_id The type id to instantiate.
* @param param_names Optional. An array of param_count parameter names; a {NULL, 0} entry is positional. Pass NULL for
* all-positional parameters.
* @param param_values An array of param_count parameter values. Borrowed (copied in). Pass NULL when param_count is 0.
* @param param_count The number of parameters. 0 instantiates a parameterless primitive.
* @param out_type Receives the new logical type handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_factory_create_type_from_id(
duckdb_v2_factory_handle factory, DUCKDB_V2_LOGICAL_TYPE_ID type_id, const duckdb_v2_identifier_t *param_names,
const duckdb_v2_value_handle *param_values, idx_t param_count, duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a logical type from a type name plus value parameters.
*
* The generic constructor: resolves the name in the factory's catalog and binds it with the given parameters, exactly
* as SQL binds a type expression. Built-in parameterized kinds and registered extension types construct through this
* same call.
*
* An unqualified name is resolved along the search path first and then in the system catalog, which is where the
* built-in kinds live. A qualified name is resolved exactly as written, with no system-catalog fallback, so it names
* the type in that catalog or schema or fails.
*
* Parameters are (name, value) pairs in two parallel arrays. param_names may be NULL to make every parameter
* positional, and a {NULL, 0} entry makes that one parameter positional. Child types cross as TYPE values, built with
* value_create_type. The built-in shapes are: decimal(width, scale); list(T); array(T, size); map(K, V); struct(fields,
* as named or all-positional TYPE values); union(members, as named TYPE values); enum(entries, as VARCHAR values); and
* varchar with a named "collation" VARCHAR parameter.
*
* A name that resolves to a type with no bind function takes no parameters, and passing any fails. Bind errors —
* unknown name, wrong parameter count or types — surface from the call.
*
* Resolves in the scope of the factory: a connection's or callback's factory reaches the catalog, an instance's factory
* knows only the built-in types. A connection's factory looks up catalog types in the connection's transaction, or in
* one of its own when none is open. Through an instance's factory, only an unqualified built-in name resolves.
*
* The returned logical type is caller-owned and must be destroyed via logical_type_destroy. A type resolved from the
* catalog shares database-owned storage, such as an ENUM dictionary, so destroy it before closing the database. This is
* the inverse of logical_type_get_param_count / logical_type_get_param.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to resolve the type in.
* @param name The type name to resolve. Parts are matched case-insensitively; qualify it to name a type in a particular
* catalog or schema.
* @param param_names Optional. An array of param_count parameter names; a {NULL, 0} entry is positional. Pass NULL for
* all-positional parameters.
* @param param_values An array of param_count parameter values. Borrowed (copied in). Pass NULL when param_count is 0.
* @param param_count The number of parameters.
* @param out_type Receives the new logical type handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_factory_create_type_from_name(
duckdb_v2_factory_handle factory, duckdb_v2_qname_handle name, const duckdb_v2_identifier_t *param_names,
const duckdb_v2_value_handle *param_values, idx_t param_count, duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a logical type by parsing SQL text.
*
* Parses a SQL type expression and returns the bound logical type. It accepts primitives ("INTEGER"), parameterized
* kinds ("DECIMAL(18,3)", "INTEGER[]", "STRUCT(a INTEGER, b VARCHAR)", "MAP(VARCHAR, INTEGER)", "INTEGER[3]", "UNION(i
* INTEGER, s VARCHAR)", "ENUM('a', 'b')"), and catalog-registered type names, both user-defined and from extensions. A
* catalog type name binds to its structural type, and the name is not preserved as an alias. Names are
* case-insensitive. Parse and bind errors surface from the call.
*
* Resolves in the scope of the factory: a connection's or callback's factory reaches the catalog, an instance's factory
* knows only the built-in types. A connection's factory looks up catalog types in the connection's transaction, or in
* one of its own when none is open. Text naming only built-in types never touches the catalog.
*
* The returned logical type is caller-owned and must be destroyed via logical_type_destroy. A type resolved from the
* catalog shares database-owned storage, such as an ENUM dictionary, so destroy it before closing the database. This is
* the inverse of logical_type_to_text for every constructible kind.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to resolve the type in.
* @param text View of the SQL type expression to parse.
* @param out_type Receives the new logical type handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_factory_create_type_from_text(duckdb_v2_factory_handle factory,
const duckdb_v2_str *text,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a copy of a logical type.
*
* On success, writes the new caller-owned handle into *out_type; destroy it via logical_type_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param type The logical type to copy.
* @param out_type Receives the new logical type handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_copy(duckdb_v2_logical_type_handle type,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a logical type handle.
*
* Null-safe: passing nullptr or a slot already set to nullptr is a no-op. On success the slot is set to nullptr.
*
* history:
* - unstable: v2.0.0
*
* @param type The logical type to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_destroy(duckdb_v2_logical_type_handle *type);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Compares two logical types for deep equality.
*
* Two types are equal when they agree in kind and in every parameter, recursively. DECIMAL(10, 2) equals DECIMAL(10,
* 2), but not DECIMAL(10, 3) and not FLOAT; two STRUCTs are equal when they have the same field names in the same order
* and equal field types.
*
* history:
* - unstable: v2.0.0
*
* @param left The first logical type.
* @param right The second logical type.
* @param result Receives the result of the comparison.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_is_equal(duckdb_v2_logical_type_handle left,
duckdb_v2_logical_type_handle right, bool *result,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the logical type id.
*
* history:
* - unstable: v2.0.0
*
* @param type The logical type.
* @param out_id Receives the type id.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_get_id(duckdb_v2_logical_type_handle type,
DUCKDB_V2_LOGICAL_TYPE_ID *out_id,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the logical type's name.
*
* The alias when one is set — an extension or user-defined name such as "POINT_2D" — otherwise the canonical name of
* the type id, such as "INTEGER", "DECIMAL", or "TIMESTAMP WITH TIME ZONE". Never the empty view. This is exactly the
* name vocabulary create_type_from_name accepts. The view is valid until the logical type is destroyed; a canonical
* name points at static storage.
*
* history:
* - unstable: v2.0.0
*
* @param type The logical type.
* @param out_name Receives a borrowed view of the name (alias when set, else the id's canonical name).
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_get_name(duckdb_v2_logical_type_handle type,
duckdb_v2_identifier_t *out_name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Renders a logical type as SQL text.
*
* An aliased type renders as its alias, and create_type_from_text resolves that spelling only when the name is
* registered in the factory's catalog. The text round-trips through create_type_from_text for every constructible kind,
* with one exception: ANY renders as "ANY", but create_type_from_text cannot parse it back, since ANY is a signature
* wildcard rather than a parseable SQL type.
*
* Writes into a caller-supplied buffer, so nothing is allocated on the caller's behalf and nothing has to be freed.
* Pass out_text = NULL to size the buffer without rendering into it: out_length then receives the length, and
* out_capacity is ignored. With out_text != NULL, out_capacity must be at least out_length + 1, or the call returns
* ERROR_INPUT_OBJECT_SIZE with out_length set to the required length and out_text left untouched.
*
* out_length never counts the terminator, but a successful write always appends one, so the buffer is usable as a C
* string.
*
* history:
* - unstable: v2.0.0
*
* @param type The logical type.
* @param out_text Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required
* length in out_length.
* @param out_capacity Bytes available in out_text, terminator included. Ignored when out_text is NULL.
* @param out_length Receives the text length excluding the null terminator — written on success and on
* ERROR_INPUT_OBJECT_SIZE.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_to_text(duckdb_v2_logical_type_handle type, char *out_text,
idx_t out_capacity, idx_t *out_length,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of value parameters of a logical type.
*
* The inspection dual of create_type_from_name: these are the parameters that reconstruct the type through it. Per
* kind: DECIMAL 2 (width, scale); LIST 1 (element type); ARRAY 2 (element type, size); MAP 2 (key type, value type);
* STRUCT and TUPLE one per field; UNION one per member; ENUM one per dictionary entry; VARCHAR 1 when a collation is
* set, else 0; GEOMETRY 1 when a coordinate system is set, else 0; everything else 0. A bound type reports only what it
* actually carries, so a bind-time modifier that is not retained — an ignored VARCHAR length, say — does not reappear.
*
* history:
* - unstable: v2.0.0
*
* @param type The logical type.
* @param out_count Receives the number of parameters.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_get_param_count(duckdb_v2_logical_type_handle type,
idx_t *out_count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns one value parameter of a logical type.
*
* out_name receives a borrowed view of the parameter name — a STRUCT field name, a UNION member name, "collation" — or
* the empty view {NULL, 0} for a positional parameter. A non-empty view is valid until the logical type is destroyed.
* out_value receives an owned value, destroyed via value_destroy: child types come back as TYPE values (unwrap them
* with value_get_type), DECIMAL width and scale as UTINYINT, ARRAY size as BIGINT, and ENUM dictionary entries and
* collations as VARCHAR. An out-of-range index returns ERROR_INPUT_INVALID. Each call allocates one owned value.
*
* history:
* - unstable: v2.0.0
*
* @param type The logical type.
* @param index The parameter index, in [0, param_count).
* @param out_name Receives a borrowed view of the parameter name, or the empty view {NULL, 0} for a positional
* parameter.
* @param out_value Receives the owned parameter value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_logical_type_get_param(duckdb_v2_logical_type_handle type, idx_t index,
duckdb_v2_identifier_t *out_name,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a logical type that is an alias of another logical type.
*
* The alias keeps the base type's internal representation, so executing against it needs no special handling, while
* remaining logically distinct from the base type. Intended for custom type bind callbacks, where both the base type
* and the name come from the bind info.
*
* The alias is not registered anywhere, so this works through any factory. An empty alias name returns
* ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to resolve the type in.
* @param base_type The logical type to alias. Typically the base type supplied in the custom type bind info.
* @param alias_name The name for the resulting type. Typically the name of the custom type being constructed, also
* available from the bind info.
* @param out_type Receives the new type: the base type's internal representation under the given alias name.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_factory_create_type_with_alias(duckdb_v2_factory_handle factory,
duckdb_v2_logical_type_handle base_type,
const duckdb_v2_identifier_t *alias_name,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates the common type of a set of logical types.
*
* The common type is the type every input implicitly casts to, resolved by the same rule a SQL list literal and
* value_create_list follow: INTEGER and BIGINT resolve to BIGINT, and DECIMAL(4,1) and DECIMAL(5,4) to DECIMAL(7,4).
* The types are combined pairwise from left to right, and the result is not guaranteed to be independent of their
* order.
*
* A connection's or a callback's factory also applies the casts that extensions registered, while an instance's factory
* knows only the built-in ones, so the two can resolve the same set differently. A single type resolves to a copy of
* itself.
*
* Returns ERROR_INPUT_INVALID for an empty set, for a NULL entry and for ANY, and ERROR_QUERY_NOT_IMPLEMENTED when the
* types have no common type.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to resolve the type in.
* @param types An array of type_count logical types. Borrowed.
* @param type_count The number of types. Must be at least 1.
* @param out_type Receives the new logical type handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_factory_create_common_type(duckdb_v2_factory_handle factory,
const duckdb_v2_logical_type_handle *types,
idx_t type_count,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for logical_type --- */
/* ============================================================================
* MODULE: macro
* ============================================================================ */
/* --- Enums for macro --- */
//! The kind of a macro function, deciding how its body is read. Pass one to `duckdb_v2_macro_function_create()`.
typedef enum DUCKDB_V2_MACRO_FUNCTION_TYPE {
//! A scalar macro. The body is a single expression, and the macro is called like a scalar function.
DUCKDB_V2_MACRO_FUNCTION_TYPE_SCALAR = 0,
//! A table macro. The body is a single SELECT query, and the macro is called like a table function.
DUCKDB_V2_MACRO_FUNCTION_TYPE_TABLE = 1,
DUCKDB_V2_MACRO_FUNCTION_TYPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_MACRO_FUNCTION_TYPE;
/* --- Struct forward declarations for macro --- */
/* --- Types for macro --- */
/*!
* An owned opaque handle to a macro function being built. Created with `duckdb_v2_macro_function_create()`, configured
* with `duckdb_v2_macro_function_set_name()`, `duckdb_v2_macro_function_set_body()` and the signature obtained via
* `duckdb_v2_macro_function_get_signature()`, made available with `duckdb_v2_extension_register_macro_function()`, and
* destroyed with `duckdb_v2_macro_function_destroy()`.
*/
typedef struct _duckdb_v2_macro_function {
void *internal_ptr;
} * duckdb_v2_macro_function_handle;
/* --- Constants for macro --- */
/* --- Function pointer typedefs for macro --- */
/* --- Functions for macro --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new macro function through a factory.
*
* The macro function starts out empty: configure it with the setter functions and the signature obtained via
* `duckdb_v2_macro_function_get_signature()`, then make it available with
* `duckdb_v2_extension_register_macro_function()`. The caller owns the returned handle and must destroy it with
* `duckdb_v2_macro_function_destroy()`, also after registration.
*
* The macro function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the macro function through.
* @param type Whether the macro is a scalar or a table macro.
* @param function On success, receives the newly created macro function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_macro_function_create(duckdb_v2_factory_handle factory,
DUCKDB_V2_MACRO_FUNCTION_TYPE type,
duckdb_v2_macro_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the macro function, as SQL calls it.
*
* The name is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The macro function to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_macro_function_set_name(duckdb_v2_macro_function_handle function,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the body of the macro function, as SQL text.
*
* For a scalar macro the body is a single expression, for a table macro a single SELECT query. It refers to the
* parameters by name. The body is parsed at registration, which fails on a syntax error; names in it are resolved only
* when the macro is called, as with SQL `CREATE MACRO`. The body is borrowed and copied. Calling this again replaces
* the previous body. A body must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The macro function to set the body of.
* @param body The SQL text of the body. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_macro_function_set_body(duckdb_v2_macro_function_handle function,
const duckdb_v2_str *body,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the macro function's signature so its parameters can be declared.
*
* Add parameters with `duckdb_v2_function_signature_add_parameter()`. A macro's parameters can always be passed by
* position or by name, so only `FUNCTION_PARAMETER_KIND_STANDARD` parameters are accepted; a macro has no variadic
* parameters. A parameter of type ANY is untyped, and a parameter with a default value can be omitted by a caller. A
* macro's result is decided by its body, so the signature cannot set a return type. Registration fails on a signature
* that does not follow these rules. The signature is modified in place.
*
* history:
* - unstable: v2.0.0
*
* @param function The macro function to get the signature of.
* @param sig The returned signature. Borrowed and valid for the lifetime of the macro function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_macro_function_get_signature(duckdb_v2_macro_function_handle function,
duckdb_v2_function_signature_handle *sig,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the documentation of the macro function so it can be filled in.
*
* Set a description with `duckdb_v2_function_docs_set_description()`, and add examples and categories with
* `duckdb_v2_function_docs_add_example()` and `duckdb_v2_function_docs_add_category()`. The documentation is modified
* in place and registered with the macro function. Optional.
*
* history:
* - unstable: v2.0.0
*
* @param function The macro function to get the documentation of.
* @param docs The returned documentation. Borrowed and valid for the lifetime of the macro function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_macro_function_get_docs(duckdb_v2_macro_function_handle function,
duckdb_v2_function_docs_handle *docs,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the macro function, making it available for use in SQL queries.
*
* The macro function is registered on the loading extension's database and attributed to the extension. Use this from
* the extension's load callback. Registration requires a name and a body that parses, and a signature that follows the
* rules of `duckdb_v2_macro_function_get_signature()`. It fails when a function of the same name already exists: a
* macro function has a single overload. The macro function must have been created through a factory of the same
* database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_macro_function_destroy()`, which does not affect the registered macro function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The macro function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_macro_function(duckdb_v2_extension_handle extension,
duckdb_v2_macro_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the macro function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered macro function.
*
* history:
* - unstable: v2.0.0
*
* @param function The macro function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_macro_function_destroy(duckdb_v2_macro_function_handle *function);
#endif
/* --- Struct definitions for macro --- */
/* ============================================================================
* MODULE: pragma
* ============================================================================ */
/* --- Enums for pragma --- */
/* --- Struct forward declarations for pragma --- */
/* --- Types for pragma --- */
/*!
* An owned opaque handle to a custom pragma function being built. Created with `duckdb_v2_pragma_function_create()`,
* configured with the setter functions (e.g. `duckdb_v2_pragma_function_set_name()`,
* `duckdb_v2_pragma_function_set_query_callback()`, etc.) and the signature obtained via
* `duckdb_v2_pragma_function_get_signature()`, made available with `duckdb_v2_connection_register_pragma_function()` or
* `duckdb_v2_extension_register_pragma_function()`, and destroyed with `duckdb_v2_pragma_function_destroy()`.
*/
typedef struct _duckdb_v2_pragma_function {
void *internal_ptr;
} * duckdb_v2_pragma_function_handle;
/*!
* A borrowed opaque handle to the result of a pragma function's "query" callback. The query callback receives this
* handle next to a `duckdb_v2_function_bind_info_handle`, which gives access to the arguments and the user data, and
* uses it to set the query to run in place of the `PRAGMA` statement.
*/
typedef struct _duckdb_v2_pragma_function_query_info {
void *internal_ptr;
} * duckdb_v2_pragma_function_query_info_handle;
/* --- Constants for pragma --- */
/* --- Function pointer typedefs for pragma --- */
typedef void (*duckdb_v2_pragma_function_query_callback_fn)(duckdb_v2_function_bind_info_handle info,
duckdb_v2_pragma_function_query_info_handle result,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_pragma_function_exec_callback_fn)(duckdb_v2_function_bind_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
/* --- Functions for pragma --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new pragma function through a factory.
*
* The function starts out empty: configure it with the setter functions (e.g. `duckdb_v2_pragma_function_set_name()`,
* `duckdb_v2_pragma_function_set_query_callback()`, etc.) and the signature obtained via
* `duckdb_v2_pragma_function_get_signature()`, then make it available with
* `duckdb_v2_connection_register_pragma_function()` or `duckdb_v2_extension_register_pragma_function()`. The caller
* owns the returned handle and must destroy it with `duckdb_v2_pragma_function_destroy()`, also after registration.
*
* The pragma function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the pragma function through.
* @param function On success, receives the newly created pragma function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_create(duckdb_v2_factory_handle factory,
duckdb_v2_pragma_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the pragma function, as the `PRAGMA` statement calls it.
*
* The name is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_set_name(duckdb_v2_pragma_function_handle function,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the documentation of the function so it can be filled in.
*
* Set a description with `duckdb_v2_function_docs_set_description()`, and add examples and categories with
* `duckdb_v2_function_docs_add_example()` and `duckdb_v2_function_docs_add_category()`. The documentation is modified
* in place and registered with the function. Optional.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the documentation of.
* @param docs The returned documentation. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_get_docs(duckdb_v2_pragma_function_handle function,
duckdb_v2_function_docs_handle *docs,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the function's signature so it can be configured.
*
* Add parameters with `duckdb_v2_function_signature_add_parameter()`. A pragma produces no value, so its signature
* cannot set a return type. A signature without parameters makes a pragma called as `PRAGMA name`. The signature is
* modified in place.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the signature of.
* @param sig The returned signature. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_get_signature(duckdb_v2_pragma_function_handle function,
duckdb_v2_function_signature_handle *sig,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the pragma function.
*
* Associates an opaque pointer with the function, retrievable from the callbacks via
* `duckdb_v2_function_bind_get_user_data()`. The opaque handle bundles the pointer with an optional destructor, invoked
* when the data is no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_set_user_data(duckdb_v2_pragma_function_handle function,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the query callback of the pragma function, making it a query pragma.
*
* The query callback is invoked before the `PRAGMA` statement is bound, and must set a SQL string through
* `duckdb_v2_pragma_function_query_set_query()`. The string is parsed and its statements run in place of the `PRAGMA`
* statement. A pragma function has either a query callback or an exec callback; registration fails when both or neither
* are set.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the query callback of.
* @param callback The query callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_set_query_callback(
duckdb_v2_pragma_function_handle function, duckdb_v2_pragma_function_query_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the exec callback of the pragma function, making it an exec pragma.
*
* The exec callback is invoked when the `PRAGMA` statement executes, and runs for its side effects: the statement
* produces no rows. A pragma function has either a query callback or an exec callback; registration fails when both or
* neither are set.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the exec callback of.
* @param callback The exec callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_set_exec_callback(
duckdb_v2_pragma_function_handle function, duckdb_v2_pragma_function_exec_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the SQL to run in place of the `PRAGMA` statement.
*
* The query may hold several statements, separated by semicolons. It is borrowed and copied. Calling this again
* replaces the previous query. The query callback must set a query.
*
* history:
* - unstable: v2.0.0
*
* @param info The query info handle.
* @param query The SQL to run. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_query_set_query(duckdb_v2_pragma_function_query_info_handle info,
const duckdb_v2_str *query,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the pragma function, making it available to the `PRAGMA` statement.
*
* The function is registered on the connection's database, visible to every connection, in the connection's
* transaction: inside an explicit transaction, it is invisible to other connections until the transaction commits, and
* a rollback undoes it. Registration requires a name and exactly one of a query callback or an exec callback, and fails
* when a pragma of the same name already exists. The pragma function must have been created through a factory of the
* same database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_pragma_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param function The pragma function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_pragma_function(duckdb_v2_connection_handle conn,
duckdb_v2_pragma_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the pragma function, making it available to the `PRAGMA` statement.
*
* The function is registered on the loading extension's database and attributed to the extension. Use this from the
* extension's load callback. Registration requires a name and exactly one of a query callback or an exec callback, and
* fails when a pragma of the same name already exists. The pragma function must have been created through a factory of
* the same database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_pragma_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The pragma function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_pragma_function(duckdb_v2_extension_handle extension,
duckdb_v2_pragma_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the pragma function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_pragma_function_destroy(duckdb_v2_pragma_function_handle *function);
#endif
/* --- Struct definitions for pragma --- */
/* ============================================================================
* MODULE: replacement scan
* ============================================================================ */
/* --- Enums for replacement scan --- */
/* --- Struct forward declarations for replacement scan --- */
/* --- Types for replacement scan --- */
/*!
* An owned opaque handle to a replacement scan being built. Created with `duckdb_v2_replacement_scan_create()`,
* configured with `duckdb_v2_replacement_scan_set_callback()` and `duckdb_v2_replacement_scan_set_user_data()`, made
* available with `duckdb_v2_connection_register_replacement_scan()`, `duckdb_v2_instance_register_replacement_scan()`
* or `duckdb_v2_extension_register_replacement_scan()`, and destroyed with `duckdb_v2_replacement_scan_destroy()`.
*/
typedef struct _duckdb_v2_replacement_scan {
void *internal_ptr;
} * duckdb_v2_replacement_scan_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a replacement scan when the binder consults it. The callback
* receives this handle and can use it to inspect the unresolved name and to claim it by naming what to read instead.
* Valid only for the duration of the callback; the name it hands out is owned separately and outlives it.
*/
typedef struct _duckdb_v2_replacement_scan_info {
void *internal_ptr;
} * duckdb_v2_replacement_scan_info_handle;
/* --- Constants for replacement scan --- */
/* --- Function pointer typedefs for replacement scan --- */
typedef void (*duckdb_v2_replacement_scan_callback_fn)(duckdb_v2_replacement_scan_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
/* --- Functions for replacement scan --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new replacement scan through a factory.
*
* The scan starts out empty: configure it with `duckdb_v2_replacement_scan_set_callback()` and optionally
* `duckdb_v2_replacement_scan_set_user_data()`, then make it available with
* `duckdb_v2_connection_register_replacement_scan()`, `duckdb_v2_instance_register_replacement_scan()` or
* `duckdb_v2_extension_register_replacement_scan()`. The caller owns the returned handle and must destroy it with
* `duckdb_v2_replacement_scan_destroy()`, also after registration.
*
* The scan can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the scan through.
* @param scan On success, receives the newly created replacement scan. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_create(duckdb_v2_factory_handle factory,
duckdb_v2_replacement_scan_handle *scan,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the callback of the replacement scan.
*
* The callback is invoked during query planning for each table reference the catalog could not resolve. It can inspect
* the unresolved name via `duckdb_v2_replacement_scan_get_name()`, and claim the reference via
* `duckdb_v2_replacement_scan_set_function_name()`, `duckdb_v2_replacement_scan_set_collection()` or
* `duckdb_v2_replacement_scan_set_subquery()`; returning without claiming declines it. The context passed to the
* callback may be used to read settings, but not to run queries. A callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param scan The scan to set the callback of.
* @param callback The callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_set_callback(duckdb_v2_replacement_scan_handle scan,
duckdb_v2_replacement_scan_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the replacement scan.
*
* Associates an opaque pointer with the scan, retrievable from the callback via
* `duckdb_v2_replacement_scan_get_user_data()`. The opaque handle bundles the pointer with an optional destructor,
* invoked when the data is no longer needed, at the latest when the scan's scope ends. The callback may be invoked from
* several connections at once, so the data must be safe to read concurrently.
*
* history:
* - unstable: v2.0.0
*
* @param scan The scan to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_set_user_data(duckdb_v2_replacement_scan_handle scan,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_replacement_scan_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_get_user_data(duckdb_v2_replacement_scan_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the name the catalog could not resolve.
*
* The name as written in the query, as a path: an unqualified reference has a single part, and a qualified one carries
* its catalog and schema before it -- see `duckdb_v2_qname_get_part()`. For a file-backed reference the single part is
* the path with the quotes stripped. The returned name is owned by the caller and must be destroyed via
* `duckdb_v2_qname_destroy()`; being owned, it may outlive the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param name Receives the unresolved name. Owned by the caller; destroy via `duckdb_v2_qname_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_get_name(duckdb_v2_replacement_scan_info_handle info,
duckdb_v2_qname_handle *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Claims the reference by naming a table function to read instead.
*
* Arguments to the function are added with `duckdb_v2_replacement_scan_add_argument()` and
* `duckdb_v2_replacement_scan_add_named_argument()`. The name is borrowed and copied, and its parts are matched
* case-insensitively. A qualified name targets a function in a particular schema or catalog, exactly as writing it out
* in SQL would. The name is not resolved here: an unknown function fails later, when the replacement is bound. Calling
* this again replaces the previous name and keeps the arguments added so far.
*
* The three claim forms, `duckdb_v2_replacement_scan_set_function_name()`,
* `duckdb_v2_replacement_scan_set_collection()` and `duckdb_v2_replacement_scan_set_subquery()`, are mutually
* exclusive: claiming the reference through a second, different form results in an error.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param name The table function to read instead. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_set_function_name(duckdb_v2_replacement_scan_info_handle info,
duckdb_v2_qname_handle name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Appends a positional argument to the claimed table function.
*
* Positional arguments are passed in the order they are added, before any named ones. The value is borrowed and copied,
* so the caller may destroy it after the call. Requires `duckdb_v2_replacement_scan_set_function_name()` to have been
* called first; otherwise the call results in an error.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param value The argument value. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_add_argument(duckdb_v2_replacement_scan_info_handle info,
duckdb_v2_value_handle value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Appends a named argument to the claimed table function.
*
* Equivalent to writing `name := value` at the call site. The name and the value are borrowed and copied, so the caller
* may destroy the value after the call. Requires `duckdb_v2_replacement_scan_set_function_name()` to have been called
* first; otherwise the call results in an error.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param name The name of the parameter to bind the value to. Borrowed and copied.
* @param value The argument value. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_add_named_argument(duckdb_v2_replacement_scan_info_handle info,
const duckdb_v2_identifier_t *name,
duckdb_v2_value_handle value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Claims the reference by naming a column data collection to read instead.
*
* The collection is borrowed, not copied: the caller keeps ownership and must keep it alive, and must not clear, reset
* or destroy it, for as long as any result reading it is live, since the result scans its buffers directly.
*
* A prepared statement extends that lifetime well beyond its own results. Preparing a statement over a claimed name
* captures the borrow in the plan, and since a collection claim reads no database there is nothing to invalidate that
* plan: `duckdb_v2_prepared_statement_reuses_plan()` reports true, and every later execution reuses the captured borrow
* without consulting the callback again. So dropping the name from whatever the callback resolves against does not
* release the collection, and releasing it while such a statement is live leaves the next execution reading freed
* memory. Destroy every prepared statement over a claimed name before clearing, resetting or destroying the collection
* behind it.
*
* By default the collection's columns are named col1..colN. Pass `column_names` to name them instead. When supplied,
* `column_count` must equal the collection's column count and no name may be empty; pass NULL and 0 for the default
* names.
*
* The three claim forms, `duckdb_v2_replacement_scan_set_function_name()`,
* `duckdb_v2_replacement_scan_set_collection()` and `duckdb_v2_replacement_scan_set_subquery()`, are mutually
* exclusive: claiming the reference through a second, different form results in an error.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param collection The collection to read instead. Borrowed; the caller keeps ownership and must keep it alive.
* @param column_names Optional. An array of `column_count` column names, in order. Pass NULL for the default names
* col1..colN.
* @param column_count The number of names in `column_names`. Must equal the collection's column count, or 0 for the
* default names.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_set_collection(
duckdb_v2_replacement_scan_info_handle info, duckdb_v2_column_data_collection_handle collection,
const duckdb_v2_identifier_t *column_names, idx_t column_count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Claims the reference by naming a query to read instead.
*
* The text is parsed at the call and must contain exactly one SELECT statement: a syntax error, several statements or a
* statement of another kind results in an error. The text is borrowed for the call only. Prefer
* `duckdb_v2_replacement_scan_set_function_name()` when a single table function call suffices, as it avoids the parse
* and keeps the plan flatter.
*
* The three claim forms, `duckdb_v2_replacement_scan_set_function_name()`,
* `duckdb_v2_replacement_scan_set_collection()` and `duckdb_v2_replacement_scan_set_subquery()`, are mutually
* exclusive: claiming the reference through a second, different form results in an error.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param sql The SELECT statement to read instead. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_set_subquery(duckdb_v2_replacement_scan_info_handle info,
const duckdb_v2_str *sql,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the alias the claimed replacement is bound under.
*
* Optional, and independent of the claim form. An alias written in the query takes precedence over this one; without
* either, the table name of the reference is used, which for a file-backed reference is the path. The alias is borrowed
* and copied.
*
* history:
* - unstable: v2.0.0
*
* @param info The info handle.
* @param alias The alias to bind the replacement under. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_set_alias(duckdb_v2_replacement_scan_info_handle info,
const duckdb_v2_identifier_t *alias,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the replacement scan, making it consulted for names the catalog cannot resolve.
*
* The scan is visible only to queries on this connection and is released when the connection is destroyed. It is
* consulted before every instance-wide scan, so it can claim a name that a built-in scan would otherwise take.
* Registration requires a callback. Scans are consulted in registration order within their scope, connection-scoped
* ones before instance-wide ones, and the first to claim a name wins. A scan cannot be registered twice, and a
* registered scan cannot be unregistered: it lives until its scope ends. The scan must have been created through a
* factory of the same database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_replacement_scan_destroy()`, which does not affect the registered scan.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param scan The replacement scan to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_replacement_scan(duckdb_v2_connection_handle conn,
duckdb_v2_replacement_scan_handle scan,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the replacement scan, making it consulted for names the catalog cannot resolve.
*
* The scan is visible to every connection to the instance and lives until the instance is destroyed. Registering it
* while queries are binding on other connections is not thread-safe: register before issuing queries. Registration
* requires a callback. Scans are consulted in registration order within their scope, connection-scoped ones before
* instance-wide ones, and the first to claim a name wins. A scan cannot be registered twice, and a registered scan
* cannot be unregistered: it lives until its scope ends. The scan must have been created through a factory of the same
* database. The caller still owns the handle after registration and must destroy it with
* `duckdb_v2_replacement_scan_destroy()`, which does not affect the registered scan.
*
* history:
* - unstable: v2.0.0
*
* @param instance The instance to register on.
* @param scan The replacement scan to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_instance_register_replacement_scan(duckdb_v2_instance_handle instance,
duckdb_v2_replacement_scan_handle scan,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the replacement scan, making it consulted for names the catalog cannot resolve.
*
* The scan is visible to every connection to the loading extension's instance and lives until the instance is
* destroyed. Use this from the extension's load callback. Registration requires a callback. Scans are consulted in
* registration order within their scope, connection-scoped ones before instance-wide ones, and the first to claim a
* name wins. A scan cannot be registered twice, and a registered scan cannot be unregistered: it lives until its scope
* ends. The scan must have been created through a factory of the same database. The caller still owns the handle after
* registration and must destroy it with `duckdb_v2_replacement_scan_destroy()`, which does not affect the registered
* scan.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param scan The replacement scan to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_replacement_scan(duckdb_v2_extension_handle extension,
duckdb_v2_replacement_scan_handle scan,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the replacement scan, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered scan.
*
* history:
* - unstable: v2.0.0
*
* @param scan The scan to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_replacement_scan_destroy(duckdb_v2_replacement_scan_handle *scan);
#endif
/* --- Struct definitions for replacement scan --- */
/* ============================================================================
* MODULE: scalar
* ============================================================================ */
/* --- Enums for scalar --- */
/* --- Struct forward declarations for scalar --- */
/* --- Types for scalar --- */
/*!
* An owned opaque handle to a custom scalar function being built. Created with `duckdb_v2_scalar_function_create()`,
* configured with the setter functions (e.g. `duckdb_v2_scalar_function_set_name()`,
* `duckdb_v2_scalar_function_set_exec_callback()`, etc.) and the signature obtained via
* `duckdb_v2_scalar_function_get_signature()`, made available with `duckdb_v2_connection_register_scalar_function()` or
* `duckdb_v2_extension_register_scalar_function()`, and destroyed with `duckdb_v2_scalar_function_destroy()`.
*/
typedef struct _duckdb_v2_scalar_function {
void *internal_ptr;
} * duckdb_v2_scalar_function_handle;
/*!
* A borrowed opaque handle to the result of a scalar function's "resolve types" phase. The "resolve types" callback
* receives this handle next to a `duckdb_v2_function_bind_info_handle`, which gives access to the arguments and the
* user data, and can use it to set the return type of the call site being bound.
*/
typedef struct _duckdb_v2_scalar_function_resolve_types_info {
void *internal_ptr;
} * duckdb_v2_scalar_function_resolve_types_info_handle;
/*!
* A borrowed opaque handle to the result of a scalar function's "bind" phase. The "bind" callback receives this handle
* next to a `duckdb_v2_function_bind_info_handle`, which gives access to the arguments and the user data, and can use
* it to set the bind data of the call site being bound.
*/
typedef struct _duckdb_v2_scalar_function_bind_info {
void *internal_ptr;
} * duckdb_v2_scalar_function_bind_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a scalar function during the local state initialization "init"
* phase. The "init" callback receives this handle and can use it to e.g. set up local state reusable across invocations
* of the "exec" execution callback.
*/
typedef struct _duckdb_v2_scalar_function_init_info {
void *internal_ptr;
} * duckdb_v2_scalar_function_init_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a scalar function during the execution "exec" phase. The "exec"
* callback receives this handle and can use it to e.g. access the input argument vectors, retrieve the number of rows
* to process, and write results to the output vector.
*/
typedef struct _duckdb_v2_scalar_function_exec_info {
void *internal_ptr;
} * duckdb_v2_scalar_function_exec_info_handle;
/* --- Constants for scalar --- */
/* --- Function pointer typedefs for scalar --- */
typedef void (*duckdb_v2_scalar_function_resolve_types_callback_fn)(
duckdb_v2_function_bind_info_handle info, duckdb_v2_scalar_function_resolve_types_info_handle result,
duckdb_v2_context_handle context, duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_scalar_function_bind_callback_fn)(duckdb_v2_function_bind_info_handle info,
duckdb_v2_scalar_function_bind_info_handle result,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_scalar_function_init_callback_fn)(duckdb_v2_scalar_function_init_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_scalar_function_exec_callback_fn)(duckdb_v2_scalar_function_exec_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
/* --- Functions for scalar --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new scalar function through a factory.
*
* The function starts out empty: configure it with the setter functions (e.g. `duckdb_v2_scalar_function_set_name()`,
* `duckdb_v2_scalar_function_set_exec_callback()`, etc.) and the signature obtained via
* `duckdb_v2_scalar_function_get_signature()`, then make it available with
* `duckdb_v2_connection_register_scalar_function()` or `duckdb_v2_extension_register_scalar_function()`. The caller
* owns the returned handle and must destroy it with `duckdb_v2_scalar_function_destroy()`, also after registration.
*
* The scalar function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the scalar function through.
* @param function On success, receives the newly created scalar function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_create(duckdb_v2_factory_handle factory,
duckdb_v2_scalar_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the scalar function.
*
* The name is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_set_name(duckdb_v2_scalar_function_handle function,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the documentation of the function so it can be filled in.
*
* Set a description with `duckdb_v2_function_docs_set_description()`, and add examples and categories with
* `duckdb_v2_function_docs_add_example()` and `duckdb_v2_function_docs_add_category()`. The documentation is modified
* in place, describes this overload only, and is registered with the function. Optional.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the documentation of.
* @param docs The returned documentation. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_get_docs(duckdb_v2_scalar_function_handle function,
duckdb_v2_function_docs_handle *docs,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the function's signature so it can be configured.
*
* Add parameters with `duckdb_v2_function_signature_add_parameter()` and set the return type with
* `duckdb_v2_function_signature_set_return_type()`. The signature is modified in place; the function must be given a
* signature with a return type before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the signature of.
* @param sig The returned signature. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_get_signature(duckdb_v2_scalar_function_handle function,
duckdb_v2_function_signature_handle *sig,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the scalar function.
*
* Associates an opaque pointer with the function, retrievable from the callbacks via
* `duckdb_v2_function_bind_get_user_data()`, `duckdb_v2_scalar_function_init_get_user_data()` and
* `duckdb_v2_scalar_function_exec_get_user_data()`. The opaque handle bundles the pointer with an optional destructor,
* invoked when the data is no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_set_user_data(duckdb_v2_scalar_function_handle function,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets a property on the scalar function.
*
* Configures a function property that influences planning and execution, such as stability, NULL handling, fallibility
* or collation handling. The value must be one of the `DUCKDB_V2_FUNCTION_PROPERTY_VALUE` entries belonging to `key`;
* passing a value that does not belong to the key, or a key that is not valid for scalar functions, results in an
* error.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the property of.
* @param key The property to set.
* @param value The value to set for the property. Must belong to `key`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_set_property(duckdb_v2_scalar_function_handle function,
DUCKDB_V2_FUNCTION_PROPERTY_KEY key,
DUCKDB_V2_FUNCTION_PROPERTY_VALUE value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional resolve types callback of the scalar function.
*
* The resolve types callback is invoked during query planning for each call site of the function, before the arguments
* are cast to the parameter types of the signature. Through its `duckdb_v2_function_bind_info_handle` it can inspect
* the argument types as they were passed and constant argument values. Through its
* `duckdb_v2_scalar_function_resolve_types_info_handle` it can set a concrete return type. It cannot set "bind data",
* use the bind callback for that.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the resolve types callback of.
* @param callback The resolve types callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_set_resolve_types_callback(
duckdb_v2_scalar_function_handle function, duckdb_v2_scalar_function_resolve_types_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional bind callback of the scalar function.
*
* The bind callback is invoked during query planning for each call site of the function, after the resolve types
* callback and after the arguments have been cast to the parameter types of the signature. Through its
* `duckdb_v2_function_bind_info_handle` it can inspect the argument types and constant argument values. Through its
* `duckdb_v2_scalar_function_bind_info_handle` it can set "bind data" that is shared with the init and exec callbacks.
* It cannot change the types of the call site, use the resolve types callback for that.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the bind callback of.
* @param callback The bind callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_set_bind_callback(
duckdb_v2_scalar_function_handle function, duckdb_v2_scalar_function_bind_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional init callback of the scalar function.
*
* The init callback is invoked at the start of execution for each thread that will execute the function. It can set
* worker-local "init data", retrievable from the exec callback, to keep mutable state across invocations of the
* function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the init callback of.
* @param callback The init callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_set_init_callback(
duckdb_v2_scalar_function_handle function, duckdb_v2_scalar_function_init_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the exec callback of the scalar function.
*
* The exec callback implements the function's logic: it is invoked during query execution with a batch of input rows
* and must fill the result vector. An exec callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the exec callback of.
* @param callback The exec callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_set_exec_callback(
duckdb_v2_scalar_function_handle function, duckdb_v2_scalar_function_exec_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the concrete return type of the call site being bound.
*
* Overrides the return type declared in the signature. Register the function with an ANY return type and set the
* concrete type here, derived from the argument types, to build a function whose result type depends on its input. The
* type is borrowed and copied.
*
* history:
* - unstable: v2.0.0
*
* @param info The resolve types info handle.
* @param return_type The return type to set. Borrowed for the call only.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_resolve_types_set_return_type(
duckdb_v2_scalar_function_resolve_types_info_handle info, duckdb_v2_logical_type_handle return_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's "bind data" from the bind callback.
*
* The bind data is stored with the bound call site and retrievable from the init and exec callbacks. The opaque handle
* bundles the pointer with an optional destructor, invoked when the bind data is no longer needed, and an optional
* equality callback used when comparing two bound call sites; without one, pointer equality is used. Scalar functions
* set their bind data through this function, `duckdb_v2_function_bind_set_bind_data()` is not available to them.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param data Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_bind_set_bind_data(
duckdb_v2_scalar_function_bind_info_handle info, duckdb_v2_opaque *data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_scalar_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_init_get_user_data(
duckdb_v2_scalar_function_init_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_init_get_bind_data(
duckdb_v2_scalar_function_init_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's worker-local "init data" from the init callback.
*
* The init data is associated with the executing thread for the duration of the query and retrievable from the exec
* callback via `duckdb_v2_scalar_function_exec_get_init_data()`. The opaque handle bundles the pointer with an optional
* destructor, invoked when the init data is no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param info The init info handle.
* @param data Opaque handle bundling the init data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_init_set_init_data(
duckdb_v2_scalar_function_init_info_handle info, duckdb_v2_opaque *data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_scalar_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_exec_get_user_data(
duckdb_v2_scalar_function_exec_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_exec_get_bind_data(
duckdb_v2_scalar_function_exec_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the worker-local init data set by the function's init callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the init data pointer for the executing thread, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_exec_get_init_data(
duckdb_v2_scalar_function_exec_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many rows this execution must produce. The exec callback must write exactly this many rows to the result
* vector. Note that this may be less than a full vector: with all-constant arguments the function is invoked for a
* single row and the result is expanded by the engine.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param count Receives the number of rows.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_exec_get_row_count(
duckdb_v2_scalar_function_exec_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns how many argument vectors this invocation carries, split into the four parts of the argument list.
*
* The parts and their order are those the bind callback saw through `duckdb_v2_function_bind_get_arg_count()`, and the
* vectors are at the same indices. Valid indices for `duckdb_v2_scalar_function_exec_get_arg()` are [0, the sum of the
* four counts). Every out-parameter may be NULL, in which case nothing is written to it.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param positional_fixed Optional. Receives the number of positional-only and standard parameters.
* @param positional_variadic Optional. Receives the number of arguments `*args` received, 0 when the signature has
* none.
* @param named_fixed Optional. Receives the number of named-only parameters.
* @param named_variadic Optional. Receives the number of arguments `**kwargs` received, 0 when the signature has none.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_exec_get_arg_count(
duckdb_v2_scalar_function_exec_info_handle info, idx_t *positional_fixed, idx_t *positional_variadic,
idx_t *named_fixed, idx_t *named_variadic, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the argument vector at the given index.
*
* The index is the one the bind callback used for the argument, e.g. the index
* `duckdb_v2_function_bind_get_arg_index()` found for a name. The vector holds the argument's values for the current
* batch; use `duckdb_v2_scalar_function_exec_get_row_count()` for the number of rows. Fails if the index is out of
* bounds. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param index The index of the argument.
* @param vector Receives the borrowed argument vector.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_exec_get_arg(duckdb_v2_scalar_function_exec_info_handle info,
idx_t index, duckdb_v2_vector_handle *vector,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the result vector the exec callback must write into.
*
* The callback must write one entry per input row; use `duckdb_v2_scalar_function_exec_get_row_count()` for the number
* of rows. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param vector Receives the borrowed result vector to write into.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_exec_get_result(duckdb_v2_scalar_function_exec_info_handle info,
duckdb_v2_vector_handle *vector,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the scalar function, making it available for use in SQL queries.
*
* The function is registered on the connection's database, visible to every connection, in the connection's
* transaction: inside an explicit transaction, it is invisible to other connections until the transaction commits, and
* a rollback undoes it. Registration requires a name, an exec callback, and a signature with a complete return type; an
* ANY return type is accepted only together with a resolve types callback that sets the concrete type per call site.
* The scalar function must have been created through a factory of the same database. The caller still owns the handle
* after registration and must destroy it with `duckdb_v2_scalar_function_destroy()`, which does not affect the
* registered function.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param function The scalar function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_scalar_function(duckdb_v2_connection_handle conn,
duckdb_v2_scalar_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the scalar function, making it available for use in SQL queries.
*
* The function is registered on the loading extension's database and attributed to the extension. Use this from the
* extension's load callback. Registration requires a name, an exec callback, and a signature with a complete return
* type; an ANY return type is accepted only together with a resolve types callback that sets the concrete type per call
* site. The scalar function must have been created through a factory of the same database. The caller still owns the
* handle after registration and must destroy it with `duckdb_v2_scalar_function_destroy()`, which does not affect the
* registered function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The scalar function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_scalar_function(duckdb_v2_extension_handle extension,
duckdb_v2_scalar_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the scalar function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_scalar_function_destroy(duckdb_v2_scalar_function_handle *function);
#endif
/* --- Struct definitions for scalar --- */
/* ============================================================================
* MODULE: sql_statement
* ============================================================================ */
/* --- Enums for sql_statement --- */
//! SQL statement type of a parsed statement or an executed query.
typedef enum DUCKDB_V2_STATEMENT_TYPE {
DUCKDB_V2_STATEMENT_TYPE_INVALID = 0,
DUCKDB_V2_STATEMENT_TYPE_SELECT = 1,
DUCKDB_V2_STATEMENT_TYPE_INSERT = 2,
DUCKDB_V2_STATEMENT_TYPE_UPDATE = 3,
DUCKDB_V2_STATEMENT_TYPE_CREATE = 4,
DUCKDB_V2_STATEMENT_TYPE_DELETE = 5,
DUCKDB_V2_STATEMENT_TYPE_PREPARE = 6,
DUCKDB_V2_STATEMENT_TYPE_EXECUTE = 7,
DUCKDB_V2_STATEMENT_TYPE_ALTER = 8,
DUCKDB_V2_STATEMENT_TYPE_TRANSACTION = 9,
DUCKDB_V2_STATEMENT_TYPE_COPY = 10,
DUCKDB_V2_STATEMENT_TYPE_ANALYZE = 11,
DUCKDB_V2_STATEMENT_TYPE_VARIABLE_SET = 12,
DUCKDB_V2_STATEMENT_TYPE_CREATE_FUNC = 13,
DUCKDB_V2_STATEMENT_TYPE_EXPLAIN = 14,
DUCKDB_V2_STATEMENT_TYPE_DROP = 15,
DUCKDB_V2_STATEMENT_TYPE_EXPORT = 16,
DUCKDB_V2_STATEMENT_TYPE_PRAGMA = 17,
DUCKDB_V2_STATEMENT_TYPE_VACUUM = 18,
DUCKDB_V2_STATEMENT_TYPE_CALL = 19,
DUCKDB_V2_STATEMENT_TYPE_SET = 20,
DUCKDB_V2_STATEMENT_TYPE_LOAD = 21,
DUCKDB_V2_STATEMENT_TYPE_RELATION = 22,
DUCKDB_V2_STATEMENT_TYPE_EXTENSION = 23,
DUCKDB_V2_STATEMENT_TYPE_LOGICAL_PLAN = 24,
DUCKDB_V2_STATEMENT_TYPE_ATTACH = 25,
DUCKDB_V2_STATEMENT_TYPE_DETACH = 26,
DUCKDB_V2_STATEMENT_TYPE_MULTI = 27,
DUCKDB_V2_STATEMENT_TYPE_COPY_DATABASE = 28,
DUCKDB_V2_STATEMENT_TYPE_UPDATE_EXTENSIONS = 29,
DUCKDB_V2_STATEMENT_TYPE_MERGE_INTO = 30,
DUCKDB_V2_STATEMENT_TYPE_CONNECT = 31,
DUCKDB_V2_STATEMENT_TYPE_DISCONNECT = 32,
DUCKDB_V2_STATEMENT_TYPE_EXTERNAL_RESOURCE = 33,
DUCKDB_V2_STATEMENT_TYPE_PASSTHROUGH = 34,
DUCKDB_V2_STATEMENT_TYPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_STATEMENT_TYPE;
/* --- Struct forward declarations for sql_statement --- */
/* --- Types for sql_statement --- */
/*!
* An opaque, owned handle to a single parsed SQL statement, produced by statement_iterator_next. statement_execute runs
* it without consuming it; the caller always destroys it via sql_statement_destroy.
*/
typedef struct _duckdb_v2_sql_statement {
void *internal_ptr;
} * duckdb_v2_sql_statement_handle;
/*!
* An opaque, owned handle to an iterator over the statements of a SQL string, produced by parse_sql. Destroy it via
* statement_iterator_destroy; statements it already yielded are independently owned and unaffected.
*/
typedef struct _duckdb_v2_statement_iterator {
void *internal_ptr;
} * duckdb_v2_statement_iterator_handle;
/* --- Constants for sql_statement --- */
/* --- Function pointer typedefs for sql_statement --- */
/* --- Functions for sql_statement --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Parses a SQL string into an iterator over its statements.
*
* Parses and nothing more: no binding, no catalog access, no transaction. The connection supplies the parser options
* and parser extensions, and is not otherwise touched. Statements are raw parser output; statement-level rewrites
* happen inside statement_execute. The SQL string is copied, so the caller may free it once this call returns. An input
* with no statements — empty, whitespace, or separators only — yields an iterator that is immediately exhausted.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection supplying the parser configuration.
* @param sql Null-terminated SQL string; may contain any number of statements.
* @param out_iterator Receives the new iterator handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_parse_sql(duckdb_v2_connection_handle conn, const char *sql,
duckdb_v2_statement_iterator_handle *out_iterator,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Yields the next statement, or NULL when exhausted.
*
* On success *out_statement receives the next owned statement, or NULL once the iterator is exhausted — repeatedly, so
* calling again is harmless. A parse error within the input surfaces no later than the call that reaches the failing
* statement: an implementation that parses eagerly reports it from parse_sql instead and yields no statements at all,
* while an incremental one yields the statements ahead of the failure first. On failure *out_statement is set to NULL.
*
* history:
* - unstable: v2.0.0
*
* @param iterator The iterator to advance.
* @param out_statement Receives an owned statement, or NULL when the iterator is exhausted.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_statement_iterator_next(duckdb_v2_statement_iterator_handle iterator,
duckdb_v2_sql_statement_handle *out_statement,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Binds a parsed statement without executing, yielding its schema signature.
*
* Preprocesses and binds the statement exactly as execution would, but runs nothing: the result is the statement's
* signature as two schemas, not a query result. The statement is borrowed, not consumed, so it can be bound as often as
* you like and executed later. out_schema receives the output schema (result columns) and is never empty, since a
* non-SELECT reports a single status column: a BIGINT changed-rows count, or a BOOLEAN success. out_parameters, when
* non-NULL, receives the input schema (parameter types, ordered by binding index). Both are owned; destroy them via
* schema_destroy.
*
* Binding is read-only and does not disturb a live result: it begins no query, claims no cursor, reuses an active
* transaction read-only, and runs alongside a paused stream. It is single-consumer like the stepping functions, so bind
* concurrently only on a second connection. Prepare-time errors — binder, catalog, preprocessing — surface here. A
* statement that expands into a group (a dynamic PIVOT, or statement-expanding DDL such as ALTER ADD COLUMN with a
* non-constant DEFAULT) has a schema known only at execution, and is reported with ERROR_INPUT_METADATA_DEFERRED;
* execute it instead.
*
* *out_schema and *out_parameters are set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection supplying the catalog, transaction, and parser configuration.
* @param statement The statement to bind. Borrowed; not consumed.
* @param out_schema Receives the owned output schema (result columns). Destroy via schema_destroy.
* @param out_parameters Optional. When non-NULL, receives the owned input schema (parameter types, ordered by binding
* index). Destroy via schema_destroy.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_statement_bind(duckdb_v2_connection_handle conn,
duckdb_v2_sql_statement_handle statement,
duckdb_v2_schema_handle *out_schema,
duckdb_v2_schema_handle *out_parameters,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Binds a column data collection to the statement under a name.
*
* Makes the collection visible to the statement as a table named `name`, by adding a common table expression to the
* parsed statement. The statement can then be bound, prepared or executed as usual; each execution reads the
* collection's contents at that moment, so a prepared statement can be executed again after the collection was cleared
* and refilled. Supported statement types are SELECT, INSERT, UPDATE, DELETE and MERGE INTO; any other type is rejected
* with `ERROR_INPUT_INVALID`.
*
* A name the statement already defines as a common table expression, in its SQL text or by a prior call, is rejected
* with `ERROR_INPUT_INVALID`. The binding shadows any catalog table named `name`, as a common table expression does.
*
* By default the collection's columns are named col1..colN. Pass `column_names` to name them instead; when supplied,
* `column_count` must equal the collection's column count. Pass NULL and 0 for the default names.
*
* The collection is borrowed: the caller keeps ownership and must keep it alive, and must not clear, reset or destroy
* it, for as long as the statement, any statement copied or prepared from it, or any result executing it is live. An
* empty collection is a valid binding. Several collections can be bound under distinct names.
*
* history:
* - unstable: v2.0.0
*
* @param statement The statement to bind the collection to. Modified in place.
* @param name The non-empty name the statement refers to the collection by. Borrowed and copied.
* @param collection The collection to bind. Borrowed; the caller keeps ownership and must keep it alive.
* @param column_names Optional. An array of `column_count` names for the collection's columns, in order. Pass NULL for
* col1..colN.
* @param column_count The number of names in `column_names`. 0 for the default names; otherwise the collection's column
* count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_statement_add_collection(duckdb_v2_sql_statement_handle statement,
const duckdb_v2_identifier_t *name,
duckdb_v2_column_data_collection_handle collection,
const duckdb_v2_identifier_t *column_names,
idx_t column_count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the statement's type as classified by the parser.
*
* This gives the type before the statement-level rewrites that `duckdb_v2_statement_execute()` applies, if any. So a
* PRAGMA reports PRAGMA even where execution rewrites it into a SELECT or a CALL.
* `duckdb_v2_result_get_statement_type()` on the executed result reports the rewritten type of a statement that
* rewrites into one. A statement the parser expands into a group reports MULTI, here and on its result. Its parts are
* not visible here, and statement_bind reports ERROR_INPUT_METADATA_DEFERRED for it.
*
* history:
* - unstable: v2.0.0
*
* @param statement The statement.
* @param out_type Receives the statement type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_sql_statement_get_type(duckdb_v2_sql_statement_handle statement,
DUCKDB_V2_STATEMENT_TYPE *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the statement's own SQL text.
*
* The slice of the parsed string that belongs to this statement. A trailing terminator and the whitespace after it are
* included, whitespace and comments before the first token are not. The statement holds its own copy, so the view
* outlives the SQL string passed to parse_sql and the iterator, and stays valid until the statement is destroyed. A
* statement produced by a parser extension that overrides parsing carries whatever text the extension recorded.
*
* history:
* - unstable: v2.0.0
*
* @param statement The statement.
* @param out_text Receives a borrowed view of the statement text, valid until the statement is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_sql_statement_get_text(duckdb_v2_sql_statement_handle statement,
duckdb_v2_str *out_text,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of distinct parameters the statement declares.
*
* This counts the parameters the parser found ($1, ?, $name, ...), so it needs no catalog and no binding; only the
* parameter types wait for `duckdb_v2_statement_bind()`. Repeated uses of one parameter count once.
*
* history:
* - unstable: v2.0.0
*
* @param statement The statement.
* @param out_count Receives the number of distinct parameters.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_sql_statement_get_parameter_count(duckdb_v2_sql_statement_handle statement,
idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows the name of one parameter, in binding order.
*
* Parse-time metadata. Positions follow the parameters' binding indices, the order of `duckdb_v2_statement_bind()`'s
* parameter schema, so position i here names field i there. The name is the binding key that
* `duckdb_v2_statement_execute()` accepts: "1", "2", ... for a positional parameter ($1 or ?), the identifier for a
* named one ($name). Positional indices may be gapped ($1 and $3 without $2), in which case the names are "1" and "3"
* at positions 0 and 1. The view is valid until the statement is destroyed. An index outside [0, count) is rejected
* with ERROR_INPUT_OUT_OF_RANGE.
*
* history:
* - unstable: v2.0.0
*
* @param statement The statement.
* @param index Zero-based position in binding order.
* @param out_name Receives a borrowed view of the parameter name, valid until the statement is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_sql_statement_get_parameter_name(duckdb_v2_sql_statement_handle statement,
idx_t index, duckdb_v2_identifier_t *out_name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a statement handle.
*
* Null-safe: passing nullptr or a slot already set to nullptr is a no-op. statement_execute does not consume a
* statement, so every statement is destroyed here once it is no longer needed. On success the slot is set to nullptr.
*
* history:
* - unstable: v2.0.0
*
* @param statement The statement to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_sql_statement_destroy(duckdb_v2_sql_statement_handle *statement);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a statement iterator handle.
*
* Null-safe: passing nullptr or a slot already set to nullptr is a no-op. Statements already yielded are independently
* owned and stay valid. On success the slot is set to nullptr.
*
* history:
* - unstable: v2.0.0
*
* @param iterator The iterator to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_statement_iterator_destroy(duckdb_v2_statement_iterator_handle *iterator);
#endif
/* --- Struct definitions for sql_statement --- */
/* ============================================================================
* MODULE: vector
* ============================================================================ */
/* --- Enums for vector --- */
/*!
* Internal representation of a vector, with FSST / SEQUENCE / SHREDDED collapsed into OTHER: the view getter rejects
* those and requires an explicit vector_flatten first. OTHER is the 0-value, so a zero-initialized out-param reads as
* "unspecified, needs flatten" rather than silently looking like FLAT.
*/
typedef enum DUCKDB_V2_VECTOR_TYPE {
//! Default for zero-init. Covers FSST / SEQUENCE / SHREDDED — call vector_flatten first.
DUCKDB_V2_VECTOR_TYPE_OTHER = 0,
//! Standard per-row storage.
DUCKDB_V2_VECTOR_TYPE_FLAT = 1,
//! A single value applies to every row in the vector.
DUCKDB_V2_VECTOR_TYPE_CONSTANT = 2,
//! Data + selection vector indirection into another vector.
DUCKDB_V2_VECTOR_TYPE_DICTIONARY = 3,
DUCKDB_V2_VECTOR_TYPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_VECTOR_TYPE;
/* --- Struct forward declarations for vector --- */
typedef struct duckdb_v2_vector_view duckdb_v2_vector_view;
typedef struct duckdb_v2_list_entry duckdb_v2_list_entry;
typedef struct duckdb_v2_hugeint_t duckdb_v2_hugeint_t;
typedef struct duckdb_v2_uhugeint_t duckdb_v2_uhugeint_t;
typedef struct duckdb_v2_interval_t duckdb_v2_interval_t;
/* --- Types for vector --- */
/* --- Constants for vector --- */
/* --- Function pointer typedefs for vector --- */
/* --- Functions for vector --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the internal representation kind: flat, constant, or dictionary.
*
* Reports VECTOR_TYPE_OTHER for FSST / SEQUENCE / SHREDDED vectors, which must be passed through vector_flatten before
* vector_get_view will read them.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector.
* @param out_type Receives the representation kind.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_vector_type(duckdb_v2_vector_handle vector,
DUCKDB_V2_VECTOR_TYPE *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the vector's logical type.
*
* The returned logical type is the same type that was passed to vector_reference, or the type that was set on creation.
* It is caller-owned; destroy it via logical_type_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector.
* @param out_type Receives the caller-owned logical type handle. Destroy via logical_type_destroy.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_logical_type(duckdb_v2_vector_handle vector,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reads a vector as a unified view of data, validity, selection, and count.
*
* Populates out_view with borrowed pointers, valid until the owning chunk is destroyed. view.data addresses the
* vector's elements, to be cast to the layout its logical type implies: a typed leaf array for the primitives,
* hugeint_t / uhugeint_t / interval_t for those kinds, bytes for VARCHAR / BLOB / BIT / BIGNUM, list_entry for LIST and
* MAP, and nothing at all for ARRAY / STRUCT / UNION, whose data lives in their children.
*
* DECIMAL and ENUM are typed leaf arrays too, over a storage tier that follows from the type; both mappings are
* contract. A DECIMAL of width <= 4 stores int16, <= 9 int32, <= 18 int64, and <= 38 int128, boundaries inclusive, with
* the width and scale available from logical_type_get_param. An ENUM stores its dictionary indices as uint8 for a
* dictionary of at most 255 entries, uint16 for at most 65535, and uint32 beyond that, boundaries inclusive and an
* empty dictionary uint8; logical_type_get_param resolves an index to its entry.
*
* Rejects VECTOR_TYPE_OTHER; call vector_flatten first.
*
* Reading a DICTIONARY vector has one side effect: the dictionary's underlying child is flattened in place if it is not
* already FLAT. The parent vector stays DICTIONARY, and only the child's storage shape changes, but any pointer
* previously borrowed into that child — from an earlier vector_get_view on a vector aliasing the same buffer, say — is
* invalidated. This is the only mutation vector_get_view performs; compare vector_flatten, which materializes the whole
* vector to FLAT.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to read.
* @param out_view Receives the view. Its pointers are borrowed and valid until the owning chunk is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_view(duckdb_v2_vector_handle vector, duckdb_v2_vector_view *out_view,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of elements in the vector.
*
* The size is the number of logical elements the vector represents, which for a nested kind can differ from the size of
* its children. An ARRAY vector of size 10 whose array size is 3, for instance, has 10 logical elements while its
* single child vector has 30.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector.
* @param out_size Receives the number of elements.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_size(duckdb_v2_vector_handle vector, idx_t *out_size,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the number of elements in the vector.
*
* The counterpart of vector_get_size: it declares how many logical elements the vector now holds. It reserves enough
* space for size logical elements.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector.
* @param size The new number of logical elements.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_set_size(duckdb_v2_vector_handle vector, idx_t size,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reads one cell of a vector as an owned value.
*
* The total fallback reader. It reads any logical row of any vector representation without flattening — FLAT, CONSTANT,
* DICTIONARY, and the compressed kinds the view getter rejects — and covers every type kind, including those with no
* committed view layout (today VARIANT and GEOMETRY), where it is the only way to reach a cell.
*
* Each call allocates one owned value, which makes this a single-cell bridge rather than a per-row loop primitive; use
* vector_get_view on hot paths. The row index is logical and bounds-checked against vector_get_size. The returned value
* is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to read from.
* @param row The logical row index, in [0, vector_get_size).
* @param out_value Receives the owned cell value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_value(duckdb_v2_vector_handle vector, idx_t row,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Writes one cell of a FLAT vector from a value.
*
* The total fallback writer. It covers every type kind, including those with no committed view layout (today VARIANT
* and GEOMETRY), where it is the only way to write a cell. The value is borrowed and copied in, then cast to the
* vector's type through the non-strict default cast; a cast failure surfaces from the call. A NULL value clears the
* row's validity.
*
* Requires a FLAT vector: constant, dictionary, and compressed representations are not row-addressable, so call
* vector_flatten first. Each call performs one value write, which makes this a single-cell bridge rather than a per-row
* loop primitive; use the typed mutable-data paths on hot paths. The row index is logical and bounds-checked against
* vector_get_size.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to write to.
* @param row The logical row index, in [0, vector_get_size).
* @param value The borrowed value to write. Copied in; cast to the vector's type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_set_value(duckdb_v2_vector_handle vector, idx_t row,
duckdb_v2_value_handle value, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns a mutable pointer to the data of a FLAT or CONSTANT vector.
*
* Any other representation returns ERROR_INPUT_INVALID. The pointer is valid until the owning chunk is destroyed, and
* the vector's storage shape must not change — through a flatten, say — while it is in use.
*
* When writing VARCHAR values, the caller must ensure that the bytes contain valid UTF-8.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector.
* @param out_data Receives a mutable pointer to the data.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_data_mutable(duckdb_v2_vector_handle vector, void **out_data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Forces a vector into FLAT representation, in place.
*
* A no-op for a vector that is already FLAT. For a CONSTANT, DICTIONARY, FSST, SEQUENCE, or SHREDDED vector it
* materializes the per-row data and switches the representation to FLAT. Call it before vector_get_view if you would
* rather not handle CONSTANT and DICTIONARY semantics in the view; it is required for any vector reporting
* VECTOR_TYPE_OTHER.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to flatten.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_flatten(duckdb_v2_vector_handle vector, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Casts every row of a vector into another vector, using a factory.
*
* The conversion is the one SQL `CAST` / `TRY_CAST` performs, registered custom casts included, from the type of
* `source` to the type of `target`. It covers as many rows as `source` holds (`duckdb_v2_vector_get_size()`), of any
* representation. `target` is replaced by the result, as `duckdb_v2_vector_reference()` would, taking its size: data
* and views taken from it beforehand do not survive the call, and nothing it held before carries over. In
* CAST_MODE_NORMAL a row that does not convert fails the call with the engine's conversion error, and the contents of
* `target` are unspecified. In CAST_MODE_TRY such rows are NULL in `target` instead and the call succeeds; compare the
* validity of `source` and `target` to find them. `cast_err` then receives the conversion error of one of them, e.g. to
* report why the cast did not convert every row.
*
* A connection's or callback's factory casts with that client's cast functions and settings (e.g. TimeZone). An
* instance's factory supports only the built-in casts, with default settings. `source` and `target` must be different
* vectors; `target` is typically a vector of a data chunk created by the caller, or the result vector of a callback.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory supplying the cast functions.
* @param source The vector to cast. Borrowed for the call only.
* @param target The vector to write the cast rows into. Its logical type is the target type.
* @param mode Whether a row that does not convert fails the call, or becomes NULL.
* @param out_converted Optional. Receives whether every row converted. Always true when a CAST_MODE_NORMAL cast
* succeeds.
* @param cast_err Optional. When a CAST_MODE_TRY cast succeeds without converting every row, receives an opaque info
* handle with the conversion error of one row that did not convert, which the caller must destroy via
* error_info_destroy. Otherwise receives NULL.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_cast(duckdb_v2_factory_handle factory, duckdb_v2_vector_handle source,
duckdb_v2_vector_handle target, DUCKDB_V2_CAST_MODE mode,
bool *out_converted, duckdb_v2_error_info_handle *cast_err,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Repoints a vector at another vector's data, without copying.
*
* `vector` takes on the storage of `source`: no data moves, and the two alias the same buffers until one of them is
* reset or re-referenced. Works for any type, including nested types. The source's logical type must equal the
* vector's; a mismatch returns ERROR_INPUT_INVALID. The source's data must outlive every read of `vector`. Use it to
* hand an already-materialized vector straight to an output vector without a per-row copy.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to repoint at the source's data.
* @param source The vector whose data to reference. Its logical type must equal the vector's.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_reference(duckdb_v2_vector_handle vector, duckdb_v2_vector_handle source,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Turns the vector into a CONSTANT vector holding the given value.
*
* Afterwards the vector holds a single element that applies to every logical row; write it through
* vector_get_data_mutable, which returns a pointer to that one element. For a STRUCT vector the change propagates to
* every child. The value's logical type must equal the vector's; a mismatch returns ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to make constant.
* @param value The value every row takes. Its logical type must equal the vector's.
* @param count The number of elements in the vector.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_make_constant(duckdb_v2_vector_handle vector,
duckdb_v2_value_handle value, idx_t count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets a vector to a SEQUENCE representation.
*
* Afterwards the vector represents the arithmetic sequence start, start+increment, start+2*increment, ... over count
* elements. No data pointer is involved; the three parameters describe the sequence completely.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to turn into a sequence.
* @param start The first value of the sequence.
* @param increment The step between consecutive values.
* @param count The number of elements in the sequence.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_make_sequence(duckdb_v2_vector_handle vector, int64_t start,
int64_t increment, idx_t count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets one row of a FLAT vector to NULL, nested children included.
*
* Clears the row's validity and broadcasts the NULL recursively to every descendant element under that row — STRUCT
* fields, and ARRAY elements strided by the array size — maintaining DuckDB's nested NULL invariant: when a STRUCT or
* ARRAY row is NULL, every descendant element under it must be NULL too. LIST children are left untouched, since their
* consumers gate on the list's own validity. Which kinds propagate is normative DuckDB behavior that evolves with the
* type system, which makes this the total NULL write path: equivalent to vector_set_value with a NULL value, without
* the per-call value allocation.
*
* Requires a FLAT vector: constant, dictionary, and compressed representations are not row-addressable, so call
* vector_flatten first. The row index is logical and bounds-checked against vector_get_size.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector to write to.
* @param row The logical row index, in [0, vector_get_size).
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_set_null(duckdb_v2_vector_handle vector, idx_t row,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns a mutable pointer to the validity mask of a FLAT vector.
*
* Allocates the mask on first use, so the returned pointer is always non-null. Each uint64_t word covers 64 rows: bit N
* of word W is row W*64+N. A set bit means valid; a cleared bit means NULL.
*
* A raw mask write marks only this vector's rows. Clearing a STRUCT or ARRAY parent bit leaves the descendant elements
* untouched, which violates DuckDB's nested NULL invariant — a NULL STRUCT or ARRAY row requires NULL descendants — so
* set nested rows NULL through vector_set_null instead. When writing nested masks raw anyway, invalidate the child
* masks up front and mark elements valid as the values are written.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector.
* @param out_validity Receives a mutable pointer to the validity mask.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_flat_get_validity_mutable(duckdb_v2_vector_handle vector,
uint64_t **out_validity,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the validity of a CONSTANT vector.
*
* A constant vector holds a single element, so one flag decides whether every row reads as the value or as NULL.
*
* history:
* - unstable: v2.0.0
*
* @param vector The constant vector.
* @param validity True to mark the vector's single element valid, false to mark it NULL.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_constant_set_valid(duckdb_v2_vector_handle vector, bool validity,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows a string-backed vector's arena for writing.
*
* Allocates the arena on first use. Valid for VARCHAR, BLOB, BIT, and BIGNUM vectors, and returns ERROR_INPUT_INVALID
* for anything else. This call is the single string-ness check, which is why arena_allocate itself performs none. The
* arena is borrowed — never destroy it — and stays valid until the vector is flattened, reallocated, or destroyed.
*
* history:
* - unstable: v2.0.0
*
* @param vector The string-backed vector whose arena to borrow.
* @param out_arena Receives the borrowed arena handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_arena(duckdb_v2_vector_handle vector,
duckdb_v2_arena_handle *out_arena,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of child vectors a nested vector exposes.
*
* 1 for LIST, MAP and ARRAY; the field count for STRUCT; member_count + 1 for UNION, the tag plus the members; and 0
* for any non-nested kind. vector_get_child documents what each index addresses.
*
* history:
* - unstable: v2.0.0
*
* @param vector The vector.
* @param out_count Receives the number of child vectors.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_child_count(duckdb_v2_vector_handle vector, idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Borrows a child vector by index.
*
* What each index addresses, by kind: LIST and ARRAY expose [0] = the elements; MAP [0] = the entries, a STRUCT(key,
* value) whose children are the keys and the values; STRUCT and TUPLE [i] = field i; and UNION [0] = the tag with
* [1..N] = the members. Note that value_get_child diverges on UNION, exposing only the active member.
*
* The returned child is borrowed and lives as long as the owning chunk. Returns ERROR_INPUT_INVALID if the vector has
* no children, or if the index is out of range.
*
* history:
* - unstable: v2.0.0
*
* @param vector The nested vector to descend into.
* @param index The child index, in [0, vector_get_child_count).
* @param out_child Receives the borrowed child vector.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_vector_get_child(duckdb_v2_vector_handle vector, idx_t index,
duckdb_v2_vector_handle *out_child,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Decodes BIGNUM storage bytes into a caller-supplied magnitude buffer + sign flag.
*
* in_data and in_length are the value's raw storage bytes, exactly as they sit in a vector's bignum payload or as
* value_get_blob reports them for a BIGNUM value. Those bytes are opaque: the storage encoding is not a committed part
* of this API, and this function is the only thing that interprets them.
*
* Writes the big-endian magnitude bytes into out_data and the sign flag into out_is_negative; reconstruct the integer
* as (-1)**out_is_negative * unsigned_big_endian(out_data[0..out_length]). Materializing the bytes is unavoidable,
* since a negative bignum stores its magnitude bit-inverted, but the buffer belongs to the caller: this function never
* allocates and hands back nothing to free.
*
* Pass out_data = NULL to size the buffer without decoding. out_length then receives the exact number of magnitude
* bytes and out_is_negative the sign, and out_capacity is ignored. The size comes straight out of the storage header,
* so the query is O(1) and exact — a size call followed by a decode call never needs a retry loop.
*
* With out_data != NULL, out_capacity must be at least out_length bytes, or the call returns ERROR_INPUT_OBJECT_SIZE
* with out_length set to the required size and out_data left untouched. On success exactly out_length bytes are
* written, and the rest of the buffer is not modified.
*
* Returns ERROR_INPUT_INVALID if in_data is NULL, or if in_length is too short to hold a bignum header.
*
* history:
* - unstable: v2.0.0
*
* @param in_data The value's raw BIGNUM storage bytes.
* @param in_length Size of in_data in bytes.
* @param out_data Caller-owned buffer receiving the magnitude bytes, or NULL to only report the required size in
* out_length.
* @param out_capacity Bytes available in out_data. Ignored when out_data is NULL.
* @param out_length Receives the magnitude size in bytes, written on success and on ERROR_INPUT_OBJECT_SIZE.
* @param out_is_negative Receives true if the value is negative, false otherwise.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_bignum_decode(const uint8_t *in_data, idx_t in_length, uint8_t *out_data,
idx_t out_capacity, idx_t *out_length, bool *out_is_negative,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Encodes a magnitude + sign flag into BIGNUM storage bytes.
*
* The inverse of bignum_decode. in_data and in_length are the big-endian magnitude bytes and is_negative the sign;
* out_data receives the raw storage bytes for that integer, in the form a BIGNUM vector payload expects. Those bytes
* are opaque: the storage encoding is not a committed part of this API.
*
* Pass out_data = NULL to size the buffer without encoding. out_length then receives the exact number of storage bytes,
* and out_capacity is ignored. The size is a fixed function of in_length, so the query is O(1) and exact.
*
* With out_data != NULL, out_capacity must be at least out_length bytes, or the call returns ERROR_INPUT_OBJECT_SIZE
* with out_length set to the required size and out_data left untouched. On success exactly out_length bytes are
* written, and the rest of the buffer is not modified.
*
* The magnitude must be canonical, matching what bignum_decode produces: in_length >= 1 with no leading zero bytes, so
* the value zero is the single byte 0x00 with is_negative = false. A NULL in_data, an in_length of 0, a leading zero
* byte, or a negative zero returns ERROR_INPUT_INVALID; a magnitude beyond the maximum bignum width returns
* ERROR_INPUT_OUT_OF_RANGE.
*
* history:
* - unstable: v2.0.0
*
* @param in_data Big-endian magnitude bytes, with no leading zero bytes.
* @param in_length Size of in_data in bytes. Must be >= 1.
* @param is_negative True to encode a negative value.
* @param out_data Caller-owned buffer receiving the storage bytes, or NULL to only report the required size in
* out_length.
* @param out_capacity Bytes available in out_data. Ignored when out_data is NULL.
* @param out_length Receives the storage size in bytes — written on success and on ERROR_INPUT_OBJECT_SIZE.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_bignum_encode(const uint8_t *in_data, idx_t in_length, bool is_negative,
uint8_t *out_data, idx_t out_capacity, idx_t *out_length,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Validates all text->len bytes as UTF-8, including bytes after embedded NUL characters.
*
* Returns ERROR_INPUT_INVALID if any of:
* - text is NULL.
* - text->ptr is NULL and text->len is nonzero.
* - The input contains malformed UTF-8.
*
* A view with a NULL ptr and zero length is valid.
*
* history:
* - unstable: v2.0.0
*
* @param text The bytes to validate.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_validate_utf8(const duckdb_v2_str *text, duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for vector --- */
struct duckdb_v2_vector_view {
const void *data;
const uint64_t *validity;
const duckdb_v2_sel_t *sel;
idx_t count;
};
struct duckdb_v2_list_entry {
idx_t offset;
idx_t length;
};
struct duckdb_v2_hugeint_t {
uint64_t lower;
int64_t upper;
};
struct duckdb_v2_uhugeint_t {
uint64_t lower;
uint64_t upper;
};
struct duckdb_v2_interval_t {
int32_t months;
int32_t days;
int64_t micros;
};
/* ============================================================================
* MODULE: prepared_statement
* ============================================================================ */
/* --- Enums for prepared_statement --- */
/* --- Struct forward declarations for prepared_statement --- */
/* --- Types for prepared_statement --- */
/*!
* An owned handle to a statement bound and planned once, executable repeatedly via
* `duckdb_v2_prepared_statement_execute()`. Construct with `duckdb_v2_prepared_statement_create()` and destroy with
* `duckdb_v2_prepared_statement_destroy()`. It keeps its connection's session alive, so it stays usable across
* executions and even after the connection is disconnected.
*/
typedef struct _duckdb_v2_prepared_statement {
void *internal_ptr;
} * duckdb_v2_prepared_statement_handle;
/* --- Constants for prepared_statement --- */
/* --- Function pointer typedefs for prepared_statement --- */
/* --- Functions for prepared_statement --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Prepares a parsed statement into a reusable handle. Non-consuming.
*
* Copies the statement's AST, then binds and plans it once. Binder and catalog errors surface here, exactly as they
* would from `duckdb_v2_statement_execute()`. The statement is borrowed rather than consumed, since a copy is what gets
* prepared, so it can be prepared again or executed directly; the caller destroys it with
* `duckdb_v2_sql_statement_destroy()`.
*
* By default this succeeds for any preparable statement, whether or not its plan will be reused; ask
* `duckdb_v2_prepared_statement_reuses_plan()` which one you got. Setting `require_cacheable` instead fails with
* `ERROR_INPUT_INVALID` when the plan would not be reused, so a caller who wants the handle only for the speedup finds
* out here rather than after silently taking the slow path.
*
* A statement that DuckDB expands into several, such as a dynamic PIVOT, is kept as written and expanded again at each
* execution, in the transaction state of that execution. It runs nothing here, its plan is never reused, and its
* result's metadata is deferred as for `duckdb_v2_statement_execute()`. Parameters on such a statement are refused with
* `ERROR_INPUT_INVALID`.
*
* Refuses with `ERROR_RESOURCE_IN_USE` while a statement on the connection is still running. Drain, destroy, or
* interrupt that result first, or prepare on another connection. `*out_prepared` is set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection supplying the catalog, transaction, and parser state. The prepared statement belongs to
* it.
* @param statement The statement to prepare. Borrowed and copied, not consumed; destroy it with
* `duckdb_v2_sql_statement_destroy()`.
* @param require_cacheable When true, fail with `ERROR_INPUT_INVALID` unless the prepared plan will be reused across
* executions, as `duckdb_v2_prepared_statement_reuses_plan()` would report it.
* @param out_prepared On success, receives the new prepared statement. Owned by the caller; destroy via
* `duckdb_v2_prepared_statement_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_prepared_statement_create(duckdb_v2_connection_handle conn,
duckdb_v2_sql_statement_handle statement,
bool require_cacheable,
duckdb_v2_prepared_statement_handle *out_prepared,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Executes a prepared statement, streaming its result. Non-consuming.
*
* Returns a result without executing anything: execution happens incrementally as the result is stepped or drained,
* exactly as with `duckdb_v2_statement_execute()`. The handle returned is an ordinary result, with identical behaviour
* throughout -- streaming, draining, the changed-row count of a DML statement, the output schema, the statement type,
* and the result type.
*
* `parameter_values` binds the statement's parameters as constants for this execution. Binding is positional by default
* ($1 = element 0); supply `parameter_names` to bind by name instead, where a non-empty entry binds its value to that
* named parameter ($name, matched case-insensitively) and a {NULL, 0} entry stays positional. Pass NULL for both
* arrays, or a count of 0, for a statement without parameters. Both arrays are borrowed and copied in, so the caller
* still owns and destroys them. A key set that does not match the statement's parameters is rejected with
* `ERROR_INPUT_INVALID`, with one exception: a named parameter left without a value reads the session variable of the
* same name (`SET VARIABLE`) when one exists.
*
* Not consumed: execute the same handle again, with the same values or different ones, as often as you like. Values are
* bound per execution and nothing carries over between them. A catalog change since the statement was prepared, or a
* parameter type that differs from the one the cached plan assumed, triggers a re-bind that is invisible apart from its
* cost.
*
* Refuses with `ERROR_RESOURCE_IN_USE` while a statement on the connection is still running; drain, destroy, or
* interrupt that result first, or execute on another connection. A failed execution, at any stage, leaves the prepared
* statement usable. `*out_result` is set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param prepared The prepared statement to execute. Borrowed; not consumed.
* @param parameter_names Optional. An array of `parameter_count` parameter names; a non-empty entry binds its value to
* the named parameter ($name, case-insensitive), a {NULL, 0} entry keeps it positional ($1 = element 0). Pass NULL to
* bind everything positionally.
* @param parameter_values Optional. An array of `parameter_count` values. Each binds by name when `parameter_names`
* supplies one, and positionally ($1 = element 0) otherwise. Borrowed and copied in. Pass NULL for a statement without
* parameters.
* @param parameter_count The number of entries in `parameter_names` and `parameter_values`. Pass 0 for a statement
* without parameters.
* @param out_result On success, receives the new result. Owned by the caller; destroy via `duckdb_v2_result_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_prepared_statement_execute(duckdb_v2_prepared_statement_handle prepared,
const duckdb_v2_identifier_t *parameter_names,
const duckdb_v2_value_handle *parameter_values,
idx_t parameter_count,
duckdb_v2_result_handle *out_result,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports whether the prepared statement reuses its compiled plan across executions.
*
* True when executions reuse the plan built at prepare time, provided the supplied values match the planned parameter
* types and nothing the plan depends on has changed; false when the statement re-binds on every execution, making it no
* faster than `duckdb_v2_statement_execute()`. A plan is reused only when all parameter types were resolved at prepare
* time and the plan is cacheable: `SELECT 42` reuses, `SELECT $1::INTEGER + 1` reuses, a statement reading a base table
* does not (it re-binds so a catalog change is picked up), and `SELECT $1 + $2` does not (the types are unknown until
* values arrive).
*
* A static property of the built plan, fixed when the statement was prepared and independent of the values later passed
* to `duckdb_v2_prepared_statement_execute()`.
*
* history:
* - unstable: v2.0.0
*
* @param prepared The prepared statement to inspect.
* @param out_reuses Receives true when the compiled plan is reused across executions, false when the statement re-binds
* each time.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_prepared_statement_reuses_plan(duckdb_v2_prepared_statement_handle prepared,
bool *out_reuses,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a prepared statement.
*
* Null-safe: passing NULL, or a slot already set to NULL, is a no-op. A result produced by
* `duckdb_v2_prepared_statement_execute()` is independently owned and keeps the session alive itself, so the prepared
* statement may be destroyed while results made from it are still live. On success the slot is set to NULL.
*
* history:
* - unstable: v2.0.0
*
* @param prepared The prepared statement to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_prepared_statement_destroy(duckdb_v2_prepared_statement_handle *prepared);
#endif
/* --- Struct definitions for prepared_statement --- */
/* ============================================================================
* MODULE: query_result
* ============================================================================ */
/* --- Enums for query_result --- */
/*!
* Shape of a query result. QUERY_RESULT carries rows and columns; CHANGED_ROWS carries an affected row count, as an
* INSERT, UPDATE, or DELETE without RETURNING produces; NOTHING covers DDL and other statements with no row output.
*/
typedef enum DUCKDB_V2_RESULT_TYPE {
DUCKDB_V2_RESULT_TYPE_QUERY_RESULT = 0,
DUCKDB_V2_RESULT_TYPE_CHANGED_ROWS = 1,
DUCKDB_V2_RESULT_TYPE_NOTHING = 2,
DUCKDB_V2_RESULT_TYPE_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_RESULT_TYPE;
/*!
* Outcome of a result_step call. WAITING is the 0-value, so a zero-initialized out-param reads as "no work product yet"
* rather than CHUNK, the same convention VECTOR_TYPE_OTHER follows. The four states are the ones a consumer acts on;
* they are deliberately not a projection of any internal enum.
*/
typedef enum DUCKDB_V2_RESULT_STEP_STATUS {
//! No chunk yet; step again, or block in result_wait.
DUCKDB_V2_RESULT_STEP_STATUS_WAITING = 0,
//! A caller-owned chunk was written to *out_chunk, or an array to *out_array.
DUCKDB_V2_RESULT_STEP_STATUS_CHUNK = 1,
//! Stream exhausted. Sticky.
DUCKDB_V2_RESULT_STEP_STATUS_FINISHED = 2,
//! Query was interrupted. Sticky.
DUCKDB_V2_RESULT_STEP_STATUS_CANCELLED = 3,
DUCKDB_V2_RESULT_STEP_STATUS_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_RESULT_STEP_STATUS;
/* --- Struct forward declarations for query_result --- */
/* --- Types for query_result --- */
/* --- Constants for query_result --- */
/* --- Function pointer typedefs for query_result --- */
/* --- Functions for query_result --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Executes a parsed statement on the connection, streaming its result. Non-consuming.
*
* Takes a statement produced by the sql_statement module (parse_sql / statement_iterator_next), preprocesses and
* prepares it, and returns a result handle without executing anything: execution happens incrementally as the result is
* stepped (result_step) or drained (result_fetch_chunk). This call reports only the errors detectable at prepare time —
* binder, catalog, pragma preprocessing — while errors raised during execution surface from the stepping functions.
*
* The statement is borrowed, not consumed, since a copy is what executes. It can be executed again, for example with a
* different set of values, and the caller destroys it with sql_statement_destroy.
*
* parameter_values binds the statement's parameters as constants for this execution. Binding is positional by default:
* the i-th value binds $(i+1), matching SQL's own convention, so dense $1..$N and ? placeholders work directly. Supply
* parameter_names to bind by name instead — a non-empty name binds its value to that named parameter ($name, matched
* case-insensitively), while a {NULL, 0} entry leaves that value positional. The parameter schema from statement_bind
* lists the names to use. Both arrays are borrowed and copied in; the caller still owns and destroys them. Pass NULL
* for both, or a count of 0, for an unparameterized statement. A key set that does not match the statement's parameters
* — names for a positional statement, or the reverse — is rejected with ERROR_INPUT_INVALID, and named and positional
* parameters cannot be mixed within one statement. Parameters and statement expansion are mutually exclusive: passing
* values for a statement that preprocesses into a group is rejected with ERROR_INPUT_INVALID.
*
* DuckDB can expand one statement into a group: a dynamic PIVOT, or statement-expanding DDL such as ALTER ... ADD
* COLUMN with a non-constant DEFAULT. The group executes as one result through the same steps, and the stream surfaces
* the rows of the first row-producing statement of the group. A row-producing statement followed by another cannot be
* served as a single result and reports ERROR_QUERY_NOT_IMPLEMENTED; no known expansion produces one.
*
* One running statement per connection: this refuses with ERROR_RESOURCE_IN_USE while a statement on the connection is
* still running. Drain, destroy, or interrupt that result first, or open another connection.
*
* Schema metadata — result type, statement type, column count, names, logical types — is available on the returned
* handle immediately, before the first step.
*
* *out_result is set to nullptr on failure.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection on which to execute the statement.
* @param statement The statement to execute. Borrowed and copied; not consumed. Destroy it with sql_statement_destroy.
* @param parameter_names Optional. An array of parameter_count parameter names; a non-empty entry binds its value to
* the named parameter ($name, case-insensitive), a {NULL, 0} entry keeps it positional ($1 = element 0). Pass NULL for
* all-positional binding. Named and positional parameters cannot be mixed within one statement.
* @param parameter_values Optional. An array of parameter_count value handles. Each binds by name when parameter_names
* supplies one, otherwise positionally ($1 = element 0). Borrowed (copied in). Pass NULL for an unparameterized
* statement.
* @param parameter_count The number of parameters in parameter_names and parameter_values. Pass 0 for an
* unparameterized statement.
* @param out_result Receives the new result handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_statement_execute(duckdb_v2_connection_handle conn,
duckdb_v2_sql_statement_handle statement,
const duckdb_v2_identifier_t *parameter_names,
const duckdb_v2_value_handle *parameter_values,
idx_t parameter_count, duckdb_v2_result_handle *out_result,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a result handle.
*
* Null-safe: passing nullptr or a slot already set to nullptr is a no-op. Frees the memory the result owns and releases
* the connection for its next query. Safe at any point in the stream's life. Destroying a result before its statement
* ended (drained, or stepped to FINISHED) aborts the statement. On autocommit, its writes are rolled back. Inside a
* transaction, a statement that may write invalidates the transaction, and a read-only statement just stops. Chunks
* already fetched are caller-owned and stay valid. On success the slot is set to nullptr.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_destroy(duckdb_v2_result_handle *result);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Runs one bounded unit of query execution and returns without blocking.
*
* The streaming primitive: a step does a bounded amount of execution work, mostly without blocking, and returns control
* to the caller, so an event loop stays responsive and can interleave other work between steps. The conveniences —
* result_wait, result_fetch_chunk, result_drain — block, and are for synchronous callers. out_status reports the
* outcome:
*
* - CHUNK: *out_chunk receives a caller-owned chunk (destroy via data_chunk_destroy). Written only for this status;
* nullptr otherwise.
* - WAITING: no chunk yet, but work was done. Transient: keep stepping and it resolves to CHUNK, FINISHED, CANCELLED,
* or an error. Block in result_wait rather than busy-stepping.
* - FINISHED: stream exhausted. Sticky.
* - CANCELLED: query interrupted via connection_interrupt. Sticky. Cancellation is a status here, not an error;
* result_fetch_chunk, which has no status out-param, reports it as ERROR_RUNTIME_INTERRUPT.
*
* Execution errors come back as the return code plus err, never as a status; out_status is then unspecified and
* *out_chunk is nullptr. Errors are sticky, so later steps report the same code.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to step.
* @param out_chunk Receives an owned chunk if *out_status is CHUNK; set to nullptr otherwise.
* @param out_status Receives the step status.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_step(duckdb_v2_result_handle result,
duckdb_v2_data_chunk_handle *out_chunk,
DUCKDB_V2_RESULT_STEP_STATUS *out_status,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Blocks until the next chunk is available and returns it.
*
* A convenience over result_step: blocks until a chunk is produced or the stream ends. On success *out_chunk receives a
* caller-owned chunk (destroy via data_chunk_destroy), or nullptr at end-of-stream. End-of-stream is sticky, so later
* calls keep succeeding with *out_chunk set to nullptr.
*
* An interrupted query returns ERROR_RUNTIME_INTERRUPT — the same event result_step reports as status CANCELLED,
* carried on the error channel because this function has no status out-param.
*
* On failure *out_chunk is set to nullptr. Errors are sticky, so later calls report the same code.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to fetch from.
* @param out_chunk Receives an owned chunk, or nullptr at end-of-stream.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_fetch_chunk(duckdb_v2_result_handle result,
duckdb_v2_data_chunk_handle *out_chunk,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Blocks until result_step can make progress.
*
* A convenience over result_step: blocks until a step is worth issuing again, that is, until a unit of execution work
* can run on the calling thread. Never produces or consumes chunks. Waiting on a terminal result — FINISHED, CANCELLED,
* or a sticky error — returns immediately; it is a no-op, never an error.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to wait on.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_wait(duckdb_v2_result_handle result, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Renders the result as a box table, consuming it.
*
* Drains the result into a column data collection and renders it with the same renderer the DuckDB CLI uses, so every
* client displays results identically without reimplementing table formatting. The result is consumed by transfer: the
* slot is set to NULL on success and on failure alike. A partially consumed result is accepted, and the remainder is
* what gets rendered.
*
* The whole remaining result materializes in memory before rendering. max_rows bounds what is DISPLAYED, not what is
* read, so with limit 0 the footer's row count is exact. A caller who cannot afford full materialization should bound
* the query itself (e.g. LIMIT n) and pass n as limit; the footer then renders "? rows" whenever the result fills that
* bound, since the true total is unknown at that point.
*
* Zero selects the renderer default for each sizing knob: max_rows 20, max_width the probed terminal width or 80 when
* that is unavailable, max_col_width 20. An empty null_value renders NULL cells as the default "NULL" text.
*
* The rendered text goes to sink rather than being returned: a box can be large, and this way nothing allocates a
* buffer the caller has to free. The sink is called exactly once with the whole box, so its view carries the full
* length — write it straight to a stream, or copy it into your own string. sink must not be NULL.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to render; consumed and set to NULL. Left intact only when the call rejects null arguments.
* @param max_rows Maximum rows displayed; 0 selects the renderer default (20).
* @param max_width Maximum total width in characters; 0 selects the renderer default.
* @param max_col_width Maximum width of one column; 0 selects the renderer default (20).
* @param null_value Text rendered for NULL cells; empty selects "NULL".
* @param render_mode 0 renders rows (records down the page); 1 renders columns; other values are rejected with
* INVALID_INPUT.
* @param limit The row limit the caller applied to the query before rendering; 0 means none. When the materialized
* result holds exactly this many rows the true total is unknown, so the footer renders "? rows" instead of an exact
* count.
* @param sink Receives the whole rendered box in a single call. Borrowed for the duration of that call; see text_sink
* for the full contract.
* @param user_data Opaque pointer passed through to sink untouched. May be NULL.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_render_box(duckdb_v2_result_handle *result, idx_t max_rows,
idx_t max_width, idx_t max_col_width,
const duckdb_v2_str *null_value, idx_t render_mode,
idx_t limit, duckdb_v2_text_sink_fn sink, void *user_data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Runs the result to completion and reports the changed-row count.
*
* A convenience over result_step: blocks until the stream is fully consumed, so every side effect is applied. Rows of a
* row-producing result are discarded. For a CHANGED_ROWS result *out_rows_changed receives the affected row count; for
* every other result type, and for a stream whose Count chunk was already consumed, it receives 0.
*
* The result type (result_get_result_type) is prepare-time metadata, so a caller can choose between consuming rows and
* draining without inspecting the SQL. Draining an already FINISHED result succeeds. Cancellation surfaces as
* ERROR_RUNTIME_INTERRUPT; errors are sticky, and on failure *out_rows_changed is unspecified.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to drain.
* @param out_rows_changed Receives the affected row count for CHANGED_ROWS results, 0 otherwise.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_drain(duckdb_v2_result_handle result, idx_t *out_rows_changed,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the shape of the result: query, changed rows, or nothing.
*
* QUERY_RESULT for statements that produce rows (SELECT, RETURNING, EXPLAIN), CHANGED_ROWS for an INSERT, UPDATE, or
* DELETE without RETURNING, NOTHING for DDL and other statements with no row output.
*
* Prepare-time metadata: available from statement_execute on, except for a statement that expands into a group, where
* it fails with ERROR_INPUT_METADATA_DEFERRED until stepping has bound the row-producing statement, or the group ended
* without one.
*
* history:
* - unstable: v2.0.0
*
* @param result The result.
* @param out_type Receives the result shape.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_get_result_type(duckdb_v2_result_handle result,
DUCKDB_V2_RESULT_TYPE *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the SQL statement type that produced the result.
*
* Prepare-time metadata: available from statement_execute on. A statement that expands into a group reports its type as
* written: MULTI, or PRAGMA for a pragma such as IMPORT DATABASE.
*
* history:
* - unstable: v2.0.0
*
* @param result The result.
* @param out_type Receives the statement type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_get_statement_type(duckdb_v2_result_handle result,
DUCKDB_V2_STATEMENT_TYPE *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the result's output schema as a single schema handle.
*
* Builds an owned schema of the result's column names and types into *out_schema; destroy it via schema_destroy.
* Prepare-time metadata, available before the first step, or for an expanding statement once stepping has bound the
* row-producing statement (before that it fails with ERROR_INPUT_METADATA_DEFERRED). Never empty: a non-SELECT reports
* a single status column, either a BIGINT changed-rows count or a BOOLEAN success.
*
* This schema is the authoritative source for the column types of the chunks the result produces; vectors do not carry
* their own type.
*
* *out_schema is set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param result The result.
* @param out_schema Receives the owned output schema. Destroy via schema_destroy.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_result_get_schema(duckdb_v2_result_handle result,
duckdb_v2_schema_handle *out_schema,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for query_result --- */
/* ============================================================================
* MODULE: table
* ============================================================================ */
/* --- Enums for table --- */
/*!
* Whether a table function's scan is partitioned by a given set of columns, and how. Reported by
* `duckdb_v2_table_function_set_partitioning_callback()` via
* `duckdb_v2_table_function_partitioning_set_partition_info()`.
*/
typedef enum DUCKDB_V2_TABLE_PARTITION_INFO {
//! The scan is not known to be partitioned by the requested columns.
DUCKDB_V2_TABLE_PARTITION_INFO_NOT_PARTITIONED = 0,
//! Each partition the scan produces carries exactly one distinct value for the requested columns.
DUCKDB_V2_TABLE_PARTITION_INFO_SINGLE_VALUE_PARTITIONS = 1,
//! The partitions the scan produces overlap only at their boundaries.
DUCKDB_V2_TABLE_PARTITION_INFO_OVERLAPPING_PARTITIONS = 2,
//! The partitions the scan produces are disjoint ranges.
DUCKDB_V2_TABLE_PARTITION_INFO_DISJOINT_PARTITIONS = 3,
DUCKDB_V2_TABLE_PARTITION_INFO_MAX_ENUM = 0x7FFFFFFF,
} DUCKDB_V2_TABLE_PARTITION_INFO;
/* --- Struct forward declarations for table --- */
/* --- Types for table --- */
/*!
* An owned opaque handle to a custom table function being built. Created with `duckdb_v2_table_function_create()`,
* configured with the setter functions (e.g. `duckdb_v2_table_function_set_name()`,
* `duckdb_v2_table_function_set_exec_callback()`, etc.) and the signature obtained via
* `duckdb_v2_table_function_get_signature()`, made available with `duckdb_v2_connection_register_table_function()` or
* `duckdb_v2_extension_register_table_function()`, and destroyed with `duckdb_v2_table_function_destroy()`.
*/
typedef struct _duckdb_v2_table_function {
void *internal_ptr;
} * duckdb_v2_table_function_handle;
/*!
* A borrowed opaque handle to the result of a table function's "bind" phase. The "bind" callback receives this handle
* next to a `duckdb_v2_function_bind_info_handle`, which gives access to the arguments, the user data and the bind
* data. It must use this handle to declare the columns the function returns, and can use it to hint at the number of
* rows the scan will produce.
*/
typedef struct _duckdb_v2_table_function_bind_info {
void *internal_ptr;
} * duckdb_v2_table_function_bind_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function during the global state initialization "init
* global" phase. The "init global" callback receives this handle and can use it to e.g. set up the state shared by
* every thread scanning the function, and to declare how many threads may scan it.
*/
typedef struct _duckdb_v2_table_function_init_global_info {
void *internal_ptr;
} * duckdb_v2_table_function_init_global_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function during the local state initialization "init
* local" phase. The "init local" callback receives this handle and can use it to e.g. set up worker-local state,
* typically by claiming work from the shared global state.
*/
typedef struct _duckdb_v2_table_function_init_local_info {
void *internal_ptr;
} * duckdb_v2_table_function_init_local_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function during the execution "exec" phase. The "exec"
* callback receives this handle and can use it to e.g. access the global and local state and write the next batch of
* rows to the output chunk.
*/
typedef struct _duckdb_v2_table_function_exec_info {
void *internal_ptr;
} * duckdb_v2_table_function_exec_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function during the "progress" phase. The "progress"
* callback receives this handle and can use it to report how far the scan has advanced.
*/
typedef struct _duckdb_v2_table_function_progress_info {
void *internal_ptr;
} * duckdb_v2_table_function_progress_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function during the "filter pushdown" phase of query
* optimization. The "filter pushdown" callback receives this handle and can use it to inspect the filter predicates the
* query applies to the function's rows, and to accept the ones it will apply itself.
*/
typedef struct _duckdb_v2_table_function_filter_pushdown_info {
void *internal_ptr;
} * duckdb_v2_table_function_filter_pushdown_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function during the "partition data" phase. The engine
* invokes the callback on the worker thread that just produced a batch of rows, once per batch, only when a downstream
* operator needs to know the batch's ordering position, the values of a set of partitioning columns, or both; the
* handle reports which of those were actually requested and receives the answer.
*/
typedef struct _duckdb_v2_table_function_partition_data_info {
void *internal_ptr;
} * duckdb_v2_table_function_partition_data_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function during the "partitioning" phase of query
* optimization. The engine invokes the callback once per candidate `GROUP BY` column set, before execution starts, to
* decide whether the scan can feed a partitioned aggregate directly instead of hashing.
*/
typedef struct _duckdb_v2_table_function_partitioning_info {
void *internal_ptr;
} * duckdb_v2_table_function_partitioning_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function when a scanning thread claims its next batch
* of work. The "claim batch" callback receives this handle and can use it to claim the next part of the scan from the
* shared global state for the thread's local state, and to report whether it claimed one.
*/
typedef struct _duckdb_v2_table_function_claim_batch_info {
void *internal_ptr;
} * duckdb_v2_table_function_claim_batch_info_handle;
/*!
* A borrowed opaque handle to the arguments supplied to a table function when the engine asks it to describe a bound
* call. The "get bind info" callback receives this handle, and can use it to describe the call in more detail than its
* columns: with identifiers of its columns (e.g. field ids), and with options - key-value facts about what the call
* reads.
*/
typedef struct _duckdb_v2_table_function_get_bind_info_info {
void *internal_ptr;
} * duckdb_v2_table_function_get_bind_info_info_handle;
/*!
* An owned opaque handle to a multi-file table function being built. A multi-file function wraps an already registered
* table function that reads a single file, and adds everything that is needed to read many files at once on top of it:
* globbing, lists of files, hive partitioning, the `filename` column, `union_by_name` and the like. Created with
* `duckdb_v2_multi_file_function_create()`, configured with the setter functions (e.g.
* `duckdb_v2_multi_file_function_set_name()`, `duckdb_v2_multi_file_function_set_single_file_function()`), made
* available with `duckdb_v2_connection_register_multi_file_function()` or
* `duckdb_v2_extension_register_multi_file_function()`, and destroyed with `duckdb_v2_multi_file_function_destroy()`.
*/
typedef struct _duckdb_v2_multi_file_function {
void *internal_ptr;
} * duckdb_v2_multi_file_function_handle;
/* --- Constants for table --- */
/* --- Function pointer typedefs for table --- */
typedef void (*duckdb_v2_table_function_bind_callback_fn)(duckdb_v2_function_bind_info_handle info,
duckdb_v2_table_function_bind_info_handle result,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_init_global_callback_fn)(duckdb_v2_table_function_init_global_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_init_local_callback_fn)(duckdb_v2_table_function_init_local_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_exec_callback_fn)(duckdb_v2_table_function_exec_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_progress_callback_fn)(duckdb_v2_table_function_progress_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_filter_pushdown_callback_fn)(
duckdb_v2_table_function_filter_pushdown_info_handle info, duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_partition_data_callback_fn)(
duckdb_v2_table_function_partition_data_info_handle info, duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_partitioning_callback_fn)(
duckdb_v2_table_function_partitioning_info_handle info, duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_claim_batch_callback_fn)(duckdb_v2_table_function_claim_batch_info_handle info,
duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
typedef void (*duckdb_v2_table_function_get_bind_info_callback_fn)(
duckdb_v2_table_function_get_bind_info_info_handle info, duckdb_v2_context_handle context,
duckdb_v2_error_info_handle *err);
/* --- Functions for table --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new table function through a factory.
*
* The function starts out empty: configure it with the setter functions (e.g. `duckdb_v2_table_function_set_name()`,
* `duckdb_v2_table_function_set_exec_callback()`, etc.) and the signature obtained via
* `duckdb_v2_table_function_get_signature()`, then make it available with
* `duckdb_v2_connection_register_table_function()` or `duckdb_v2_extension_register_table_function()`. The caller owns
* the returned handle and must destroy it with `duckdb_v2_table_function_destroy()`, also after registration.
*
* The table function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the table function through.
* @param function On success, receives the newly created table function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_create(duckdb_v2_factory_handle factory,
duckdb_v2_table_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the table function.
*
* The name is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_name(duckdb_v2_table_function_handle function,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the documentation of the function so it can be filled in.
*
* Set a description with `duckdb_v2_function_docs_set_description()`, and add examples and categories with
* `duckdb_v2_function_docs_add_example()` and `duckdb_v2_function_docs_add_category()`. The documentation is modified
* in place, describes this overload only, and is registered with the function. Optional.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the documentation of.
* @param docs The returned documentation. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_get_docs(duckdb_v2_table_function_handle function,
duckdb_v2_function_docs_handle *docs,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the function's signature so it can be configured.
*
* Add parameters with `duckdb_v2_function_signature_add_parameter()`. The signature is modified in place. A table
* function declares the columns it returns from its bind callback instead of through a return type, so registration
* rejects a signature whose return type was set with `duckdb_v2_function_signature_set_return_type()`.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to get the signature of.
* @param sig The returned signature. Borrowed and valid for the lifetime of the function handle.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_get_signature(duckdb_v2_table_function_handle function,
duckdb_v2_function_signature_handle *sig,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets arbitrary user data on the table function.
*
* Associates an opaque pointer with the function, retrievable from the callbacks via
* `duckdb_v2_function_bind_get_user_data()`, `duckdb_v2_table_function_init_global_get_user_data()`,
* `duckdb_v2_table_function_exec_get_user_data()` and their counterparts on the other phases. The opaque handle bundles
* the pointer with an optional destructor, invoked when the data is no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the user data of.
* @param data Opaque handle bundling the user data pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_user_data(duckdb_v2_table_function_handle function,
duckdb_v2_opaque *data,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the bind callback of the table function.
*
* The bind callback is invoked during query planning for each call site of the function. It must declare the columns
* the function returns via `duckdb_v2_table_function_bind_add_result_column()`. Through its
* `duckdb_v2_function_bind_info_handle` it can also inspect the constant argument values and set "bind data" that is
* shared with all later callbacks. A bind callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the bind callback of.
* @param callback The bind callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_bind_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_bind_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional global init callback of the table function.
*
* The global init callback is invoked once per scan, at the start of execution. It can set "global state" shared by
* every thread scanning the function, and declare how many threads may scan it in parallel via
* `duckdb_v2_table_function_init_global_set_max_threads()`.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the global init callback of.
* @param callback The global init callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_init_global_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_init_global_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional local init callback of the table function.
*
* The local init callback is invoked once per thread that will scan the function. It can set worker-local "local
* state", retrievable from the exec callback, typically derived from the shared global state.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the local init callback of.
* @param callback The local init callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_init_local_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_init_local_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the exec callback of the table function.
*
* The exec callback implements the function's logic: it is invoked repeatedly during query execution and writes the
* next batch of rows to the output chunk, until it produces an empty batch to signal the end of the scan. An exec
* callback must be set before registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the exec callback of.
* @param callback The exec callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_exec_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_exec_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional progress callback of the table function.
*
* The progress callback is invoked on demand during execution to report how far the scan has advanced, which the engine
* surfaces as the query's progress. It is invoked concurrently with the exec callback, so it must read the global state
* in a thread-safe way.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the progress callback of.
* @param callback The progress callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_progress_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_progress_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets whether the table function supports projection pushdown. Defaults to false.
*
* With projection pushdown, the engine asks the function for only the columns a query actually uses: the exec
* callback's output chunk holds one vector per requested column rather than one per column declared in bind, and the
* global init, local init and exec callbacks can look up which declared column each vector stands for via e.g.
* `duckdb_v2_table_function_exec_get_column_index()`. Without it the output chunk always holds every declared column,
* and the engine drops the unused ones itself.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to configure.
* @param enable Whether the function supports projection pushdown.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_projection_pushdown(duckdb_v2_table_function_handle function,
bool enable,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional filter pushdown callback of the table function.
*
* The filter pushdown callback is invoked while the query is optimized, after the bind callback and before any init
* callback, with the filter predicates the query applies to the function's rows. Each predicate is a bound expression
* the callback can inspect with the `expression` functions; the callback accepts the predicates it will apply itself
* via `duckdb_v2_table_function_filter_pushdown_accept()`, typically after recording what they select in the bind data.
* The engine then stops applying the accepted predicates and keeps applying the rest above the scan, so accepting a
* predicate is a promise to filter the rows exactly as it would have. The optimizer may invoke the callback more than
* once for the same query, each time with the predicates not yet accepted; it is not invoked when there are none.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the filter pushdown callback of.
* @param callback The filter pushdown callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_filter_pushdown_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_filter_pushdown_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional "partition data" callback of the table function.
*
* The callback reports, for the batch the exec callback just produced, an ordering batch index, the values of a set of
* partitioning columns, or both, depending on what a downstream operator requires; it runs on the worker thread that
* produced the batch. Set `duckdb_v2_table_function_set_partitioning_callback()` too when the function can answer
* partitioning-column requests, since the engine only asks a scan for those when that callback reports
* `TABLE_PARTITION_INFO_SINGLE_VALUE_PARTITIONS`.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the partition data callback of.
* @param callback The partition data callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_partition_data_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_partition_data_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional "partitioning" callback of the table function.
*
* The callback tells the query optimizer, for a candidate `GROUP BY` column set, whether every partition the scan
* produces carries exactly one distinct value for those columns; only `TABLE_PARTITION_INFO_SINGLE_VALUE_PARTITIONS`
* unlocks the partitioned aggregate optimization; any other result, or leaving this callback unset, keeps the regular
* hash aggregate. It runs on the planning thread, before execution starts, and must be deterministic for a given column
* set since it may be called on a plan the optimizer later discards. Registration fails unless
* `duckdb_v2_table_function_set_partition_data_callback()` is set too, since the engine asks that callback for the
* partitioning column values once this one claims single-value partitions.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the partitioning callback of.
* @param callback The partitioning callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_partitioning_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_partitioning_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Declares one of the columns the function returns.
*
* Call this once per column, in order: the columns declared here are the columns of the table the function produces,
* and the vectors of the output chunk the exec callback fills follow the same order. At least one column must be
* declared. The type must be a fully defined concrete type; ANY is rejected, as a result column carries data. The name
* and type are borrowed and copied.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param name The name of the column. Borrowed and copied.
* @param type The type of the column. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_bind_add_result_column(
duckdb_v2_table_function_bind_info_handle info, const duckdb_v2_identifier_t *name,
duckdb_v2_logical_type_handle type, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the estimated number of rows the scan will produce.
*
* The estimate is a hint for the optimizer, not a limit: producing a different number of rows is not an error. Without
* it, the optimizer falls back on its own defaults.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param cardinality The estimated number of rows.
* @param is_exact Whether the estimate is exact, which also makes it an upper bound on the row count.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_bind_set_cardinality(
duckdb_v2_table_function_bind_info_handle info, idx_t cardinality, bool is_exact, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the order guarantee of the rows this call of the function produces. Defaults to
* `ORDER_PRESERVATION_INSERTION_ORDER`.
*
* With `ORDER_PRESERVATION_NO_ORDER`, a scan that reports more than one thread via
* `duckdb_v2_table_function_init_global_set_max_threads()` runs in parallel into query results, INSERT and COPY without
* a `duckdb_v2_table_function_set_partition_data_callback()`, and the rows arrive in no particular order. With
* insertion order kept, those consumers need the partition data callback to run in parallel. Fails with
* `ERROR_INPUT_INVALID` when order is not one of the enum's declared values.
*
* history:
* - unstable: v2.0.0
*
* @param info The bind info handle.
* @param order The order guarantee of the produced rows.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_bind_set_order_preservation(
duckdb_v2_table_function_bind_info_handle info, DUCKDB_V2_ORDER_PRESERVATION order,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_global_get_user_data(
duckdb_v2_table_function_init_global_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_global_get_bind_data(
duckdb_v2_table_function_init_global_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's "global state" from the global init callback.
*
* The global state lives for the duration of the scan and is retrievable from the local init, exec and progress
* callbacks. Every thread scanning the function shares it, so the function must synchronize its own access to it. The
* opaque handle bundles the pointer with an optional destructor, invoked when the scan is done with the state.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param data Opaque handle bundling the global state pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_global_set_global_state(
duckdb_v2_table_function_init_global_info_handle info, duckdb_v2_opaque *data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets how many threads may scan the function in parallel.
*
* Defaults to 1, a single-threaded scan. The engine creates at most this many local states, and therefore runs at most
* this many exec callbacks concurrently. It is an upper bound, not a request: the engine may use fewer threads.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param max_threads The maximum number of threads. Must be at least 1.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_global_set_max_threads(
duckdb_v2_table_function_init_global_info_handle info, idx_t max_threads, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns the scan produces.
*
* With projection pushdown (see `duckdb_v2_table_function_set_projection_pushdown()`) this is the number of columns the
* query uses, which is the number of vectors in the exec callback's output chunk; without it, it is the number of
* columns declared in bind. Valid indices for `duckdb_v2_table_function_init_global_get_column_index()` are `0` up to
* (but excluding) this count.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param count Receives the number of columns the scan produces.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_global_get_column_count(
duckdb_v2_table_function_init_global_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns which declared column the scan's column at the given index stands for.
*
* The result indexes the columns declared with `duckdb_v2_table_function_bind_add_result_column()`, in declaration
* order: the exec callback fills the output chunk's vector at `index` with that column's data. Without projection
* pushdown the mapping is the identity. Fails if the index is out of bounds.
*
* history:
* - unstable: v2.0.0
*
* @param info The global init info handle.
* @param index The index of the column in the scan's output.
* @param column_index Receives the index of the declared column.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_global_get_column_index(
duckdb_v2_table_function_init_global_info_handle info, idx_t index, idx_t *column_index,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_local_get_user_data(
duckdb_v2_table_function_init_local_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_local_get_bind_data(
duckdb_v2_table_function_init_local_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* Shared with every other thread scanning the function; access to it must be synchronized by the function.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_local_get_global_state(
duckdb_v2_table_function_init_local_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the function's worker-local "local state" from the local init callback.
*
* The local state is associated with the executing thread for the duration of the scan and retrievable from the exec
* callback via `duckdb_v2_table_function_exec_get_local_state()`. No other thread observes it, so it needs no
* synchronization. The opaque handle bundles the pointer with an optional destructor, invoked when the local state is
* no longer needed.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param data Opaque handle bundling the local state pointer plus an optional destructor.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_local_set_local_state(
duckdb_v2_table_function_init_local_info_handle info, duckdb_v2_opaque *data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns the scan produces.
*
* With projection pushdown (see `duckdb_v2_table_function_set_projection_pushdown()`) this is the number of columns the
* query uses, which is the number of vectors in the exec callback's output chunk; without it, it is the number of
* columns declared in bind. Valid indices for `duckdb_v2_table_function_init_local_get_column_index()` are `0` up to
* (but excluding) this count.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param count Receives the number of columns the scan produces.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_init_local_get_column_count(
duckdb_v2_table_function_init_local_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns which declared column the scan's column at the given index stands for.
*
* The result indexes the columns declared with `duckdb_v2_table_function_bind_add_result_column()`, in declaration
* order: the exec callback fills the output chunk's vector at `index` with that column's data. Without projection
* pushdown the mapping is the identity. Fails if the index is out of bounds.
*
* history:
* - unstable: v2.0.0
*
* @param info The local init info handle.
* @param index The index of the column in the scan's output.
* @param column_index Receives the index of the declared column.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR
duckdb_v2_table_function_init_local_get_column_index(duckdb_v2_table_function_init_local_info_handle info, idx_t index,
idx_t *column_index, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_exec_get_user_data(duckdb_v2_table_function_exec_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_exec_get_bind_data(duckdb_v2_table_function_exec_info_handle info,
void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* Shared with every other thread scanning the function; access to it must be synchronized by the function.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_exec_get_global_state(
duckdb_v2_table_function_exec_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the worker-local local state set by the function's local init callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param data Receives the local state pointer for the executing thread, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_exec_get_local_state(
duckdb_v2_table_function_exec_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the output chunk the exec callback must write the next batch of rows into.
*
* The chunk holds one vector per column declared with `duckdb_v2_table_function_bind_add_result_column()`, in the same
* order; reach them with `duckdb_v2_data_chunk_get_vector()`. The chunk starts out empty on every invocation: write the
* rows, then declare how many there are with `duckdb_v2_vector_set_size()` on the first vector, which the engine takes
* as the batch's row count and propagates to the other vectors. Producing an empty batch signals the end of the scan,
* after which the callback is not invoked again on that thread. Borrowed; valid only for the duration of the callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param chunk Receives the borrowed output chunk to write into.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_output_chunk(duckdb_v2_table_function_exec_info_handle info,
duckdb_v2_data_chunk_handle *chunk, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns the scan produces.
*
* With projection pushdown (see `duckdb_v2_table_function_set_projection_pushdown()`) this is the number of columns the
* query uses, which is the number of vectors in the exec callback's output chunk; without it, it is the number of
* columns declared in bind. Valid indices for `duckdb_v2_table_function_exec_get_column_index()` are `0` up to (but
* excluding) this count.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param count Receives the number of columns the scan produces.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_exec_get_column_count(
duckdb_v2_table_function_exec_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns which declared column the scan's column at the given index stands for.
*
* The result indexes the columns declared with `duckdb_v2_table_function_bind_add_result_column()`, in declaration
* order: the exec callback fills the output chunk's vector at `index` with that column's data. Without projection
* pushdown the mapping is the identity. Fails if the index is out of bounds.
*
* history:
* - unstable: v2.0.0
*
* @param info The exec info handle.
* @param index The index of the column in the scan's output.
* @param column_index Receives the index of the declared column.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_exec_get_column_index(
duckdb_v2_table_function_exec_info_handle info, idx_t index, idx_t *column_index, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_progress_get_user_data(
duckdb_v2_table_function_progress_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_progress_get_bind_data(
duckdb_v2_table_function_progress_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* The progress callback runs concurrently with the exec callbacks scanning the function, so it must read the global
* state in a thread-safe way.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_progress_get_global_state(
duckdb_v2_table_function_progress_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports how far the scan has advanced.
*
* A fraction between 0.0 (nothing scanned yet) and 1.0 (done); values outside that range are clamped. A progress
* callback that returns without calling this reports no progress.
*
* history:
* - unstable: v2.0.0
*
* @param info The progress info handle.
* @param progress The fraction of the scan that is complete, in [0.0, 1.0].
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_progress_set_progress(
duckdb_v2_table_function_progress_info_handle info, double progress, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`, or null if none was set.
*
* history:
* - unstable: v2.0.0
*
* @param info The filter pushdown info handle.
* @param data Receives the user data pointer.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_filter_pushdown_get_user_data(
duckdb_v2_table_function_filter_pushdown_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set via `duckdb_v2_function_bind_set_bind_data()`, or null if none was set.
*
* This is the same object the init and exec callbacks later receive, so a predicate the callback accepts can be
* recorded in it for the scan to apply.
*
* history:
* - unstable: v2.0.0
*
* @param info The filter pushdown info handle.
* @param data Receives the bind data pointer.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_filter_pushdown_get_bind_data(
duckdb_v2_table_function_filter_pushdown_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of filter predicates offered to the function.
*
* The predicates are combined with `AND`: every row the scan produces must satisfy all of them. Valid indices for
* `duckdb_v2_table_function_filter_pushdown_get_filter()` and `duckdb_v2_table_function_filter_pushdown_accept()` are
* `0` up to (but excluding) this count.
*
* history:
* - unstable: v2.0.0
*
* @param info The filter pushdown info handle.
* @param count Receives the number of predicates.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_filter_pushdown_get_filter_count(
duckdb_v2_table_function_filter_pushdown_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the filter predicate at the given index.
*
* Fails if the index is out of bounds. The predicate is a bound expression evaluating to `BOOLEAN`; inspect it with
* `duckdb_v2_expression_get_type()` and the other `expression` functions, and resolve the column references it contains
* via `duckdb_v2_table_function_filter_pushdown_get_column_index()`. Borrowed; valid only for the duration of the
* callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The filter pushdown info handle.
* @param index The index of the predicate to retrieve.
* @param filter Receives the borrowed predicate.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_filter_pushdown_get_filter(
duckdb_v2_table_function_filter_pushdown_info_handle info, idx_t index, duckdb_v2_expression_handle *filter,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Accepts the filter predicate at the given index: the function will apply it itself.
*
* The engine stops applying an accepted predicate, so the scan must produce only rows that satisfy it, or the query
* returns rows it should not. Predicates left unaccepted are applied by the engine as usual, so a callback that
* recognizes nothing can simply return. Fails if the index is out of bounds.
*
* history:
* - unstable: v2.0.0
*
* @param info The filter pushdown info handle.
* @param index The index of the predicate to accept.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_filter_pushdown_accept(
duckdb_v2_table_function_filter_pushdown_info_handle info, idx_t index, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns the predicates can refer to.
*
* A column reference inside a predicate (`duckdb_v2_expression_column_ref_get_index()`) indexes the columns the query
* reads from the function, not the columns declared in bind. Valid indices for
* `duckdb_v2_table_function_filter_pushdown_get_column_index()` are `0` up to (but excluding) this count.
*
* history:
* - unstable: v2.0.0
*
* @param info The filter pushdown info handle.
* @param count Receives the number of referable columns.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_filter_pushdown_get_column_count(
duckdb_v2_table_function_filter_pushdown_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Resolves a column reference found in a predicate to the declared column it refers to.
*
* Takes the index a `EXPRESSION_TYPE_BOUND_COLUMN_REF` node reports and returns the index of the column among the ones
* declared with `duckdb_v2_table_function_bind_add_result_column()`, in declaration order. Fails if the index is out of
* bounds.
*
* history:
* - unstable: v2.0.0
*
* @param info The filter pushdown info handle.
* @param index The column index reported by a column reference node.
* @param column_index Receives the index of the declared column.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_filter_pushdown_get_column_index(
duckdb_v2_table_function_filter_pushdown_info_handle info, idx_t index, idx_t *column_index,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_get_user_data(
duckdb_v2_table_function_partition_data_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_get_bind_data(
duckdb_v2_table_function_partition_data_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* Shared with every other thread scanning the function; access to it must be synchronized by the function.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_get_global_state(
duckdb_v2_table_function_partition_data_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the worker-local local state set by the function's local init callback, for the thread that produced the
* batch this call reports on. No other thread observes it, so it needs no synchronization.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param data Receives the local state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_get_local_state(
duckdb_v2_table_function_partition_data_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns whether a downstream operator needs this batch's ordering position.
*
* `duckdb_v2_table_function_partition_data_set_batch_index()` must still be called even when this is false: the engine
* validates the reported value regardless of whether it is actually used for ordering, so `0` is always a safe answer
* when this reports false.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param required Receives whether a batch index is required.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_requires_batch_index(
duckdb_v2_table_function_partition_data_info_handle info, bool *required, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns whether a downstream operator needs this batch's values for a set of partitioning columns.
*
* When true, call `duckdb_v2_table_function_partition_data_set_partition_value()` once for every index in `[0, count)`,
* where `count` comes from `duckdb_v2_table_function_partition_data_get_partition_column_count()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param required Receives whether partitioning column values are required.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_requires_partition_columns(
duckdb_v2_table_function_partition_data_info_handle info, bool *required, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of partitioning columns a downstream operator is requesting values for.
*
* `0` when `duckdb_v2_table_function_partition_data_requires_partition_columns()` is false. Valid indices for
* `duckdb_v2_table_function_partition_data_get_partition_column_index()` and
* `duckdb_v2_table_function_partition_data_set_partition_value()` are `0` up to (but excluding) this count.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param count Receives the number of requested partitioning columns.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_get_partition_column_count(
duckdb_v2_table_function_partition_data_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns which declared column the requested partitioning column at the given index stands for.
*
* The result indexes the columns declared with `duckdb_v2_table_function_bind_add_result_column()`, in declaration
* order. Fails if the index is out of bounds.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param index The index of the requested partitioning column.
* @param column_index Receives the index of the declared column.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_get_partition_column_index(
duckdb_v2_table_function_partition_data_info_handle info, idx_t index, idx_t *column_index,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports the ordering position of the batch the exec callback just produced.
*
* Required on every call, whether or not `duckdb_v2_table_function_partition_data_requires_batch_index()` is true: the
* engine validates the reported value regardless. Not calling this before the callback returns fails the query; `0` is
* always a safe answer when the batch index is not actually required. Must not decrease across successive calls on the
* same thread, must be unique across threads for the ordering to be meaningful, must be less than roughly `10^13`, and,
* when partitioning column values are also being reported, must change whenever those values change: the engine only
* re-reads them when the batch index changes, so reporting a new value under an unchanged batch index is treated as a
* caller error rather than applied. Fails with `ERROR_INPUT_INVALID` for an out-of-range value; a decreasing value or
* an unchanged value paired with changed partitioning columns fails the query once the callback returns.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param batch_index The batch's ordering position.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_set_batch_index(
duckdb_v2_table_function_partition_data_info_handle info, idx_t batch_index, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports the single value of the partitioning column at the given index, for the batch the exec callback just
* produced.
*
* Every partition reported this way carries exactly one distinct value for the column, so the value serves as both the
* minimum and maximum of the partition's range. The value is borrowed and copied, and must be of the declared type of
* the corresponding result column. Required once for every index in `[0,
* `duckdb_v2_table_function_partition_data_get_partition_column_count()`)` before the callback returns; calling it
* again for the same index overwrites the previous value. The reported value only takes effect together with a changed
* `duckdb_v2_table_function_partition_data_set_batch_index()`: reporting a different value under an unchanged batch
* index fails the query once the callback returns. Fails with `ERROR_INPUT_INVALID` when the index is out of bounds or
* the value's type does not match.
*
* history:
* - unstable: v2.0.0
*
* @param info The partition data info handle.
* @param index The index of the partitioning column being reported.
* @param value The single value of the partitioning column. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partition_data_set_partition_value(
duckdb_v2_table_function_partition_data_info_handle info, idx_t index, duckdb_v2_value_handle value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The partitioning info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partitioning_get_user_data(
duckdb_v2_table_function_partitioning_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The partitioning info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partitioning_get_bind_data(
duckdb_v2_table_function_partitioning_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of columns the optimizer is asking about: the candidate `GROUP BY` column set.
*
* Valid indices for `duckdb_v2_table_function_partitioning_get_partition_column_index()` are `0` up to (but excluding)
* this count.
*
* history:
* - unstable: v2.0.0
*
* @param info The partitioning info handle.
* @param count Receives the number of columns in the candidate set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partitioning_get_partition_column_count(
duckdb_v2_table_function_partitioning_info_handle info, idx_t *count, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns which declared column the candidate `GROUP BY` column at the given index stands for.
*
* The result indexes the columns declared with `duckdb_v2_table_function_bind_add_result_column()`, in declaration
* order. Fails if the index is out of bounds.
*
* history:
* - unstable: v2.0.0
*
* @param info The partitioning info handle.
* @param index The index of the candidate column.
* @param column_index Receives the index of the declared column.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partitioning_get_partition_column_index(
duckdb_v2_table_function_partitioning_info_handle info, idx_t index, idx_t *column_index,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports whether every partition the scan produces carries exactly one distinct value for the candidate `GROUP BY`
* column set.
*
* Only `TABLE_PARTITION_INFO_SINGLE_VALUE_PARTITIONS` unlocks the partitioned aggregate optimization; any other value
* keeps the regular hash aggregate. A callback that never calls this is treated as reporting
* `TABLE_PARTITION_INFO_NOT_PARTITIONED`. Fails with `ERROR_INPUT_INVALID` when partition_info is not one of the enum's
* declared values.
*
* history:
* - unstable: v2.0.0
*
* @param info The partitioning info handle.
* @param partition_info Whether, and how, the scan is partitioned by the candidate column set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_partitioning_set_partition_info(
duckdb_v2_table_function_partitioning_info_handle info, DUCKDB_V2_TABLE_PARTITION_INFO partition_info,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the table function, making it available for use in SQL queries.
*
* The function is registered on the connection's database, visible to every connection, in the connection's
* transaction: inside an explicit transaction, it is invisible to other connections until the transaction commits, and
* a rollback undoes it. Registration requires a name, a bind callback and an exec callback, and rejects a signature
* that declares a return type, since a table function declares the columns it returns from its bind callback. The table
* function must have been created through a factory of the same database. The caller still owns the handle after
* registration and must destroy it with `duckdb_v2_table_function_destroy()`, which does not affect the registered
* function.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param function The table function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_table_function(duckdb_v2_connection_handle conn,
duckdb_v2_table_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the table function, making it available for use in SQL queries.
*
* The function is registered on the loading extension's database and attributed to the extension. Use this from the
* extension's load callback. Registration requires a name, a bind callback and an exec callback, and rejects a
* signature that declares a return type, since a table function declares the columns it returns from its bind callback.
* The table function must have been created through a factory of the same database. The caller still owns the handle
* after registration and must destroy it with `duckdb_v2_table_function_destroy()`, which does not affect the
* registered function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The table function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_table_function(duckdb_v2_extension_handle extension,
duckdb_v2_table_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the table function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_destroy(duckdb_v2_table_function_handle *function);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional claim batch callback of the table function.
*
* With a claim batch callback, a scanning thread works through the scan one batch at a time: the callback claims the
* next batch of work (e.g. the next block of a file) for the thread's local state, typically from the shared global
* state, and the exec callback then produces the rows of that batch only, leaving the output chunk empty once the batch
* is exhausted. A batch is claimed before the exec callback first runs on a thread, and again whenever the exec
* callback leaves the output chunk empty; the scan ends for a thread once the claim batch callback does not claim a
* batch.
*
* Telling the batches apart lets a caller that scans several batches in parallel put their rows back in the order of
* the batches, e.g. a multi-file function registered with `duckdb_v2_connection_register_multi_file_function()` or
* `duckdb_v2_extension_register_multi_file_function()` claims the batches of the function itself, so that the rows of a
* file keep their order also when several threads scan it.
*
* The callback runs while the work of the scan is handed out to the threads, possibly while every other scanning thread
* waits for it. It should therefore only claim the work - e.g. reserve the number of the next block - and leave reading
* it to the exec callback.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the claim batch callback of.
* @param callback The claim batch callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_claim_batch_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_claim_batch_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set on the table function via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The claim batch info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_claim_batch_get_user_data(
duckdb_v2_table_function_claim_batch_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data set by the function's bind callback.
*
* history:
* - unstable: v2.0.0
*
* @param info The claim batch info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_claim_batch_get_bind_data(
duckdb_v2_table_function_claim_batch_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the global state set by the function's global init callback.
*
* Shared with every other thread scanning the function; access to it must be synchronized by the function.
*
* history:
* - unstable: v2.0.0
*
* @param info The claim batch info handle.
* @param data Receives the global state pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_claim_batch_get_global_state(
duckdb_v2_table_function_claim_batch_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the local state set by the function's local init callback, for the thread claiming a batch.
*
* history:
* - unstable: v2.0.0
*
* @param info The claim batch info handle.
* @param data Receives the local state pointer for the claiming thread, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_claim_batch_get_local_state(
duckdb_v2_table_function_claim_batch_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Reports whether the callback claimed a batch for the thread.
*
* A callback that returns without calling this claimed nothing, which ends the scan for the thread.
*
* history:
* - unstable: v2.0.0
*
* @param info The claim batch info handle.
* @param claimed Whether a batch was claimed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_claim_batch_set_claimed(
duckdb_v2_table_function_claim_batch_info_handle info, bool claimed, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the optional "get bind info" callback of the table function.
*
* The engine invokes the callback with the bind data of a bound call when it needs to know more about the call than its
* columns. E.g. a multi-file function registered with `duckdb_v2_connection_register_multi_file_function()` or
* `duckdb_v2_extension_register_multi_file_function()` asks the function it wraps for every file it binds: it maps the
* columns of the files onto the columns of its scan by the identifiers the callback reports, and exposes the options it
* reports as the metadata of the reader of the file. The callback may be invoked more than once for the same bind data,
* so it should only report what the bind already determined.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the callback of.
* @param callback The "get bind info" callback to set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_set_get_bind_info_callback(
duckdb_v2_table_function_handle function, duckdb_v2_table_function_get_bind_info_callback_fn callback,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the user data set via `duckdb_v2_table_function_set_user_data()`.
*
* history:
* - unstable: v2.0.0
*
* @param info The get bind info handle.
* @param data Receives the user data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_get_bind_info_get_user_data(
duckdb_v2_table_function_get_bind_info_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Retrieves the bind data the function's bind callback set for the bound call being described.
*
* history:
* - unstable: v2.0.0
*
* @param info The get bind info handle.
* @param data Receives the bind data pointer, or null if none was set.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_get_bind_info_get_bind_data(
duckdb_v2_table_function_get_bind_info_info_handle info, void **data, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Attaches an identifier to a result column of the bound call, or to a field nested inside one.
*
* A multi-file reader can then map the columns of every file onto the columns of its scan by identifier rather than by
* name - e.g. by the field ids of a file format that carries them, so that renamed columns and fields are still found.
* An identifier is an INTEGER field id or a VARCHAR name.
*
* The nested field is addressed by a path of child indexes, starting at the result column at `column_index`: a STRUCT
* field by its index, the elements of a LIST or ARRAY by `0`, the keys of a MAP by `0` and its values by `1`, and a
* UNION member by its index. An empty path addresses the result column itself. Setting an identifier again for the same
* column or field replaces it. Fails with `ERROR_INPUT_INVALID` when the column index is out of range, or the path does
* not address a nested field of the column's type.
*
* history:
* - unstable: v2.0.0
*
* @param info The get bind info handle.
* @param column_index The index of the result column, in the order the bind callback declared the columns.
* @param child_path The path of child indexes addressing the nested field, or null for the column itself.
* @param child_path_length The number of entries in the path, 0 for the column itself.
* @param identifier The identifier, an INTEGER or VARCHAR value. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_get_bind_info_set_column_identifier(
duckdb_v2_table_function_get_bind_info_info_handle info, idx_t column_index, const idx_t *child_path,
idx_t child_path_length, duckdb_v2_value_handle identifier, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets an option describing the bound call: a key-value fact about what the call reads, e.g. a property of the file it
* reads. Setting a key again replaces its value.
*
* A multi-file function registered with `duckdb_v2_connection_register_multi_file_function()` or
* `duckdb_v2_extension_register_multi_file_function()` exposes the options of the function it wraps as the metadata of
* the reader of each file, e.g. to a custom multi-file reader of another extension.
*
* history:
* - unstable: v2.0.0
*
* @param info The get bind info handle.
* @param key The key of the option. Borrowed and copied.
* @param value The value of the option. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_table_function_get_bind_info_set_option(
duckdb_v2_table_function_get_bind_info_info_handle info, duckdb_v2_str *key, duckdb_v2_value_handle value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a new multi-file function through a factory.
*
* The function starts out empty: give it a name with `duckdb_v2_multi_file_function_set_name()` and the single-file
* function it wraps with `duckdb_v2_multi_file_function_set_single_file_function()`, then make it available with
* `duckdb_v2_connection_register_multi_file_function()` or `duckdb_v2_extension_register_multi_file_function()`. The
* caller owns the returned handle and must destroy it with `duckdb_v2_multi_file_function_destroy()`, also after
* registration.
*
* The multi-file function can only be registered on the database the factory belongs to.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create the multi-file function through.
* @param function On success, receives the newly created multi-file function. Owned by the caller.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_multi_file_function_create(duckdb_v2_factory_handle factory,
duckdb_v2_multi_file_function_handle *function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the multi-file function, as SQL will call it.
*
* The name is borrowed and copied. Calling this again replaces the previous name. A name must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the name of.
* @param name The name to set. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_multi_file_function_set_name(duckdb_v2_multi_file_function_handle function,
duckdb_v2_str *name,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the name of the table function that reads a single file, which the multi-file function wraps.
*
* The single-file function must be registered before the multi-file function is, and must take the file to read as its
* only positional parameter, of type ANY. It is bound once for every file that is read, and receives the file the way a
* multi-file function takes one: as the VARCHAR path of the file when there is nothing more to know about it, and
* otherwise as a STRUCT holding the path in its `filename` field and the options to open the file with in its other
* fields - e.g. the size of the file, as a file system reported it while globbing, or the options a caller passed along
* with the file (`read_x([{'filename': 'f.x', 'file_size': 42}])`). Opening the file with those options, set with
* `duckdb_v2_file_open_options_set_value()`, lets the file system skip work it would otherwise repeat, such as asking a
* remote store for the size of the file. A single-file function that takes a VARCHAR parameter instead is still
* accepted, and only receives the path. Every named parameter the single-file function declares is also a named
* parameter of the multi-file function, forwarded to it as given. Everything that involves several files - globbing,
* lists of files, hive partitioning, the `filename` column, `union_by_name` and the like - is provided by the
* multi-file function on top of it. The name is borrowed and copied. A single-file function must be set before
* registration.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the single-file function of.
* @param name The name of the registered single-file table function. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_multi_file_function_set_single_file_function(
duckdb_v2_multi_file_function_handle function, duckdb_v2_str *name, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets how the files the function reads are referred to in messages, e.g. "Avro" or "JSON".
*
* Optional: without it, the files are referred to by the name of the multi-file function. The name is borrowed and
* copied.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the reader type of.
* @param reader_type The reader type. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_multi_file_function_set_reader_type(
duckdb_v2_multi_file_function_handle function, duckdb_v2_str *reader_type, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Sets the file extension of the files the function reads, e.g. "avro".
*
* Optional. With a file extension, a path that names a directory rather than a file reads the files with that extension
* inside it. Without one, the paths passed to the function must match at least one file. The extension is given without
* a leading dot, and is borrowed and copied.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to set the file extension of.
* @param extension The file extension, without a leading dot. Borrowed and copied.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_multi_file_function_set_file_extension(
duckdb_v2_multi_file_function_handle function, duckdb_v2_str *extension, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the multi-file function, making it available for use in SQL queries.
*
* The function is registered on the connection's database, visible to every connection, in the connection's
* transaction: inside an explicit transaction, it is invisible to other connections until the transaction commits, and
* a rollback undoes it. It can then be called with the path of a single file, a glob pattern, or a list of either, and
* accepts the options every multi-file function accepts (e.g. `filename`, `hive_partitioning`, `union_by_name`) next to
* the named parameters of the single-file function. Registration requires a name and a single-file function, and fails
* when no table function by that name is registered or it does not take the path of the file to read as its only
* positional parameter (see `duckdb_v2_multi_file_function_set_single_file_function()`). The multi-file function must
* have been created through a factory of the same database. The caller still owns the handle after registration and
* must destroy it with `duckdb_v2_multi_file_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to register on.
* @param function The multi-file function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_connection_register_multi_file_function(
duckdb_v2_connection_handle conn, duckdb_v2_multi_file_function_handle function, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Registers the multi-file function, making it available for use in SQL queries.
*
* The function is registered on the loading extension's database and attributed to the extension. Use this from the
* extension's load callback. It can then be called with the path of a single file, a glob pattern, or a list of either,
* and accepts the options every multi-file function accepts (e.g. `filename`, `hive_partitioning`, `union_by_name`)
* next to the named parameters of the single-file function. Registration requires a name and a single-file function,
* and fails when no table function by that name is registered or it does not take the path of the file to read as its
* only positional parameter (see `duckdb_v2_multi_file_function_set_single_file_function()`). The multi-file function
* must have been created through a factory of the same database. The caller still owns the handle after registration
* and must destroy it with `duckdb_v2_multi_file_function_destroy()`, which does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param extension The loading extension.
* @param function The multi-file function to register.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_extension_register_multi_file_function(
duckdb_v2_extension_handle extension, duckdb_v2_multi_file_function_handle function,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the multi-file function, releasing its resources.
*
* Null-safe: passing a null pointer or null handle is a no-op. The handle is set to null on return to prevent
* double-destruction. Destroying the handle after registration does not affect the registered function.
*
* history:
* - unstable: v2.0.0
*
* @param function The function to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_multi_file_function_destroy(duckdb_v2_multi_file_function_handle *function);
#endif
/* --- Struct definitions for table --- */
/* ============================================================================
* MODULE: value
* ============================================================================ */
/* --- Enums for value --- */
/* --- Struct forward declarations for value --- */
/* --- Types for value --- */
/* --- Constants for value --- */
/* --- Function pointer typedefs for value --- */
/* --- Functions for value --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys a value handle.
*
* Null-safe: passing nullptr or a slot already set to nullptr is a no-op. On success the slot is set to nullptr.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_destroy(duckdb_v2_value_handle *value);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a BOOLEAN.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a bool.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_bool(duckdb_v2_value_handle value, bool *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a UTINYINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a uint8_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_utinyint(duckdb_v2_value_handle value, uint8_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a USMALLINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a uint16_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_usmallint(duckdb_v2_value_handle value, uint16_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a UINTEGER.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a uint32_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_uint(duckdb_v2_value_handle value, uint32_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a UBIGINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a uint64_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_ubigint(duckdb_v2_value_handle value, uint64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a UHUGEINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a uint128_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_uhugeint(duckdb_v2_value_handle value, duckdb_v2_uhugeint_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TINYINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as an int8_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_tinyint(duckdb_v2_value_handle value, int8_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a SMALLINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as an int16_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_smallint(duckdb_v2_value_handle value, int16_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as an INTEGER.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as an int32_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_int(duckdb_v2_value_handle value, int32_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a BIGINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as an int64_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_bigint(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a HUGEINT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as an int128_t.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_hugeint(duckdb_v2_value_handle value, duckdb_v2_hugeint_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a VARCHAR.
*
* The string is borrowed from the value and stays valid until the value is destroyed. That borrow is why this getter
* does not convert: a converted copy would not outlive the call. A value of any other type id, and a NULL value, return
* ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a UTF-8 string. The returned string is borrowed and valid until the value handle
* is destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_varchar(duckdb_v2_value_handle value, duckdb_v2_str *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a byte string: a BLOB, or the storage bytes of a BIT or BIGNUM.
*
* The string is borrowed from the value and stays valid until the value is destroyed. That borrow is why this getter
* does not convert: a converted copy would not outlive the call. A value of any other type id, and a NULL value, return
* ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a byte string. The returned string is borrowed and valid until the value handle is
* destroyed.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_blob(duckdb_v2_value_handle value, duckdb_v2_str *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a FLOAT.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a float.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_float(duckdb_v2_value_handle value, float *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a DOUBLE.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload as a double.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_double(duckdb_v2_value_handle value, double *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a DATE.
*
* The payload is days since 1970-01-01, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_date(duckdb_v2_value_handle value, int32_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIME.
*
* The payload is microseconds since midnight, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_time(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIME_NS.
*
* The payload is nanoseconds since midnight, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_time_ns(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIME_TZ.
*
* The payload packs the time of day and the UTC offset into one integer, in the committed layout: micros in the high 40
* bits, a biased offset in the low 24. The same form a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_time_tz(duckdb_v2_value_handle value, uint64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIMESTAMP.
*
* The payload is microseconds since 1970-01-01, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIMESTAMP_SEC.
*
* The payload is seconds since 1970-01-01, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_sec(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIMESTAMP_MS.
*
* The payload is milliseconds since 1970-01-01, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_ms(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIMESTAMP_NS.
*
* The payload is nanoseconds since 1970-01-01, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_ns(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIMESTAMP_TZ.
*
* The payload is microseconds since 1970-01-01, in UTC, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_tz(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a TIMESTAMP_TZ_NS.
*
* The payload is nanoseconds since 1970-01-01, in UTC, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_tz_ns(duckdb_v2_value_handle value, int64_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as an INTERVAL.
*
* The payload is the (months, days, micros) triple, the same unit a vector of this type exposes.
*
* A value of a different type is converted through the default cast set, on a copy, so reading never alters the value.
* An unsupported conversion returns ERROR_INPUT_INVALID, as does a NULL value.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the payload.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_interval(duckdb_v2_value_handle value, duckdb_v2_interval_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a UUID, in its internal 128-bit form.
*
* The dual of value_create_uuid: the storage form a vector element holds, with the high bit flipped so the integer
* sorts, rather than the canonical byte order. A value of any other type id, and a NULL value, return
* ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the internal 128-bit storage form.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_uuid(duckdb_v2_value_handle value, duckdb_v2_hugeint_t *out,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the value as a DECIMAL: its backing integer plus the width and scale of its type.
*
* The integer is the value scaled by 10^scale — the dual of value_create_decimal — widened to 128 bits from whatever
* storage tier the width selects. The integer getters convert, so a DECIMAL read through value_get_bigint is its
* numeric value with the fraction dropped; this one always reports storage instead, together with the scale needed to
* interpret it. A value of any other type id, and a NULL value, return ERROR_INPUT_INVALID.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out Receives the backing integer, scaled by 10^scale.
* @param out_width Receives the total digit count of the value's type.
* @param out_scale Receives the digits after the decimal point.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_decimal(duckdb_v2_value_handle value, duckdb_v2_hugeint_t *out,
uint8_t *out_width, uint8_t *out_scale,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Unwraps the logical type carried by a TYPE value.
*
* Returns ERROR_INPUT_INVALID unless the value is a non-NULL TYPE value. The returned logical type is caller-owned and
* must be destroyed via logical_type_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out_type Receives the owned logical type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_type(duckdb_v2_value_handle value,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a NULL value of the given logical type.
*
* The logical type is borrowed and copied into the value, so the caller can destroy it independently.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param type The borrowed logical type to attach to the NULL value.
* @param out_value Receives the new NULL value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_null(duckdb_v2_factory_handle factory,
duckdb_v2_logical_type_handle type,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a BOOLEAN value from a bool.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The bool to wrap.
* @param out_value Receives the new BOOLEAN value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_bool(duckdb_v2_factory_handle factory, bool in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a UTINYINT value from a uint8_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The uint8_t to wrap.
* @param out_value Receives the new UTINYINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_utinyint(duckdb_v2_factory_handle factory, uint8_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a USMALLINT value from a uint16_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The uint16_t to wrap.
* @param out_value Receives the new USMALLINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_usmallint(duckdb_v2_factory_handle factory, uint16_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a UINTEGER value from a uint32_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The uint32_t to wrap.
* @param out_value Receives the new UINTEGER value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_uint(duckdb_v2_factory_handle factory, uint32_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a UBIGINT value from a uint64_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The uint64_t to wrap.
* @param out_value Receives the new UBIGINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_ubigint(duckdb_v2_factory_handle factory, uint64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a UHUGEINT value from a uint128_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The uint128_t to wrap.
* @param out_value Receives the new UHUGEINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_uhugeint(duckdb_v2_factory_handle factory,
const duckdb_v2_uhugeint_t *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TINYINT value from an int8_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The int8_t to wrap.
* @param out_value Receives the new TINYINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_tinyint(duckdb_v2_factory_handle factory, int8_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a SMALLINT value from an int16_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The int16_t to wrap.
* @param out_value Receives the new SMALLINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_smallint(duckdb_v2_factory_handle factory, int16_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an INTEGER value from an int32_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The int32_t to wrap.
* @param out_value Receives the new INTEGER value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_int(duckdb_v2_factory_handle factory, int32_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a BIGINT value from an int64_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The int64_t to wrap.
* @param out_value Receives the new BIGINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_bigint(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a HUGEINT value from an int128_t.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The int128_t to wrap.
* @param out_value Receives the new HUGEINT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_hugeint(duckdb_v2_factory_handle factory,
const duckdb_v2_hugeint_t *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a VARCHAR value from a UTF-8 string.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The UTF-8 string to wrap. May be null only when len is 0 (empty string).
* @param out_value Receives the new VARCHAR value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_varchar(duckdb_v2_factory_handle factory,
const duckdb_v2_str *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a BLOB value from a byte string.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The byte string to wrap. May be null only when len is 0 (empty string).
* @param out_value Receives the new BLOB value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_blob(duckdb_v2_factory_handle factory,
const duckdb_v2_str *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a FLOAT value from a float.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The float to wrap.
* @param out_value Receives the new FLOAT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_float(duckdb_v2_factory_handle factory, float in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a DOUBLE value from a double.
*
* The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The double to wrap.
* @param out_value Receives the new DOUBLE value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_double(duckdb_v2_factory_handle factory, double in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TYPE value from a logical type.
*
* The logical type is borrowed and copied into the value, so the caller can destroy it independently.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_type The borrowed logical type to wrap.
* @param out_value Receives the new TYPE value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_type(duckdb_v2_factory_handle factory,
duckdb_v2_logical_type_handle in_type,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a DATE value.
*
* The payload is days since 1970-01-01, the same unit value_get_date reports. It is not range-checked here; value_cast
* is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new DATE value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_date(duckdb_v2_factory_handle factory, int32_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIME value.
*
* The payload is microseconds since midnight, the same unit value_get_time reports. It is not range-checked here;
* value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIME value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_time(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIME_NS value.
*
* The payload is nanoseconds since midnight, the same unit value_get_time_ns reports. It is not range-checked here;
* value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIME_NS value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_time_ns(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIME_TZ value.
*
* The payload packs the time of day and the UTC offset into one integer, in the committed layout: micros in the high 40
* bits, a biased offset in the low 24. The same form value_get_time_tz reports. It is not range-checked here;
* value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIME_TZ value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_time_tz(duckdb_v2_factory_handle factory, uint64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIMESTAMP value.
*
* The payload is microseconds since 1970-01-01, the same unit value_get_timestamp reports. It is not range-checked
* here; value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIMESTAMP value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_timestamp(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIMESTAMP_SEC value.
*
* The payload is seconds since 1970-01-01, the same unit value_get_timestamp_sec reports. It is not range-checked here;
* value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIMESTAMP_SEC value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_timestamp_sec(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIMESTAMP_MS value.
*
* The payload is milliseconds since 1970-01-01, the same unit value_get_timestamp_ms reports. It is not range-checked
* here; value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIMESTAMP_MS value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_timestamp_ms(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIMESTAMP_NS value.
*
* The payload is nanoseconds since 1970-01-01, the same unit value_get_timestamp_ns reports. It is not range-checked
* here; value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIMESTAMP_NS value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_timestamp_ns(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIMESTAMP_TZ value.
*
* The payload is microseconds since 1970-01-01, in UTC, the same unit value_get_timestamp_tz reports. It is not
* range-checked here; value_cast is the validating path. The returned value is caller-owned; destroy it via
* value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIMESTAMP_TZ value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_timestamp_tz(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TIMESTAMP_TZ_NS value.
*
* The payload is nanoseconds since 1970-01-01, in UTC, the same unit value_get_timestamp_tz_ns reports. It is not
* range-checked here; value_cast is the validating path. The returned value is caller-owned; destroy it via
* value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new TIMESTAMP_TZ_NS value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_timestamp_tz_ns(duckdb_v2_factory_handle factory, int64_t in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a INTERVAL value.
*
* The payload is the (months, days, micros) triple, the same unit value_get_interval reports. It is not range-checked
* here; value_cast is the validating path. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The payload to wrap.
* @param out_value Receives the new INTERVAL value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_interval(duckdb_v2_factory_handle factory,
const duckdb_v2_interval_t *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a DECIMAL value from its backing integer.
*
* The value is scaled by 10^scale, so (18500, 18, 3) is 18.500. width is the total digit count and must be 1..38; scale
* is the number of digits after the point and must not exceed width. Violating either returns ERROR_INPUT_INVALID, as
* does a value too wide for the storage tier the width selects. The value itself is not range-checked against the
* width; value_cast is the validating path.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The backing integer, scaled by 10^scale.
* @param width Total digit count, 1..38.
* @param scale Digits after the decimal point; must not exceed width.
* @param out_value Receives the new DECIMAL value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_decimal(duckdb_v2_factory_handle factory,
const duckdb_v2_hugeint_t *in_value, uint8_t width,
uint8_t scale, duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a UUID value from its internal 128-bit form.
*
* The payload is the storage form a vector element holds, not the canonical byte order: the high bit is flipped so the
* integer sorts. To build one from canonical text, cast a VARCHAR with value_cast instead, which is also how a UUID
* renders back.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The internal 128-bit storage form.
* @param out_value Receives the new UUID value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_uuid(duckdb_v2_factory_handle factory,
const duckdb_v2_hugeint_t *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a BIT value from its wire bytes.
*
* The wire form is a mandatory padding-header byte — the count of leading bits in the first data byte that are not part
* of the bit string — followed by the data bytes, so the input must be at least 1 byte. These are the same bytes
* value_get_blob reports back.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The wire bytes, a padding header byte followed by data. Must be at least 1 byte.
* @param out_value Receives the new BIT value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_bit(duckdb_v2_factory_handle factory, const duckdb_v2_str *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a BIGNUM value from its storage bytes.
*
* The bytes are opaque storage, as produced by bignum_encode from a magnitude and a sign flag; a negative is stored
* bit-inverted behind a header, so these are not the magnitude bytes. The header plus at least one magnitude byte means
* the input must exceed 3 bytes. These are the same bytes value_get_blob reports back, for bignum_decode to translate.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param in_value The opaque storage bytes from bignum_encode. Must exceed 3 bytes.
* @param out_value Receives the new BIGNUM value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_bignum(duckdb_v2_factory_handle factory,
const duckdb_v2_str *in_value,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a LIST value from its elements.
*
* The child type is the common type of the elements, resolved by the same rule a SQL list literal follows, and every
* element is cast to it; a set with no common type surfaces the cast error. Pass child_type to name the type instead,
* which is also how an empty list is built: with child_type NULL, an empty element array has no type to resolve and
* returns ERROR_INPUT_INVALID.
*
* The elements are borrowed and copied in, and a NULL element becomes a typed NULL. The type is rebuilt from its child,
* so an alias on the outer LIST type is not preserved; value_cast is the alias-preserving path.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param child_type Optional. The element type. Pass NULL to resolve it from the elements.
* @param children An array of child_count elements. Borrowed (copied in). Pass NULL when child_count is 0.
* @param child_count The number of elements.
* @param out_value Receives the new composite value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_list(duckdb_v2_factory_handle factory,
duckdb_v2_logical_type_handle child_type,
const duckdb_v2_value_handle *children, idx_t child_count,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an ARRAY value from its elements, sized by their count.
*
* The child type is resolved exactly as for value_create_list, and child_type names it explicitly the same way. The
* minimum array size is 1, so an empty element array returns ERROR_INPUT_INVALID whether or not child_type is given.
*
* The elements are borrowed and copied in, and a NULL element becomes a typed NULL.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param child_type Optional. The element type. Pass NULL to resolve it from the elements.
* @param children An array of child_count elements. Borrowed (copied in). Pass NULL when child_count is 0.
* @param child_count The number of elements.
* @param out_value Receives the new composite value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_array(duckdb_v2_factory_handle factory,
duckdb_v2_logical_type_handle child_type,
const duckdb_v2_value_handle *children, idx_t child_count,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a STRUCT value from named fields, in order.
*
* Each field keeps its own child's type, so there is nothing to resolve across them; names and children are parallel
* arrays of field_count entries. An empty field list builds the empty struct, which is a real type.
*
* The names and children are borrowed and copied in, and a NULL child becomes a typed NULL. Duplicate field names are
* rejected.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param names An array of field_count field names. Pass NULL when field_count is 0.
* @param children An array of field_count field values. Borrowed (copied in). Pass NULL when field_count is 0.
* @param field_count The number of fields.
* @param out_value Receives the new composite value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_struct(duckdb_v2_factory_handle factory,
const duckdb_v2_identifier_t *names,
const duckdb_v2_value_handle *children, idx_t field_count,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a TUPLE value from positional fields.
*
* TUPLE is the unnamed struct: the same positional children as value_create_struct, under a distinct type id and with
* no names. Each field keeps its own child's type. An empty field list builds the empty tuple, which is a real type.
*
* The children are borrowed and copied in, and a NULL child becomes a typed NULL.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param children An array of field_count field values. Borrowed (copied in). Pass NULL when field_count is 0.
* @param field_count The number of fields.
* @param out_value Receives the new composite value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_tuple(duckdb_v2_factory_handle factory,
const duckdb_v2_value_handle *children, idx_t field_count,
duckdb_v2_value_handle *out_value,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates a MAP value from parallel key and value arrays.
*
* The key and value types are the common types of the keys and of the values, resolved as for value_create_list, and
* every entry is cast to them. Pass key_type and value_type to name them instead, which is also how an empty map is
* built: with both NULL, empty key and value arrays have no types to resolve and return ERROR_INPUT_INVALID.
*
* Keys and values are borrowed and copied in, and the two arrays must be the same length. Keys must be non-NULL and
* unique; both are enforced.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory to create with.
* @param key_type Optional. The key type. Pass NULL to resolve it from the keys.
* @param value_type Optional. The value type. Pass NULL to resolve it from the values.
* @param keys An array of entry_count keys. Borrowed (copied in). Pass NULL when entry_count is 0.
* @param values An array of entry_count values, parallel to keys. Borrowed (copied in). Pass NULL when entry_count is
* 0.
* @param entry_count The number of entries.
* @param out_value Receives the new composite value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_create_map(
duckdb_v2_factory_handle factory, duckdb_v2_logical_type_handle key_type, duckdb_v2_logical_type_handle value_type,
const duckdb_v2_value_handle *keys, const duckdb_v2_value_handle *values, idx_t entry_count,
duckdb_v2_value_handle *out_value, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the number of child values of a value.
*
* Per type kind: the element count for LIST and ARRAY; the field count for STRUCT and TUPLE; twice the entry count for
* MAP, whose children alternate key, value; and 2 for UNION, the tag plus the active member. Everything else reports 0,
* NULL values of any nested type included.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out_count Receives the number of children.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_child_count(duckdb_v2_value_handle value, idx_t *out_count,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns one child of a composite value as an owned copy.
*
* LIST and ARRAY children are the elements. STRUCT and TUPLE children are the fields in declared order, and a STRUCT's
* field names come from its type, via logical_type_get_param. MAP children alternate key, value, symmetric with
* value_create_map. UNION children are [0] the tag, as a UTINYINT value, and [1] the active member, because a union
* value holds only that one member.
*
* Note the divergence from vector_get_child, which descends structurally and so exposes [0] = tag and [1..N] = ALL
* members. Code written to descend generically over both must account for that difference.
*
* An out-of-range index returns ERROR_INPUT_INVALID, as does any index on a non-composite or NULL value. The returned
* value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param index The child index, in [0, child_count).
* @param out_child Receives the owned child value.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_child(duckdb_v2_value_handle value, idx_t index,
duckdb_v2_value_handle *out_child,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Casts a value to a target type, using a factory.
*
* The conversion is the SQL-faithful, non-strict one, registered custom casts included, and a cast failure surfaces
* from the call. Together with a VARCHAR built through value_create_varchar, this constructs any value from text,
* extension values included; casting a member value to a union type, or a VARCHAR to an enum type, is the sanctioned
* way to build UNION and ENUM values.
*
* A connection's or callback's factory casts with that client's cast functions and settings (e.g. TimeZone). An
* instance's factory supports only the built-in casts, with default settings.
*
* The input value and target type are borrowed. The returned value is caller-owned; destroy it via value_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param factory The factory supplying the cast functions.
* @param value The borrowed value to cast.
* @param target_type The borrowed target logical type.
* @param out_value Receives the owned cast result.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_cast(duckdb_v2_factory_handle factory, duckdb_v2_value_handle value,
duckdb_v2_logical_type_handle target_type,
duckdb_v2_value_handle *out_value, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns whether the value is NULL.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out_is_null Receives true if the value is NULL, false otherwise.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_is_null(duckdb_v2_value_handle value, bool *out_is_null,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the logical type of the value.
*
* The returned logical type is caller-owned; destroy it via logical_type_destroy.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out_type Receives the owned logical type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_get_logical_type(duckdb_v2_value_handle value,
duckdb_v2_logical_type_handle *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Renders the value as a human-readable string. Diagnostic only.
*
* Writes into a caller-supplied buffer, so nothing is allocated on the caller's behalf and nothing has to be freed.
*
* Pass out_string = NULL to size the buffer without rendering into it: out_length then receives the length, and
* out_capacity is ignored. With out_string != NULL, out_capacity must be at least out_length + 1, or the call returns
* ERROR_INPUT_OBJECT_SIZE with out_length set to the required length and out_string left untouched.
*
* out_length never counts the terminator, but a successful write always appends one, so the buffer is usable as a C
* string.
*
* history:
* - unstable: v2.0.0
*
* @param value The value to read.
* @param out_string Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required
* length in out_length.
* @param out_capacity Bytes available in out_string, terminator included. Ignored when out_string is NULL.
* @param out_length Receives the text length excluding the null terminator — written on success and on
* ERROR_INPUT_OBJECT_SIZE.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_value_to_string(duckdb_v2_value_handle value, char *out_string,
idx_t out_capacity, idx_t *out_length,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for value --- */
/* ============================================================================
* MODULE: arrow
* ============================================================================ */
/* --- Enums for arrow --- */
/* --- Struct forward declarations for arrow --- */
/* --- Types for arrow --- */
/*!
* Converts Arrow arrays into DuckDB data chunks, against one resolved ArrowSchema. Create it with
* `duckdb_v2_arrow_importer_create()`, which resolves every column's DuckDB type once, so the same importer serves any
* number of arrays of that shape. `duckdb_v2_arrow_importer_get_schema()` reports the resolved DuckDB schema.
* `duckdb_v2_arrow_importer_append()` takes an array, `duckdb_v2_arrow_importer_next_chunk()` produces chunks from it,
* and `duckdb_v2_arrow_importer_destroy()` frees the importer.
*
* The importer borrows the context it was created with and must not outlive it. One array is in flight at a time, and
* an importer must not be used from two threads at once.
*/
typedef struct _duckdb_v2_arrow_importer {
void *internal_ptr;
} * duckdb_v2_arrow_importer_handle;
/*!
* Converts DuckDB data chunks into Arrow arrays, for one fixed list of columns. Create it with
* `duckdb_v2_arrow_exporter_create()`, which captures the session's Arrow settings and resolves the extension types
* once. `duckdb_v2_arrow_exporter_get_schema()` reports the Arrow schema. `duckdb_v2_arrow_exporter_append()` takes a
* chunk, `duckdb_v2_arrow_exporter_next_array()` produces arrays from it, and `duckdb_v2_arrow_exporter_destroy()`
* frees the exporter.
*
* An exporter must not be used from two threads at once.
*/
typedef struct _duckdb_v2_arrow_exporter {
void *internal_ptr;
} * duckdb_v2_arrow_exporter_handle;
/*!
* A query result that produces Arrow arrays. Works like a result, which produces data chunks. Create it with
* `duckdb_v2_statement_execute_arrow()` or `duckdb_v2_prepared_statement_execute_arrow()`.
*
* - Use it from one thread at a time.
* - `duckdb_v2_connection_interrupt()` cancels it: `duckdb_v2_arrow_result_step()` reports `CANCELLED`, and
* `duckdb_v2_arrow_result_fetch_array()` and a stream's `get_next` fail.
* - Arrays and schemas it hands out belong to the caller and stay valid after the result is destroyed.
*/
typedef struct _duckdb_v2_arrow_result {
void *internal_ptr;
} * duckdb_v2_arrow_result_handle;
/* --- Constants for arrow --- */
/* --- Function pointer typedefs for arrow --- */
/* --- Functions for arrow --- */
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Resolves an Arrow schema into a reusable importer.
*
* Works out every column's DuckDB logical type and the Arrow type information the conversion needs, once, so any number
* of arrays of that shape can be imported without re-reading the schema. `schema` is read, not consumed: the caller
* keeps ownership and still releases it.
*
* `batch_size` caps the rows per produced chunk. A long array is split across several chunks. Rows left over that do
* not fill a batch are held back and joined with the next array, unless the append asked to flush. Pass 0 for no
* maximum: each array becomes one chunk, however long it is.
*
* Resolving reads the catalog for extension types, so `context` must have an active transaction. The importer keeps
* using that context for every conversion and must not outlive it. Within one connection the context is the same
* throughout, so an importer created in a bind callback is usable from the matching exec callback. `*out_importer` is
* set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param context The context used to resolve the Arrow types, extension types included.
* @param schema The schema to resolve. Read, not consumed; the caller keeps ownership.
* @param batch_size Maximum rows per produced chunk, or 0 for no maximum.
* @param out_importer On success, receives the new importer. Owned by the caller; destroy via
* `duckdb_v2_arrow_importer_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_importer_create(duckdb_v2_context_handle context,
struct ArrowSchema *schema, idx_t batch_size,
duckdb_v2_arrow_importer_handle *out_importer,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the resolved DuckDB schema.
*
* Writes an owned schema handle with the DuckDB name and logical type of every column the importer resolved. This is
* how a caller learns the DuckDB shape of an ArrowSchema, to declare a table function's result columns for instance,
* without reimplementing the mapping from Arrow format strings to logical types.
*
* The fields were resolved at creation, so this reads no catalog and needs no transaction. `*out_schema` is set to NULL
* on failure.
*
* history:
* - unstable: v2.0.0
*
* @param importer The importer to read.
* @param out_schema On success, receives an owned schema. Destroy via `duckdb_v2_schema_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_importer_get_schema(duckdb_v2_arrow_importer_handle importer,
duckdb_v2_schema_handle *out_schema,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Gives the importer one array to convert.
*
* Take the chunks with `duckdb_v2_arrow_importer_next_chunk()` until that returns NULL. Appending while the previous
* array still has rows left is rejected with `ERROR_INPUT_INVALID`. An array whose shape does not match the resolved
* schema -- a different child count, a child whose length differs from the array's, a null or already-released child --
* is rejected the same way, before anything is read.
*
* `flush` marks the end of the input: rows that do not fill a batch then come out as a final short chunk instead of
* being held back for the next array. Pass NULL for `array` with `flush` set to release the held rows without supplying
* more input.
*
* `consume` decides what happens to the caller's array.
*
* When true, the importer takes over the array and sets its `release` to NULL; the caller must not release it
* afterwards. The produced chunks reference the Arrow buffers directly, without copying, and keep them alive, so the
* chunks stay valid after the importer is destroyed. Prefer this path.
*
* When false, the caller keeps the array and must keep it valid until the drain finishes. The produced chunks are
* copies, so they do not depend on the array, at the cost of one copy per chunk.
*
* Either way, a chunk that joins rows held back from the previous array is a copy, since it cannot reference two
* arrays.
*
* Only the default, dictionary-encoded and run-end-encoded Arrow layouts are supported. Any other layout reports
* `ERROR_QUERY_NOT_IMPLEMENTED` when the column is converted.
*
* history:
* - unstable: v2.0.0
*
* @param importer The importer to feed.
* @param array The array to convert. Its `release` is set to NULL when `consume` is true.
* @param consume True to hand the array over for a zero-copy import; false to keep it, in which case every produced
* chunk is a copy.
* @param flush True to mark the end of the input, releasing held rows as a final short chunk. Pass NULL for `array`
* with this set to flush without supplying more input.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_importer_append(duckdb_v2_arrow_importer_handle importer,
struct ArrowArray *array, bool consume, bool flush,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Produces the next chunk of the appended array, or NULL once the array is drained.
*
* Call it in a loop until `*out_chunk` is NULL. An importer with no array appended also returns NULL. Each chunk holds
* at most the importer's `batch_size` rows, or the whole array when that is 0. A chunk may start with rows held back
* from the previous array, and rows that do not fill a batch are held back in turn unless the append asked to flush. So
* NULL means the array has been read, not that all of its rows have come out.
*
* The conversion runs under the context the importer was created with, which must still be alive. `*out_chunk` is set
* to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param importer The importer to drain.
* @param out_chunk On success, receives the next chunk, or NULL once the array is drained. Destroy via
* `duckdb_v2_data_chunk_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_importer_next_chunk(duckdb_v2_arrow_importer_handle importer,
duckdb_v2_data_chunk_handle *out_chunk,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys an importer.
*
* Null-safe: passing NULL, or a slot already set to NULL, is a no-op. Chunks already produced stay valid, including the
* zero-copy ones, which keep the Arrow buffers alive themselves. An array appended with `consume` true and not fully
* drained is released here. Rows held back for a next array are dropped. On success the slot is set to NULL.
*
* history:
* - unstable: v2.0.0
*
* @param importer The importer to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_importer_destroy(duckdb_v2_arrow_importer_handle *importer);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Creates an exporter for one fixed list of columns.
*
* Resolves the extension types and captures the session's Arrow settings, so every array this exporter produces matches
* the schema `duckdb_v2_arrow_exporter_get_schema()` reports, even if a setting changes afterwards.
*
* `batch_size` caps the rows per produced array. A long chunk is split across several arrays. Rows left over that do
* not fill a batch are held back and joined with the next chunk, unless the append asked to flush. Pass 0 for no
* maximum: each chunk becomes one array, however long it is.
*
* `types` and `names` are parallel arrays of `count` entries, borrowed and copied; they may be NULL only when `count`
* is 0. Resolving reads the catalog, so `context` must have an active transaction. `*out_exporter` is set to NULL on
* failure.
*
* history:
* - unstable: v2.0.0
*
* @param context The context whose Arrow settings are captured and whose transaction resolves the types.
* @param types An array of `count` column types. May be NULL only when `count` is 0.
* @param names An array of `count` column names, parallel to `types`. Each name must be valid UTF-8. May be NULL only
* when `count` is 0.
* @param count The number of columns, being the length of both `types` and `names`.
* @param batch_size Maximum rows per produced array, or 0 for no maximum.
* @param out_exporter On success, receives the new exporter. Owned by the caller; destroy via
* `duckdb_v2_arrow_exporter_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_exporter_create(duckdb_v2_context_handle context,
const duckdb_v2_logical_type_handle *types,
const duckdb_v2_str *names, idx_t count, idx_t batch_size,
duckdb_v2_arrow_exporter_handle *out_exporter,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the Arrow schema of the arrays this exporter produces.
*
* Fills the caller-allocated `out_schema`. The caller owns the result and releases it with
* `out_schema->release(out_schema)`. Callable at any point, and always returns the same schema, since it is built from
* the settings captured at creation.
*
* history:
* - unstable: v2.0.0
*
* @param exporter The exporter to read.
* @param out_schema Caller-allocated schema the library fills. Release it with `out_schema->release(out_schema)`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_exporter_get_schema(duckdb_v2_arrow_exporter_handle exporter,
struct ArrowSchema *out_schema,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Gives the exporter one chunk to convert.
*
* The chunk is converted in full before this returns. The conversion copies into freshly allocated Arrow buffers, so
* nothing of the caller's is retained. Every array completed by this chunk becomes available from
* `duckdb_v2_arrow_exporter_next_array()`; rows that do not complete a batch are held back and finished by the next
* chunk. Completed arrays queue up, so appending again before they are taken is allowed.
*
* `flush` marks the end of the input: the held rows are then finished as a final short array. Pass NULL for `chunk`
* with `flush` set to release the held rows without supplying more input.
*
* The chunk's types must match the ones the exporter was created with, or the call is rejected with
* `ERROR_INPUT_INVALID` before anything is read.
*
* `consume` decides only what happens to the caller's handle, since the data is copied either way. When true the chunk
* is destroyed and the slot set to NULL, saving a `duckdb_v2_data_chunk_destroy()` for a chunk the caller owns. When
* false the chunk is left untouched, which is what a chunk borrowed from a callback needs, such as the output chunk of
* a table function's exec callback, which the caller does not own and must not destroy.
*
* history:
* - unstable: v2.0.0
*
* @param exporter The exporter to feed.
* @param chunk The chunk to convert. Destroyed and set to NULL only when `consume` is true.
* @param consume True to hand the chunk over, destroying it; false to leave the caller's handle untouched.
* @param flush True to mark the end of the input, releasing the held rows as a final short array. Pass NULL for `chunk`
* with this set to flush without supplying more input.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_exporter_append(duckdb_v2_arrow_exporter_handle exporter,
duckdb_v2_data_chunk_handle *chunk, bool consume,
bool flush, duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Takes the next completed array, or reports that none is ready.
*
* Call it in a loop after every `duckdb_v2_arrow_exporter_append()` until `out_array->release` is NULL, which is how
* the Arrow C Data Interface signals "no array" and what a stream's `get_next` does at end of input. Rows held back
* towards an unfinished batch are not an array yet; they come out after a further append or a flush.
*
* Each array is owned by the caller and released with `out_array->release(out_array)`, independently of the exporter
* and of every other array.
*
* history:
* - unstable: v2.0.0
*
* @param exporter The exporter to drain.
* @param out_array Caller-allocated array the library fills. Left released -- `release` NULL -- when none is ready.
* Release a filled one with `out_array->release(out_array)`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_exporter_next_array(duckdb_v2_arrow_exporter_handle exporter,
struct ArrowArray *out_array,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys an exporter.
*
* Null-safe: passing NULL, or a slot already set to NULL, is a no-op. Arrays already taken stay valid. Arrays still
* queued inside are released here, and rows held back towards an unfinished batch are dropped. On success the slot is
* set to NULL.
*
* history:
* - unstable: v2.0.0
*
* @param exporter The exporter to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_exporter_destroy(duckdb_v2_arrow_exporter_handle *exporter);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Executes a parsed statement. The result produces Arrow arrays.
*
* Works like `duckdb_v2_statement_execute()`. `*out_result` is set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param conn The connection to run the statement on.
* @param statement The statement to execute. Not consumed.
* @param parameter_names Optional. As in `duckdb_v2_statement_execute()`.
* @param parameter_values Optional. As in `duckdb_v2_statement_execute()`.
* @param parameter_count The number of parameters. 0 for none.
* @param batch_size Maximum rows per array. Arrays can be shorter. 0 means 131072.
* @param out_result Receives the new result. Destroy via `duckdb_v2_arrow_result_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_statement_execute_arrow(duckdb_v2_connection_handle conn,
duckdb_v2_sql_statement_handle statement,
const duckdb_v2_identifier_t *parameter_names,
const duckdb_v2_value_handle *parameter_values,
idx_t parameter_count, idx_t batch_size,
duckdb_v2_arrow_result_handle *out_result,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Executes a prepared statement. The result produces Arrow arrays.
*
* Works like `duckdb_v2_prepared_statement_execute()`. `*out_result` is set to NULL on failure.
*
* history:
* - unstable: v2.0.0
*
* @param prepared The prepared statement to execute. Not consumed.
* @param parameter_names Optional. As in `duckdb_v2_prepared_statement_execute()`.
* @param parameter_values Optional. As in `duckdb_v2_prepared_statement_execute()`.
* @param parameter_count The number of parameters. 0 for none.
* @param batch_size Maximum rows per array. Arrays can be shorter. 0 means 131072.
* @param out_result Receives the new result. Destroy via `duckdb_v2_arrow_result_destroy()`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_prepared_statement_execute_arrow(duckdb_v2_prepared_statement_handle prepared,
const duckdb_v2_identifier_t *parameter_names,
const duckdb_v2_value_handle *parameter_values,
idx_t parameter_count, idx_t batch_size,
duckdb_v2_arrow_result_handle *out_result,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Destroys the result. Works like `duckdb_v2_result_destroy()`.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to destroy.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_destroy(duckdb_v2_arrow_result_handle *result);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Runs a bounded amount of the query and returns without blocking.
*
* Works like `duckdb_v2_result_step()`. On status `CHUNK`, `out_array` holds the next array. Otherwise its `release` is
* NULL.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to step.
* @param out_array Caller-allocated array the library fills. Release it with `out_array->release(out_array)`.
* @param out_status Receives the step status.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_step(duckdb_v2_arrow_result_handle result,
struct ArrowArray *out_array,
DUCKDB_V2_RESULT_STEP_STATUS *out_status,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Blocks until the next array is ready.
*
* Works like `duckdb_v2_result_fetch_chunk()`. At the end of the result, `out_array->release` is NULL.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to fetch from.
* @param out_array Caller-allocated array the library fills. Release it with `out_array->release(out_array)`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_fetch_array(duckdb_v2_arrow_result_handle result,
struct ArrowArray *out_array,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Blocks until `duckdb_v2_arrow_result_step()` can make progress. Works like `duckdb_v2_result_wait()`.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to wait on.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_wait(duckdb_v2_arrow_result_handle result,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Runs the query to the end and reports the changed-row count. Works like `duckdb_v2_result_drain()`.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to drain.
* @param out_rows_changed Receives the changed-row count for an INSERT, UPDATE or DELETE, 0 otherwise.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_drain(duckdb_v2_arrow_result_handle result, idx_t *out_rows_changed,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the shape of the result. Works like `duckdb_v2_result_get_result_type()`.
*
* history:
* - unstable: v2.0.0
*
* @param result The result.
* @param out_type Receives the result shape.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_get_result_type(duckdb_v2_arrow_result_handle result,
DUCKDB_V2_RESULT_TYPE *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the type of statement that produced the result. Works like `duckdb_v2_result_get_statement_type()`.
*
* history:
* - unstable: v2.0.0
*
* @param result The result.
* @param out_type Receives the statement type.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_get_statement_type(duckdb_v2_arrow_result_handle result,
DUCKDB_V2_STATEMENT_TYPE *out_type,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Returns the Arrow schema of the result's arrays.
*
* Available whenever `duckdb_v2_result_get_schema()` would be.
*
* history:
* - unstable: v2.0.0
*
* @param result The result.
* @param out_schema Caller-allocated schema the library fills. Release it with `out_schema->release(out_schema)`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_get_schema(duckdb_v2_arrow_result_handle result,
struct ArrowSchema *out_schema,
duckdb_v2_error_info_handle *err);
#endif
#if DUCKDB_V2_API_ALLOW_UNSTABLE
/*!
* Turns the result into an ArrowArrayStream.
*
* On success the stream takes over the result and `*result` is set to NULL. Each `get_next` returns the next array.
* Arrays already fetched are not repeated. Releasing the stream destroys the result.
*
* Converting runs no part of the query. The stream's `get_schema` can: for a statement that expands into several
* statements, such as PIVOT, it runs the ones before the statement that returns rows. A failing `get_next` or
* `get_schema` returns `EIO`; `get_last_error` has the message.
*
* history:
* - unstable: v2.0.0
*
* @param result The result to take over. Set to NULL on success.
* @param out_stream Caller-allocated stream the library fills. Release it with `out_stream->release(out_stream)`.
* @param err Optional. On failure, receives an opaque info handle the caller must destroy via
* `duckdb_v2_error_info_destroy()`.
* @return DUCKDB_V2_ERROR
*/
DUCKDB_C_API DUCKDB_V2_ERROR duckdb_v2_arrow_result_to_arrow_c_stream(duckdb_v2_arrow_result_handle *result,
struct ArrowArrayStream *out_stream,
duckdb_v2_error_info_handle *err);
#endif
/* --- Struct definitions for arrow --- */
#ifdef __cplusplus
}
#endif