packages feed

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