Warning The C API v2 is not yet stable. Its interface may change in upcoming releases. See the C API v2 overview for how to opt in and how to read the parameter ownership tags.
API Reference Overview
Common
duckdb_v2_environment_handle
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.
duckdb_v2_instance_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.
duckdb_v2_connection_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.
duckdb_v2_config_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.
duckdb_v2_option_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.
duckdb_v2_error_info_handle
Opaque detail for a failed call; destroy with duckdb_v2_error_info_destroy.
duckdb_v2_logical_type_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.
duckdb_v2_value_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.
duckdb_v2_result_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.
duckdb_v2_data_chunk_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.
duckdb_v2_vector_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.
duckdb_v2_arena_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.
duckdb_v2_context_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.
duckdb_v2_factory_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.
duckdb_v2_text_sink_fn
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.
Syntax
typedef void (*duckdb_v2_text_sink_fn)(
const duckdb_v2_str *text,
void *user_data,
duckdb_v2_error_info_handle *err
);
Parameters
text: Borrowed view of the complete text. Valid only until the sink returns.user_data: The opaque pointer handed to the producing call alongside the callback, passed through untouched.err: Live error slot, never NULL. Populate it to fail the producing call; do not destroy it. (out)
duckdb_v2_opaque_equals_fn
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.
Syntax
typedef bool (*duckdb_v2_opaque_equals_fn)(
void *a,
void *b
);
Parameters
a: Opaque pointer to the first resource to compare.b: Opaque pointer to the second resource to compare.
duckdb_v2_opaque_destroy_fn
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.
Syntax
typedef void (*duckdb_v2_opaque_destroy_fn)(
void *data
);
Parameters
data: Opaque pointer to the resource to destroy. The callback is responsible for freeing it.
duckdb_v2_sel_t
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.
Syntax
typedef uint32_t duckdb_v2_sel_t;
duckdb_v2_varchar_t
VARCHAR storage. The bytes must contain valid UTF-8. Read the transparent bytes fields directly.
Syntax
typedef duckdb_v2_bytes duckdb_v2_varchar_t;
duckdb_v2_blob_t
BLOB storage. Read the transparent bytes fields directly.
Syntax
typedef duckdb_v2_bytes duckdb_v2_blob_t;
duckdb_v2_bit_t
BIT storage. Byte 0 is the padding-bit count, bytes 1.. the data.
Syntax
typedef duckdb_v2_bytes duckdb_v2_bit_t;
duckdb_v2_bignum_t
BIGNUM storage. Decode via duckdb_v2_bignum_decode.
Syntax
typedef duckdb_v2_bytes duckdb_v2_bignum_t;
duckdb_v2_identifier_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.
Syntax
typedef duckdb_v2_str duckdb_v2_identifier_t;
duckdb_v2_str
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.
Fields
ptr(const char *)len(idx_t)
duckdb_v2_bytes
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
- 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.
Fields
value(union)pointer(struct)length(uint32_t)prefix(char[4])ptr(char *)
inlined(struct)length(uint32_t)inlined(char[12])
duckdb_v2_opaque
An opaque, owned handle to a caller-defined resource. Bundles the pointer with optional callbacks that destroy and compare the resource.
Fields
ptr(void *)destroy(duckdb_v2_opaque_destroy_fn)equals(duckdb_v2_opaque_equals_fn)
DUCKDB_V2_ORDER_PRESERVATION
The order guarantee a producer of rows makes about its output, which decides whether the rows it produces must be kept in order downstream.
Values
DUCKDB_V2_ORDER_PRESERVATION_NO_ORDER= 0: 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_INSERTION_ORDER= 1: The rows are produced in insertion order, which the engine keeps unless thepreserve_insertion_ordersetting is disabled.DUCKDB_V2_ORDER_PRESERVATION_FIXED_ORDER= 2: The rows are produced in an order that must be kept, as if sorted by anORDER BY, even when thepreserve_insertion_ordersetting is disabled.
DUCKDB_V2_BYTES_INLINE_LENGTH
Inline cutoff for bytes storage: a value of at most this many bytes is stored inline.
Value: 12.
Errors
DUCKDB_V2_ERROR
Error codes for API calls.
Values
DUCKDB_V2_ERROR_NONE= 0: Success.DUCKDB_V2_ERROR_API= 1: Generic API error.DUCKDB_V2_ERROR_IO_FILE_NOT_FOUND= 1001: The specified file could not be found.DUCKDB_V2_ERROR_IO_READ_FAILURE= 1002: Failed to read from the storage device.DUCKDB_V2_ERROR_IO_EOF= 1003: Unexpected end of file reached.DUCKDB_V2_ERROR_IO_GENERAL= 1004: A generic I/O error occurred while reading or writing data.DUCKDB_V2_ERROR_IO_NETWORK= 1005: A network-level failure occurred during an I/O operation.DUCKDB_V2_ERROR_IO_HTTP= 1006: An HTTP request issued by the database failed.DUCKDB_V2_ERROR_INPUT_INVALID= 2001: General invalid input error.DUCKDB_V2_ERROR_INPUT_PARAMETER_INVALID= 2002: A specific function parameter is malformed.DUCKDB_V2_ERROR_INPUT_OUT_OF_RANGE= 2003: A provided value is outside the acceptable range.DUCKDB_V2_ERROR_INPUT_OBJECT_SIZE= 2004: An object exceeded its maximum permitted size.DUCKDB_V2_ERROR_INPUT_METADATA_DEFERRED= 2005: 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_RESOURCE_IN_USE= 3001: The requested resource is already in use.DUCKDB_V2_ERROR_RESOURCE_OUT_OF_MEMORY= 3002: An allocation failed because the system ran out of memory.DUCKDB_V2_ERROR_RESOURCE_CONNECTION= 3003: A connection-level failure occurred (e.g. the connection has been closed or invalidated).DUCKDB_V2_ERROR_RESOURCE_DEPENDENCY= 3004: An operation failed because of an unresolved dependency between catalog objects.DUCKDB_V2_ERROR_RESOURCE_MISSING_EXTENSION= 3005: An extension required by the operation is not loaded.DUCKDB_V2_ERROR_RESOURCE_AUTOLOAD= 3006: Autoloading an extension failed.DUCKDB_V2_ERROR_TYPE_CONVERSION= 4001: A value could not be converted to the requested type.DUCKDB_V2_ERROR_TYPE_UNKNOWN= 4002: An unknown or unsupported type was encountered.DUCKDB_V2_ERROR_TYPE_INVALID= 4003: A type was used in a context where it is not valid.DUCKDB_V2_ERROR_TYPE_MISMATCH= 4004: Two values or expressions have incompatible types.DUCKDB_V2_ERROR_TYPE_DECIMAL= 4005: A decimal value is out of range or otherwise invalid.DUCKDB_V2_ERROR_TYPE_DIVIDE_BY_ZERO= 4006: Division by zero was attempted.DUCKDB_V2_ERROR_QUERY_PARSER= 5001: The query could not be parsed.DUCKDB_V2_ERROR_QUERY_SYNTAX= 5002: The query contains a syntax error.DUCKDB_V2_ERROR_QUERY_BINDER= 5003: Binding the query against the catalog failed (e.g. unknown column or table).DUCKDB_V2_ERROR_QUERY_PLANNER= 5004: The query could not be translated into a logical plan.DUCKDB_V2_ERROR_QUERY_OPTIMIZER= 5005: An error occurred during query optimization.DUCKDB_V2_ERROR_QUERY_EXPRESSION= 5006: An expression in the query is invalid or could not be evaluated.DUCKDB_V2_ERROR_QUERY_EXECUTOR= 5007: An error occurred while executing the physical plan.DUCKDB_V2_ERROR_QUERY_SCHEDULER= 5008: The task scheduler reported an error while running the query.DUCKDB_V2_ERROR_QUERY_NOT_IMPLEMENTED= 5009: The requested feature or operation is not implemented.DUCKDB_V2_ERROR_QUERY_PARAMETER_NOT_RESOLVED= 5010: A prepared-statement parameter has not been bound to a value.DUCKDB_V2_ERROR_QUERY_PARAMETER_NOT_ALLOWED= 5011: A prepared-statement parameter was used in a position where it is not allowed.DUCKDB_V2_ERROR_DATABASE_CATALOG= 6001: A catalog operation failed (e.g. object not found or already exists).DUCKDB_V2_ERROR_DATABASE_TRANSACTION= 6002: A transaction-level error occurred (e.g. conflict or aborted transaction).DUCKDB_V2_ERROR_DATABASE_CONSTRAINT= 6003: A constraint (primary key, unique, foreign key, NOT NULL, check) was violated.DUCKDB_V2_ERROR_DATABASE_INDEX= 6004: An index operation failed.DUCKDB_V2_ERROR_DATABASE_SEQUENCE= 6005: A sequence operation failed (e.g. overflow or invalid usage).DUCKDB_V2_ERROR_DATABASE_STATISTICS= 6006: An error related to catalog statistics occurred.DUCKDB_V2_ERROR_DATABASE_SERIALIZATION= 6007: Serializing or deserializing a database object failed.DUCKDB_V2_ERROR_CONFIGURATION_SETTINGS= 7001: A settings-related error occurred (e.g. setting an unknown option).DUCKDB_V2_ERROR_CONFIGURATION_INVALID= 7002: The database configuration is invalid.DUCKDB_V2_ERROR_CONFIGURATION_PERMISSION= 7003: The operation is not permitted under the current configuration.DUCKDB_V2_ERROR_RUNTIME_INTERNAL= 8001: An internal invariant was violated; this indicates a bug in DuckDB.DUCKDB_V2_ERROR_RUNTIME_FATAL= 8002: A fatal error occurred; the database is no longer usable.DUCKDB_V2_ERROR_RUNTIME_INTERRUPT= 8003: The operation was interrupted (e.g. by a cancel request).DUCKDB_V2_ERROR_RUNTIME_NULL_POINTER= 8004: A required pointer was unexpectedly null.
Function Properties
DUCKDB_V2_FUNCTION_PROPERTY_KEY
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.
Values
DUCKDB_V2_FUNCTION_PROPERTY_STABILITY= 65536: How stable/deterministic the function's result is across rows and queries. Accepts theFUNCTION_PROPERTY_STABILITY_*values. Defaults toCONSISTENT.DUCKDB_V2_FUNCTION_PROPERTY_NULL_HANDLING= 65792: Whether the function handles NULL inputs itself. Accepts theFUNCTION_PROPERTY_NULL_HANDLING_*values. Defaults toDEFAULT(NULL in, NULL out).DUCKDB_V2_FUNCTION_PROPERTY_FALLIBILITY= 66048: Whether the function can raise a runtime error. Accepts theFUNCTION_PROPERTY_FALLIBILITY_*values. Functions created through this API default toFALLIBLE, since their callbacks can report errors.DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING= 66304: How the function interacts with collations on its arguments. Accepts theFUNCTION_PROPERTY_COLLATION_HANDLING_*values. Defaults toPROPAGATE.DUCKDB_V2_FUNCTION_PROPERTY_AGG_ORDER_DEPENDENT= 196608: Aggregate only. Whether the aggregate's result depends on the order in which rows are aggregated. Accepts theFUNCTION_PROPERTY_AGG_ORDER_DEPENDENT_*values. Defaults toYES.DUCKDB_V2_FUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT= 196864: Aggregate only. Whether the aggregate's result is affected by a DISTINCT modifier. Accepts theFUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT_*values. Defaults toYES.
DUCKDB_V2_FUNCTION_PROPERTY_VALUE
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.
Values
DUCKDB_V2_FUNCTION_PROPERTY_STABILITY_CONSISTENT= 65536: The function always returns the same result given the same input.DUCKDB_V2_FUNCTION_PROPERTY_STABILITY_VOLATILE= 65537: The result may differ per row (e.g. random()).DUCKDB_V2_FUNCTION_PROPERTY_STABILITY_CONSISTENT_WITHIN_QUERY= 65538: The result is stable within a single query/transaction but may change across queries (e.g. now()).DUCKDB_V2_FUNCTION_PROPERTY_NULL_HANDLING_DEFAULT= 65792: 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_SPECIAL= 65793: The function handles NULL inputs itself and is invoked even when arguments are NULL.DUCKDB_V2_FUNCTION_PROPERTY_FALLIBILITY_INFALLIBLE= 66048: 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_FALLIBLE= 66049: The function may raise a runtime error for some inputs.DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING_PROPAGATE= 66304: The function combines collations from its inputs and propagates them to its result (default).DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING_PUSH_COMBINABLE= 66305: Combinable collations are executed on the input arguments before the function runs.DUCKDB_V2_FUNCTION_PROPERTY_COLLATION_HANDLING_IGNORE= 66306: Collations are ignored by the function.DUCKDB_V2_FUNCTION_PROPERTY_AGG_ORDER_DEPENDENT_YES= 196608: The aggregate's result depends on the order in which rows are aggregated (default).DUCKDB_V2_FUNCTION_PROPERTY_AGG_ORDER_DEPENDENT_NO= 196609: The aggregate's result does not depend on input order.DUCKDB_V2_FUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT_YES= 196864: The aggregate's result is affected by a DISTINCT modifier (default).DUCKDB_V2_FUNCTION_PROPERTY_AGG_DISTINCT_DEPENDENT_NO= 196865: The aggregate's result is not affected by a DISTINCT modifier.
Arena
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);
duckdb_v2_arena_allocate
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
arena: The arena to allocate from.byte_len: Number of bytes to reserve. May be 0.out_ptr: Receives a writable pointer to byte_len arena-owned bytes. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Cast
duckdb_v2_cast_function_handle
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.
duckdb_v2_cast_function_exec_info_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.
duckdb_v2_cast_function_exec_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
DUCKDB_V2_CAST_MODE
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.
Values
DUCKDB_V2_CAST_MODE_NORMAL= 0: A regular cast. A conversion failure reported through the error slot aborts the query.DUCKDB_V2_CAST_MODE_TRY= 1: 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_ERROR duckdb_v2_cast_function_create(duckdb_v2_factory_handle factory, duckdb_v2_cast_function_handle *function, duckdb_v2_error_info_handle *err);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_cast_function_destroy(duckdb_v2_cast_function_handle *function);
duckdb_v2_cast_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the cast function through.function: On success, receives the newly created cast function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_set_source_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the source type of.source_type: The type to cast from. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_set_target_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the target type of.target_type: The type to cast to. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_set_implicit_cast_cost
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the implicit cast cost of.cost: The cost. Negative disables implicit casting.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_set_exec_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the exec callback of.callback: The exec callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_exec_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_cast_function_set_user_data.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_exec_get_row_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.count: Receives the number of rows. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_exec_get_input
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.vector: Receives the borrowed input vector. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_exec_get_output
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.vector: Receives the borrowed output vector to write into. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_exec_get_mode
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.mode: Receives the cast mode. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_cast_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.function: The cast function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_cast_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The cast function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_cast_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_cast_function_destroy(
duckdb_v2_cast_function_handle *function
);
Parameters
function: The function to destroy.
Return Value
DUCKDB_V2_ERROR
Column Data Collection
duckdb_v2_column_data_collection_handle
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.
duckdb_v2_column_data_collection_shared_scan_state_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.
duckdb_v2_column_data_collection_worker_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.
duckdb_v2_column_data_collection_append_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.
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);
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_reset(duckdb_v2_column_data_collection_handle collection, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_clear(duckdb_v2_column_data_collection_handle collection, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_destroy(duckdb_v2_column_data_collection_handle *collection);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_append_state_destroy(duckdb_v2_column_data_collection_append_state_handle *state);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_shared_scan_state_destroy(duckdb_v2_column_data_collection_shared_scan_state_handle *state);
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);
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_worker_scan_state_destroy(duckdb_v2_column_data_collection_worker_scan_state_handle *state);
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);
duckdb_v2_column_data_collection_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.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.types_count: Number of elements in the types_array.out_collection: Receives the new collection handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_reset
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_reset(
duckdb_v2_column_data_collection_handle collection,
duckdb_v2_error_info_handle *err
);
Parameters
collection: The collection to reset.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_clear
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_clear(
duckdb_v2_column_data_collection_handle collection,
duckdb_v2_error_info_handle *err
);
Parameters
collection: The collection to clear.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_destroy(
duckdb_v2_column_data_collection_handle *collection
);
Parameters
collection: The collection to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_combine
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
target: The collection to merge into. After the call, this collection will contain all chunks from both collections.source: The collection to merge from. This collection will be destroyed by this operation and its handle set to NULL.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_row_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
collection: The collection to inspect.out_row_count: Receives the total row count. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_append_state_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
collection: The collection to prepare for appending.out_state: Receives the new append state handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_append_state_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_append_state_destroy(
duckdb_v2_column_data_collection_append_state_handle *state
);
Parameters
state: The append state to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_append
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
collection: The collection to append to.state: The append state to use this append operation.chunk: The chunk to append.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_shared_scan_state_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
collection: The collection to prepare for shared scanning.out_state: Receives the new shared scan state handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_shared_scan_state_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_shared_scan_state_destroy(
duckdb_v2_column_data_collection_shared_scan_state_handle *state
);
Parameters
state: The shared scan state to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_worker_scan_state_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
collection: The collection to prepare for worker scanning.out_state: Receives the new worker scan state handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_worker_scan_state_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_data_collection_worker_scan_state_destroy(
duckdb_v2_column_data_collection_worker_scan_state_handle *state
);
Parameters
state: The worker scan state to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_data_collection_scan
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
collection: The collection to scan.shared_state: The shared scan state to use for coordinating across threads.worker_state: The worker-local scan state to use for this thread's scan operation.out_chunk: The output chunk to write to.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). (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Configuration
DUCKDB_V2_SETTING_SCOPE
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.
Values
DUCKDB_V2_SETTING_SCOPE_DEFAULT= 0: Write only: the option's default scope (duckdb_v2_option_get_default_scope), not its default value.DUCKDB_V2_SETTING_SCOPE_GLOBAL= 1: The instance's value, visible to all connections.DUCKDB_V2_SETTING_SCOPE_SESSION= 2: A connection's session value.
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_config_get_option_count(duckdb_v2_config_handle config, idx_t *out_count, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_option_destroy(duckdb_v2_option_handle *option);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_option_get_description(duckdb_v2_option_handle option, duckdb_v2_str *out_description, duckdb_v2_error_info_handle *err);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_option_get_alias_count(duckdb_v2_option_handle option, idx_t *out_count, duckdb_v2_error_info_handle *err);
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);
duckdb_v2_instance_get_config
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance.out_config: Receives the borrowed config. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_get_config
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection.out_config: Receives the borrowed config. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_context_get_config
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
ctx: The context.out_config: Receives the borrowed config. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_config_get_option_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
config: The config to read from.name: Option name (canonical or alias).out_value: Receives the value, typed as the option. Owned by the caller. (out)out_scope: Receives the scope the value came from. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_config_set_option_value
Unstable since 2.0.0.
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 SQLSETdoes. 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 toduckdb_v2_instance_create_with_options.
Syntax
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
);
Parameters
config: The config to write to.name: Option name (canonical or alias).value: The value, cast to the option's type as SQLSETdoes. Borrowed.scope: Target scope: DEFAULT, GLOBAL, or SESSION.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_config_set_option_text
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
config: The config to write to.name: Option name (canonical or alias).setting: The setting, in the textual form SQLSETaccepts.scope: Target scope: DEFAULT, GLOBAL, or SESSION.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_config_get_option_by_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
config: The config whose instance registered the options.name: Option name (canonical or alias).out_option: Receives the option descriptor. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_config_get_option_count
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_config_get_option_count(
duckdb_v2_config_handle config,
idx_t *out_count,
duckdb_v2_error_info_handle *err
);
Parameters
config: The config whose instance registered the options.out_count: Receives the option count. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_config_get_option_by_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
config: The config whose instance registered the options.index: The option index, in [0, option_count).out_option: Receives the option descriptor. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_option_destroy(
duckdb_v2_option_handle *option
);
Parameters
option: The option handle to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_get_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option.out_name: Receives a borrowed view of the option name. Valid until the option is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_get_default_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option.out_value: Receives the default value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_get_description
Unstable since 2.0.0.
Borrows the option's human-readable description.
Syntax
DUCKDB_V2_ERROR duckdb_v2_option_get_description(
duckdb_v2_option_handle option,
duckdb_v2_str *out_description,
duckdb_v2_error_info_handle *err
);
Parameters
option: The option.out_description: Receives a borrowed view of the description. Valid until the option is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_supports_scope
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option.scope: The scope to ask about.out_supported: Receives whether a write at the scope is accepted. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_get_default_scope
Unstable since 2.0.0.
Returns the scope a DEFAULT write of the option goes to: GLOBAL or SESSION.
Syntax
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
);
Parameters
option: The option.out_scope: Receives the default scope. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_get_alias_count
Unstable since 2.0.0.
Returns the number of aliases registered for this option.
Zero for an extension option; extension options carry no aliases.
Syntax
DUCKDB_V2_ERROR duckdb_v2_option_get_alias_count(
duckdb_v2_option_handle option,
idx_t *out_count,
duckdb_v2_error_info_handle *err
);
Parameters
option: The option.out_count: Receives the alias count. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_option_get_alias
Unstable since 2.0.0.
Borrows the alias name at the given index.
An out-of-range index returns ERROR_INPUT_INVALID.
Syntax
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
);
Parameters
option: The option.index: The alias index, in [0, alias_count).out_alias: Receives a borrowed view of the alias. Valid until the option is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Connection
DUCKDB_V2_ERROR duckdb_v2_connection_create(duckdb_v2_instance_handle instance, duckdb_v2_connection_handle *out_conn, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_connection_destroy(duckdb_v2_connection_handle *conn);
DUCKDB_V2_ERROR duckdb_v2_connection_interrupt(duckdb_v2_connection_handle conn, duckdb_v2_error_info_handle *err);
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);
duckdb_v2_connection_create
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_connection_create(
duckdb_v2_instance_handle instance,
duckdb_v2_connection_handle *out_conn,
duckdb_v2_error_info_handle *err
);
Parameters
instance: The instance to connect to.out_conn: Receives the new connection handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_connection_destroy(
duckdb_v2_connection_handle *conn
);
Parameters
conn: The connection to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_interrupt
Unstable since 2.0.0.
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).
Syntax
DUCKDB_V2_ERROR duckdb_v2_connection_interrupt(
duckdb_v2_connection_handle conn,
duckdb_v2_error_info_handle *err
);
Parameters
conn: The connection whose active query to interrupt.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_progress_get
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection.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. (out)out_rows_processed: Receives the number of rows processed so far. (out)out_total_rows_to_process: Receives the total number of rows the query will process. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Custom Type
duckdb_v2_custom_type_handle
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.
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_custom_type_destroy(duckdb_v2_custom_type_handle *type);
duckdb_v2_custom_type_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the custom type through.type: On success, receives the newly created custom type. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_type_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
type: The type to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_type_set_base_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
type: The type to set the base type of.base_type: The logical type to base the custom type on. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_custom_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.type: The custom type to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_custom_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.type: The custom type to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_type_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_custom_type_destroy(
duckdb_v2_custom_type_handle *type
);
Parameters
type: The type to destroy.
Return Value
DUCKDB_V2_ERROR
Data Chunk
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);
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);
DUCKDB_V2_ERROR duckdb_v2_data_chunk_destroy(duckdb_v2_data_chunk_handle *chunk);
DUCKDB_V2_ERROR duckdb_v2_data_chunk_clear(duckdb_v2_data_chunk_handle chunk, duckdb_v2_error_info_handle *err);
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);
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);
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);
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);
duckdb_v2_data_chunk_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.types: Pointer to an array of logical_type handles, one per column.column_count: Number of elements in the types array.out_chunk: Receives the new chunk handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_data_chunk_copy
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.chunk: The chunk to copy. Left unchanged.out_chunk: Receives the new chunk handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_data_chunk_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_data_chunk_destroy(
duckdb_v2_data_chunk_handle *chunk
);
Parameters
chunk: The chunk to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_data_chunk_clear
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_data_chunk_clear(
duckdb_v2_data_chunk_handle chunk,
duckdb_v2_error_info_handle *err
);
Parameters
chunk: The chunk to clear.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_data_chunk_get_size
Unstable since 2.0.0.
Returns the row count of a data chunk.
Syntax
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
);
Parameters
chunk: The chunk.out_size: Receives the row count. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_data_chunk_get_capacity
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
chunk: The chunk.out_capacity: Receives the number of rows the chunk can hold. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_data_chunk_get_vector_count
Unstable since 2.0.0.
Returns the number of vectors in a data chunk.
Equals the column count of the producing result.
Syntax
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
);
Parameters
chunk: The chunk.out_count: Receives the vector count. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_data_chunk_get_vector
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
chunk: The chunk.index: The vector index, in [0, vector_count).out_vector: Receives the borrowed vector handle. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Environment
DUCKDB_V2_ERROR duckdb_v2_environment_create(duckdb_v2_environment_handle *out_env, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_environment_destroy(duckdb_v2_environment_handle *env);
DUCKDB_V2_ERROR duckdb_v2_environment_get_instance_count(duckdb_v2_environment_handle env, idx_t *out_count, duckdb_v2_error_info_handle *err);
duckdb_v2_environment_create
Unstable since 2.0.0.
Creates the V2 environment. Call once at program start.
Syntax
DUCKDB_V2_ERROR duckdb_v2_environment_create(
duckdb_v2_environment_handle *out_env,
duckdb_v2_error_info_handle *err
);
Parameters
out_env: Receives the new environment handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_environment_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_environment_destroy(
duckdb_v2_environment_handle *env
);
Parameters
env: The environment.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_environment_get_instance_count
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_environment_get_instance_count(
duckdb_v2_environment_handle env,
idx_t *out_count,
duckdb_v2_error_info_handle *err
);
Parameters
env: The environment.out_count: Receives the number of live instances. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Error
DUCKDB_V2_ERROR duckdb_v2_error_info_get_code(duckdb_v2_error_info_handle info, DUCKDB_V2_ERROR *out_code);
DUCKDB_V2_ERROR duckdb_v2_error_info_get_text(duckdb_v2_error_info_handle info, duckdb_v2_str *out_text);
DUCKDB_V2_ERROR duckdb_v2_error_info_get_raw_text(duckdb_v2_error_info_handle info, duckdb_v2_str *out_raw_text);
DUCKDB_V2_ERROR duckdb_v2_error_info_set_code(duckdb_v2_error_info_handle info, DUCKDB_V2_ERROR code);
DUCKDB_V2_ERROR duckdb_v2_error_info_set_text(duckdb_v2_error_info_handle info, const duckdb_v2_str *text);
DUCKDB_V2_ERROR duckdb_v2_error_info_destroy(duckdb_v2_error_info_handle *info);
duckdb_v2_error_info_get_code
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_error_info_get_code(
duckdb_v2_error_info_handle info,
DUCKDB_V2_ERROR *out_code
);
Parameters
info: The error info handle to query.out_code: The error code associated with the info, if the call succeeds. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_error_info_get_text
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_error_info_get_text(
duckdb_v2_error_info_handle info,
duckdb_v2_str *out_text
);
Parameters
info: The error info handle to query.out_text: Receives a borrowed view of the text. Owned by DuckDB; valid until the info handle is destroyed. (out, borrowed)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_error_info_get_raw_text
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_error_info_get_raw_text(
duckdb_v2_error_info_handle info,
duckdb_v2_str *out_raw_text
);
Parameters
info: The error info handle to query.out_raw_text: Receives a borrowed view of the raw text. Owned by DuckDB; valid until the info handle is destroyed. (out, borrowed)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_error_info_set_code
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_error_info_set_code(
duckdb_v2_error_info_handle info,
DUCKDB_V2_ERROR code
);
Parameters
info: The error info handle to set. On success, updated with the provided code.code: The error code to set in the info.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_error_info_set_text
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_error_info_set_text(
duckdb_v2_error_info_handle info,
const duckdb_v2_str *text
);
Parameters
info: The error info handle to set. On success, updated with the provided text.text: The error text to set in the info.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_error_info_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_error_info_destroy(
duckdb_v2_error_info_handle *info
);
Parameters
info: The error info handle to destroy. Set to nullptr on return.
Return Value
DUCKDB_V2_ERROR
Extension
duckdb_v2_extension_get_api_fn
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.
Syntax
typedef const void *(*duckdb_v2_extension_get_api_fn)(
duckdb_v2_extension_handle extension,
const char *version
);
Parameters
extension: The extension being loaded, as handed to the entrypoint.version: The API version the extension was built against, e.g. “v2.0.0”.
duckdb_v2_extension_input
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.
Fields
get_api(duckdb_v2_extension_get_api_fn): Fetches the versioned function-pointer table. NULL for a statically linked extension.extension(duckdb_v2_extension_handle): The extension being loaded, and the token get_api takes.context(duckdb_v2_context_handle): 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.err(duckdb_v2_error_info_handle *): 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.
Factory
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);
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);
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);
duckdb_v2_instance_get_factory
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance.out_factory: Receives the borrowed factory. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_get_factory
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection.out_factory: Receives the borrowed factory. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_context_get_factory
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
ctx: The context.out_factory: Receives the borrowed factory. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
File System
duckdb_v2_file_system_handle
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.
duckdb_v2_file_open_options_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.
duckdb_v2_file_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.
duckdb_v2_file_system_path_glob_callback_fn
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.
Syntax
typedef void (*duckdb_v2_file_system_path_glob_callback_fn)(
const duckdb_v2_str *path,
void *user_data,
duckdb_v2_error_info_handle *err
);
Parameters
path: Borrowed view of the matched path. Valid only until the callback returns.user_data: The pointer passed toduckdb_v2_file_system_path_glob, untouched.err: A live error slot to report a failure through, which stops the glob.
DUCKDB_V2_FILE_FLAG
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.
Values
DUCKDB_V2_FILE_FLAG_INVALID= 0: 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_READ= 1: Open the file with “read” capabilities.DUCKDB_V2_FILE_FLAG_WRITE= 2: Open the file with “write” capabilities.DUCKDB_V2_FILE_FLAG_CREATE= 3: Create the file if it does not exist, and open it as it is if it does.DUCKDB_V2_FILE_FLAG_CREATE_NEW= 4: Create the file if it does not exist, and truncate it to empty if it does. To fail instead of truncating, combineFILE_FLAG_CREATEwithFILE_FLAG_EXCLUSIVE_CREATE.DUCKDB_V2_FILE_FLAG_APPEND= 5: Open the file in “append” mode.DUCKDB_V2_FILE_FLAG_EXCLUSIVE_CREATE= 6: Fail if the file already exists. A modifier onFILE_FLAG_CREATE, and meaningless without it.DUCKDB_V2_FILE_FLAG_PARALLEL_ACCESS= 7: The file will be read and written at explicit offsets from several threads at once. Pass it wheneverduckdb_v2_file_read_atorduckdb_v2_file_write_atare 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_EXTERNAL_FILE_CACHE= 8: 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 thecache_local_filessetting. Only meaningful for reading.
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_file_open_options_destroy(duckdb_v2_file_open_options_handle *options);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_file_tell(duckdb_v2_file_handle file, idx_t *position, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_file_size(duckdb_v2_file_handle file, idx_t *size, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_file_seek(duckdb_v2_file_handle file, idx_t position, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_file_sync(duckdb_v2_file_handle file, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_file_close(duckdb_v2_file_handle file, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_file_destroy(duckdb_v2_file_handle *file);
duckdb_v2_context_get_file_system
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
context: The context to take the file system from.file_system: Receives the borrowed file system. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_get_file_system
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance to take the file system from.file_system: Receives the borrowed file system. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_get_file_system
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to take the file system from.file_system: Receives the borrowed file system. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_open_options_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system the options are for.options: On success, receives the new options. Owned by the caller; destroy viaduckdb_v2_file_open_options_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_open_options_set_flag
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
options: The options to apply the flag to.flag: The flag to apply.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_open_options_set_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
options: The options to set the value on.name: The name of the value. Borrowed and copied.value: The value. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_open_options_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_file_open_options_destroy(
duckdb_v2_file_open_options_handle *options
);
Parameters
options: The options to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_system_open
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system to open the file through.file_path: The path of the file to open. Borrowed for the call only.options: How to open the file. Borrowed for the call only, and reusable across opens.file: On success, receives the open file. Owned by the caller; destroy viaduckdb_v2_file_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_system_path_exists
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system to ask.path: The path to check. Borrowed for the call only.out_exists: Receives whether a file exists at the path. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_system_path_is_remote
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system the path is meant for.path: The path to check. Borrowed for the call only.out_is_remote: Receives whether the path names a remote file. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_system_path_expand
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system whose settings expand the path.path: The path to expand. Borrowed for the call only.sink: Receives the expanded path in a single call. Borrowed for the duration of that call; see text_sink for the full contract.user_data: Opaque pointer passed through to sink untouched. May be NULL.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_system_path_glob
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system to glob in.pattern: The glob pattern. Borrowed for the call only.callback: Invoked once per matched path.user_data: Opaque pointer passed through tocallbackuntouched. May be NULL.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_system_path_move
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system to move the file in.source: The path of the file to move. Borrowed for the call only.target: The path to move the file to. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_system_path_remove
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file_system: The file system to remove the file from.path: The path of the file to remove. Borrowed for the call only.out_removed: Optional. Receives whether a file was removed. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_read
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file: The file to read from.buffer: A caller-owned buffer of at leastbuffer_sizebytes, receiving what was read.buffer_size: The maximum number of bytes to read.bytes_read: Receives how many bytes were actually read, which may be fewer thanbuffer_sizeat the end of the file. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_write
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file: The file to write to.buffer: A caller-owned buffer of at leastbuffer_sizebytes, holding what to write.buffer_size: The number of bytes to write.bytes_written: Receives how many bytes were actually written. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_read_at
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file: The file to read from.buffer: A caller-owned buffer of at leastbuffer_sizebytes, receiving what was read.buffer_size: The number of bytes to read. All of them are read, or the call fails.location: The absolute byte offset to read from, measured from the start of the file.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_write_at
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
file: The file to write to.buffer: A caller-owned buffer of at leastbuffer_sizebytes, holding what to write.buffer_size: The number of bytes to write. All of them are written, or the call fails.location: The absolute byte offset to write at, measured from the start of the file.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_tell
Unstable since 2.0.0.
Returns the file's current read/write position, as a byte offset from the start of the file.
Syntax
DUCKDB_V2_ERROR duckdb_v2_file_tell(
duckdb_v2_file_handle file,
idx_t *position,
duckdb_v2_error_info_handle *err
);
Parameters
file: The file to query.position: Receives the current position, as a byte offset from the start of the file. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_size
Unstable since 2.0.0.
Returns the total size of the file in bytes.
Syntax
DUCKDB_V2_ERROR duckdb_v2_file_size(
duckdb_v2_file_handle file,
idx_t *size,
duckdb_v2_error_info_handle *err
);
Parameters
file: The file to query.size: Receives the total size of the file in bytes. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_seek
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_file_seek(
duckdb_v2_file_handle file,
idx_t position,
duckdb_v2_error_info_handle *err
);
Parameters
file: The file to seek within.position: The absolute byte offset to seek to, measured from the start of the file.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_sync
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_file_sync(
duckdb_v2_file_handle file,
duckdb_v2_error_info_handle *err
);
Parameters
file: The file to synchronize.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_close
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_file_close(
duckdb_v2_file_handle file,
duckdb_v2_error_info_handle *err
);
Parameters
file: The file to close.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_file_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_file_destroy(
duckdb_v2_file_handle *file
);
Parameters
file: The file to destroy.
Return Value
DUCKDB_V2_ERROR
Function
duckdb_v2_function_bind_info_handle
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.
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);
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);
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);
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);
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);
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);
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);
duckdb_v2_function_bind_get_user_data
Unstable since 2.0.0.
Retrieves the user data set on the function being bound, e.g. via duckdb_v2_scalar_function_set_user_data.
Syntax
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
);
Parameters
info: The bind info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_bind_set_bind_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.data: Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_bind_get_arg_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.positional_fixed: Optional. Receives the number of positional-only and standard parameters. (out)positional_variadic: Optional. Receives the number of arguments*argsreceived, 0 when the signature has none. (out)named_fixed: Optional. Receives the number of named-only parameters. (out)named_variadic: Optional. Receives the number of arguments**kwargsreceived, 0 when the signature has none. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_bind_get_arg_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the argument.type: Receives the argument type. Owned by the caller; destroy viaduckdb_v2_logical_type_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_bind_get_arg_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the argument.value: Receives the constant value. Owned by the caller; destroy viaduckdb_v2_value_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_bind_get_arg_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the argument.name: Receives a borrowed view of the argument name. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_bind_get_arg_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.name: The name to look up. Borrowed for the call only.index: Receives the index of the argument, if found. (out)found: Receives whether the call has an argument of that name. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
Function Docs
duckdb_v2_function_docs_handle
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.
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);
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);
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);
duckdb_v2_function_docs_set_description
Unstable since 2.0.0.
Sets the description of the function overload.
The description is borrowed and copied. Calling this again replaces the previous description.
Syntax
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
);
Parameters
docs: The documentation to set the description of.description: The description to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_docs_add_example
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
docs: The documentation to add the example to.title: Optional. The title of the example; NULL or an empty view for none. Borrowed and copied.example: The example, e.g. a SQL expression calling the function. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_docs_add_category
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
docs: The documentation to add the category to.category: The category. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Function Signature
duckdb_v2_function_signature_handle
An opaque handle to a function signature. Carries the function's parameters and return type.
DUCKDB_V2_FUNCTION_PARAMETER_KIND
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.
Values
DUCKDB_V2_FUNCTION_PARAMETER_KIND_POSITIONAL_ONLY= 0: 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_STANDARD= 1: Passed by position or by name.DUCKDB_V2_FUNCTION_PARAMETER_KIND_POSITIONAL_VARIADIC= 2:*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_NAMED_ONLY= 3: Passed by name only.DUCKDB_V2_FUNCTION_PARAMETER_KIND_NAMED_VARIADIC= 4:**kwargs: receives the named arguments that match no other parameter, each cast to the parameter type. ANY leaves them un-cast.
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);
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);
duckdb_v2_function_signature_add_parameter
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
sig: The signature to configure.name: The parameter name. Borrowed and copied.type: The parameter type. ANY accepts an argument of any type without casting it. Borrowed and copied.value: Optional default value, borrowed and copied. Will be cast to the parameter type.kind: How a caller passes the argument for the parameter.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_function_signature_set_return_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
sig: The signature to configure.type: The return type. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Identifier
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);
duckdb_v2_identifier_render_quoted
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
name: The name to render. Borrowed for the call only.out_text: Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required length in out_length. (out)out_capacity: Bytes available in out_text, terminator included. Ignored when out_text is NULL.out_length: Receives the text length excluding the null terminator — written on success and on ERROR_INPUT_OBJECT_SIZE. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
Instance
duckdb_v2_attach_options_handle
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.
DUCKDB_V2_ERROR duckdb_v2_instance_create(duckdb_v2_environment_handle env, duckdb_v2_instance_handle *out_instance, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_instance_destroy(duckdb_v2_instance_handle *instance);
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);
DUCKDB_V2_ERROR duckdb_v2_instance_detach(duckdb_v2_instance_handle instance, const duckdb_v2_identifier_t *name, duckdb_v2_error_info_handle *err);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_attach_options_destroy(duckdb_v2_attach_options_handle *options);
DUCKDB_V2_ERROR duckdb_v2_library_version(duckdb_v2_str *out_version, duckdb_v2_error_info_handle *err);
duckdb_v2_instance_create
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_instance_create(
duckdb_v2_environment_handle env,
duckdb_v2_instance_handle *out_instance,
duckdb_v2_error_info_handle *err
);
Parameters
env: The environment.out_instance: Receives the new instance handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_create_with_options
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
env: The environment.option_names: Optional. An array of option_count option names (canonical or alias). Pass NULL when option_count is 0.option_values: Optional. An array of option_count values, parallel to option_names, in the textual form SQLSETaccepts. Pass NULL when option_count is 0.option_count: The number of startup options.out_instance: Receives the new instance handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_instance_destroy(
duckdb_v2_instance_handle *instance
);
Parameters
instance: The instance handle to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_attach
Unstable since 2.0.0.
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.
nameis the name to attach under, likeATTACH ... AS name; it is howduckdb_v2_instance_detachandduckdb_v2_instance_set_defaultrefer to the database. Null, or an empty view, derives the name from the path the way SQLATTACHwithoutASdoes: memoryfor:memory:or an empty view;- otherwise the file name up to its first
., without any?queryparameters (/data/sales.2024.dbattaches assales), with_dbappended when that is a reserved name such assystemortemp. Naming is how two files with the same base name, or:memory:twice, attach side by side.optionsmay be null; it carries the(KEY value)options of SQLATTACH, for per-database options such as READ_ONLY, BLOCK_SIZE or ENCRYPTION_KEY, and must have been created from this instance handle.make_defaultmakes the attached database the default for connections created afterwards, exactly as aduckdb_v2_instance_set_defaultcall 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 toduckdb_v2_instance_create_with_options.
Syntax
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
);
Parameters
instance: The instance handle.name: Optional. The name to attach under; null or an empty view for the name derived from the path. Borrowed and copied.path: Path to the database file, or:memory:/ an empty view for an in-memory database.options: Optional attach options created frominstance, or null to attach with defaults under the derived name.make_default: Whether to make the attached database the default for connections created afterwards.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_detach
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_instance_detach(
duckdb_v2_instance_handle instance,
const duckdb_v2_identifier_t *name,
duckdb_v2_error_info_handle *err
);
Parameters
instance: The instance handle.name: The name the database is attached under. Borrowed.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_set_default
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance handle.name: The name the database is attached under. Borrowed.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_attach_options_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance handle the options will be used with.out_options: Receives the new options handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_attach_options_set
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
options: The attach options.key: The option name, e.g. READ_ONLY.setting: The option value, in the textual form a quoted SQL literal would carry.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_attach_options_destroy
Unstable since 2.0.0.
Destroys an attach options handle.
On success the slot is set to null. Safe to call on an already-null slot.
Syntax
DUCKDB_V2_ERROR duckdb_v2_attach_options_destroy(
duckdb_v2_attach_options_handle *options
);
Parameters
options: The attach options to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_library_version
Unstable since 2.0.0.
Returns the version of the linked DuckDB library.
Syntax
DUCKDB_V2_ERROR duckdb_v2_library_version(
duckdb_v2_str *out_version,
duckdb_v2_error_info_handle *err
);
Parameters
out_version: The version string. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Logging
DUCKDB_V2_LOG_LEVEL
Severity of a log message. Mirrors DuckDB's own log levels, and is compared against the configured threshold: an entry below it is dropped.
Values
DUCKDB_V2_LOG_LEVEL_TRACE= 10: Finest detail; off in any default configuration.DUCKDB_V2_LOG_LEVEL_DEBUG= 20: Diagnostic detail.DUCKDB_V2_LOG_LEVEL_INFO= 30: Ordinary progress information.DUCKDB_V2_LOG_LEVEL_WARNING= 40: A recoverable problem.DUCKDB_V2_LOG_LEVEL_ERROR= 50: An operation failed.DUCKDB_V2_LOG_LEVEL_FATAL= 60: An unrecoverable failure.
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);
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);
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);
duckdb_v2_context_log
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
ctx: The context to log through.level: Severity of the message.log_type: The log type to record under, matched case-sensitively. Empty selects the default type.message: The message body. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_log
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance to log through.level: Severity of the message.log_type: The log type to record under, matched case-sensitively. Empty selects the default type.message: The message body. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_log
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to log through.level: Severity of the message.log_type: The log type to record under, matched case-sensitively. Empty selects the default type.message: The message body. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Qualified Name
duckdb_v2_qname_handle
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.
DUCKDB_V2_ERROR duckdb_v2_qname_parse(const duckdb_v2_str *text, duckdb_v2_qname_handle *name, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_qname_get_part_count(duckdb_v2_qname_handle name, idx_t *count, duckdb_v2_error_info_handle *err);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_qname_hash(duckdb_v2_qname_handle name, uint64_t *hash, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_qname_destroy(duckdb_v2_qname_handle *name);
duckdb_v2_qname_parse
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_qname_parse(
const duckdb_v2_str *text,
duckdb_v2_qname_handle *name,
duckdb_v2_error_info_handle *err
);
Parameters
text: The name text to parse. Borrowed for the call only.name: On success, receives the qualified name. Owned by the caller; destroy viaduckdb_v2_qname_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_qname_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
parts: An array ofpart_countnon-empty identifier views, outermost first.part_count: The number of parts, between one and three.name: On success, receives the qualified name. Owned by the caller; destroy viaduckdb_v2_qname_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_qname_get_part_count
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_qname_get_part_count(
duckdb_v2_qname_handle name,
idx_t *count,
duckdb_v2_error_info_handle *err
);
Parameters
name: The qualified name.count: Receives the number of parts. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_qname_get_part
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
name: The qualified name.index: Zero-based part index.part: Receives a borrowed view of the part, valid until the qualified name is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_qname_render
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
name: The qualified name to render.out_text: Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required length in out_length. (out)out_capacity: Bytes available in out_text, terminator included. Ignored when out_text is NULL.out_length: Receives the text length excluding the null terminator — written on success and on ERROR_INPUT_OBJECT_SIZE. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_qname_equals
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
left: The first qualified name.right: The second qualified name.result: Receives whether the two names are equal. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_qname_hash
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_qname_hash(
duckdb_v2_qname_handle name,
uint64_t *hash,
duckdb_v2_error_info_handle *err
);
Parameters
name: The qualified name to hash.hash: Receives the hash value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_qname_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_qname_destroy(
duckdb_v2_qname_handle *name
);
Parameters
name: The qualified name to destroy.
Return Value
DUCKDB_V2_ERROR
Query Metrics
duckdb_v2_query_metrics_handle
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.
duckdb_v2_query_metrics_node_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.
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);
DUCKDB_V2_ERROR duckdb_v2_connection_enable_profiling(duckdb_v2_connection_handle conn, bool enabled, duckdb_v2_error_info_handle *err);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_query_metrics_destroy(duckdb_v2_query_metrics_handle *metrics);
duckdb_v2_connection_get_query_metrics
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to take the snapshot of.metrics: On success, receives the owned snapshot. Destroy viaduckdb_v2_query_metrics_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_enable_profiling
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_connection_enable_profiling(
duckdb_v2_connection_handle conn,
bool enabled,
duckdb_v2_error_info_handle *err
);
Parameters
conn: The connection to enable or disable profiling for.enabled: Whether to enable profiling.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_get_root
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
metrics: The snapshot.node: Receives the borrowed root node. Valid until the snapshot is destroyed. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_node_get_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
node: The node.name: Receives a borrowed view of the name. Valid until the snapshot is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_node_get_child_count
Unstable since 2.0.0.
Returns the number of children of the node. Valid indices for duckdb_v2_query_metrics_node_get_child are
[0, count).
Syntax
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
);
Parameters
node: The node.count: Receives the number of children. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_node_get_child
Unstable since 2.0.0.
Borrows the child of the node at index. An out-of-range index is rejected with ERROR_INPUT_OUT_OF_RANGE.
Syntax
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
);
Parameters
node: The node.index: Zero-based child index.child: Receives the borrowed child. Valid until the snapshot is destroyed. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_node_get_metric_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
node: The node.count: Receives the number of metrics. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_node_get_metric_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
node: The node.index: Zero-based metric index.name: Receives a borrowed view of the name. Valid until the snapshot is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_node_get_metric_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
node: The node.index: Zero-based metric index.value: Receives the owned value. Destroy viaduckdb_v2_value_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_node_get_metric
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
node: The node.name: The name of the metric, matched exactly. Borrowed for the call only.value: Receives the owned value, if present. Destroy viaduckdb_v2_value_destroy. (out)present: Receives whether the node carries the metric. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_query_metrics_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_query_metrics_destroy(
duckdb_v2_query_metrics_handle *metrics
);
Parameters
metrics: The snapshot to destroy.
Return Value
DUCKDB_V2_ERROR
Schema
duckdb_v2_schema_handle
An owned, ordered list of (name, type) fields. Read with schema_get_count and schema_get_field. Destroy via schema_destroy.
DUCKDB_V2_ERROR duckdb_v2_schema_get_count(duckdb_v2_schema_handle schema, idx_t *out_count, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_schema_destroy(duckdb_v2_schema_handle *schema);
duckdb_v2_schema_get_count
Unstable since 2.0.0.
Returns the number of fields in a schema.
Syntax
DUCKDB_V2_ERROR duckdb_v2_schema_get_count(
duckdb_v2_schema_handle schema,
idx_t *out_count,
duckdb_v2_error_info_handle *err
);
Parameters
schema: The schema.out_count: Receives the field count. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_schema_get_field
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
schema: The schema.index: Zero-based field index.out_name: Receives a borrowed view of the field name. Valid until the schema is destroyed. (out, borrowed)out_type: Receives a borrowed field type. Valid until the schema is destroyed; do not destroy it. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_schema_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_schema_destroy(
duckdb_v2_schema_handle *schema
);
Parameters
schema: The schema handle to destroy.
Return Value
DUCKDB_V2_ERROR
Tokenizer
duckdb_v2_token_iterator_handle
An opaque, owned handle to an iterator over the tokens of a SQL string, produced by tokenize_sql.
DUCKDB_V2_TOKEN_TYPE
The lexical class of a token.
Values
DUCKDB_V2_TOKEN_TYPE_INVALID= 0: Not an actual token class; out_type is set to this whenduckdb_v2_token_iterator_nextfails.DUCKDB_V2_TOKEN_TYPE_KEYWORD= 1: A keyword of the connection's grammar.DUCKDB_V2_TOKEN_TYPE_IDENTIFIER= 2: A bare or double-quoted identifier, quotes included.DUCKDB_V2_TOKEN_TYPE_STRING_LITERAL= 3: A quoted or dollar-quoted string, delimiters included.DUCKDB_V2_TOKEN_TYPE_NUMBER_LITERAL= 4: A numeric literal.DUCKDB_V2_TOKEN_TYPE_OPERATOR= 5: An operator or punctuation run other than the statement terminator.DUCKDB_V2_TOKEN_TYPE_COMMENT= 6: A line or block comment, delimiters included.DUCKDB_V2_TOKEN_TYPE_TERMINATOR= 7: A statement-terminating semicolon.DUCKDB_V2_TOKEN_TYPE_END_OF_INPUT= 8: 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_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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_token_iterator_destroy(duckdb_v2_token_iterator_handle *iterator);
duckdb_v2_tokenize_sql
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection supplying the grammar.sql: The SQL text. Borrowed for the call only; may contain interior null bytes. {NULL, 0} is the empty input.out_iterator: Receives the new iterator handle. Destroy via token_iterator_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_token_iterator_next
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
iterator: The iterator to advance.out_type: Receives the token's class, or TOKEN_TYPE_END_OF_INPUT once exhausted. (out)out_start: Receives the token's byte offset into the input; the input length for END_OF_INPUT. (out)out_length: Receives the token's byte length; 0 for END_OF_INPUT. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_token_iterator_ends_unterminated
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
iterator: The iterator.out_ends_unterminated: Receives whether the input ended inside an open token. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_token_iterator_destroy
Unstable since 2.0.0.
Destroys a token iterator handle.
Syntax
DUCKDB_V2_ERROR duckdb_v2_token_iterator_destroy(
duckdb_v2_token_iterator_handle *iterator
);
Parameters
iterator: The iterator to destroy.
Return Value
DUCKDB_V2_ERROR
Aggregate
duckdb_v2_aggregate_function_handle
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.
duckdb_v2_aggregate_function_bind_info_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.
duckdb_v2_aggregate_function_size_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.
duckdb_v2_aggregate_function_init_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.
duckdb_v2_aggregate_function_update_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.
duckdb_v2_aggregate_function_combine_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.
duckdb_v2_aggregate_function_finalize_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.
duckdb_v2_aggregate_function_destroy_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.
duckdb_v2_aggregate_function_bind_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the arguments of the call site being bound, the user data and the bind data.result: Borrowed opaque handle to set the return type of the call site being bound through.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_aggregate_function_size_callback_fn
Syntax
typedef void (*duckdb_v2_aggregate_function_size_callback_fn)(
duckdb_v2_aggregate_function_size_info_handle info,
duckdb_v2_error_info_handle *err
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_aggregate_function_init_callback_fn
Syntax
typedef void (*duckdb_v2_aggregate_function_init_callback_fn)(
duckdb_v2_aggregate_function_init_info_handle info,
duckdb_v2_error_info_handle *err
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_aggregate_function_update_callback_fn
Syntax
typedef void (*duckdb_v2_aggregate_function_update_callback_fn)(
duckdb_v2_aggregate_function_update_info_handle info,
duckdb_v2_error_info_handle *err
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_aggregate_function_combine_callback_fn
Syntax
typedef void (*duckdb_v2_aggregate_function_combine_callback_fn)(
duckdb_v2_aggregate_function_combine_info_handle info,
duckdb_v2_error_info_handle *err
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_aggregate_function_finalize_callback_fn
Syntax
typedef void (*duckdb_v2_aggregate_function_finalize_callback_fn)(
duckdb_v2_aggregate_function_finalize_info_handle info,
duckdb_v2_error_info_handle *err
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_aggregate_function_destroy_callback_fn
Syntax
typedef void (*duckdb_v2_aggregate_function_destroy_callback_fn)(
duckdb_v2_aggregate_function_destroy_info_handle info,
duckdb_v2_error_info_handle *err
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.err: Borrowed error info handle to use to report errors that occur during the callback. Errors reported by this callback are ignored.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_aggregate_function_destroy(duckdb_v2_aggregate_function_handle *function);
duckdb_v2_aggregate_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the aggregate function through.function: On success, receives the newly created aggregate function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_get_docs
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the documentation of.docs: The returned documentation. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_get_signature
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the signature of.sig: The returned signature. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_property
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the property of.key: The property to set.value: The value to set for the property. Must belong tokey.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_bind_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the bind callback of.callback: The bind callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_size_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the size callback of.callback: The size callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_init_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the init callback of.callback: The init callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_update_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the update callback of.callback: The update callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_combine_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the combine callback of.callback: The combine callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_finalize_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the finalize callback of.callback: The finalize callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_set_destroy_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the destroy callback of.callback: The destroy callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_bind_set_return_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.return_type: The return type to set. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_size_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_aggregate_function_set_user_data.
Syntax
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
);
Parameters
info: The size info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_size_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The size info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_size_set_state_size
Unstable since 2.0.0.
Sets the size of a single aggregate state, in bytes. The size callback must set this; DuckDB uses it to allocate state memory.
Syntax
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
);
Parameters
info: The size info handle.size: The size of a single aggregate state, in bytes.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_init_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_aggregate_function_set_user_data.
Syntax
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
);
Parameters
info: The init info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_init_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The init info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_init_get_state_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The init info handle.count: Receives the number of states. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_init_get_states
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The init info handle.states: Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_update_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_aggregate_function_set_user_data.
Syntax
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
);
Parameters
info: The update info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_update_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The update info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_update_get_row_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The update info handle.count: Receives the number of rows. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_update_get_arg_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The update info handle.positional_fixed: Optional. Receives the number of positional-only and standard parameters. (out)positional_variadic: Optional. Receives the number of arguments*argsreceived, 0 when the signature has none. (out)named_fixed: Optional. Receives the number of named-only parameters. (out)named_variadic: Optional. Receives the number of arguments**kwargsreceived, 0 when the signature has none. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_update_get_arg
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The update info handle.index: The index of the argument.vector: Receives the borrowed argument vector. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_update_get_states
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The update info handle.states: Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_combine_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_aggregate_function_set_user_data.
Syntax
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
);
Parameters
info: The combine info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_combine_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The combine info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_combine_get_state_count
Unstable since 2.0.0.
Returns how many source/target state pairs this invocation must combine. This is the length of both the sources and the targets array.
Syntax
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
);
Parameters
info: The combine info handle.count: Receives the number of state pairs. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_combine_get_sources
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The combine info handle.states: Receives the array of source aggregate state pointers. Borrowed; valid only for the duration of the callback. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_combine_get_targets
Unstable since 2.0.0.
Returns the array of target aggregate states, one pointer per pair. Source i must be combined into target i.
Syntax
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
);
Parameters
info: The combine info handle.states: Receives the array of target aggregate state pointers. Borrowed; valid only for the duration of the callback. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_finalize_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_aggregate_function_set_user_data.
Syntax
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
);
Parameters
info: The finalize info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_finalize_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The finalize info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_finalize_get_state_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The finalize info handle.count: Receives the number of states. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_finalize_get_states
Unstable since 2.0.0.
Returns the array of aggregate states to finalize, one pointer per state. State i must be finalized into result row offset + i.
Syntax
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
);
Parameters
info: The finalize info handle.states: Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_finalize_get_result
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The finalize info handle.vector: Receives the borrowed result vector to write into. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_finalize_get_result_offset
Unstable since 2.0.0.
Returns the offset in the result vector at which to start writing: state i must be finalized into result row offset + i.
Syntax
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
);
Parameters
info: The finalize info handle.offset: Receives the result offset. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_destroy_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_aggregate_function_set_user_data.
Syntax
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
);
Parameters
info: The destroy info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_destroy_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The destroy info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_destroy_get_state_count
Unstable since 2.0.0.
Returns how many aggregate states this invocation must destroy. This is the length of the state array.
Syntax
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
);
Parameters
info: The destroy info handle.count: Receives the number of states. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_destroy_get_states
Unstable since 2.0.0.
Returns the array of aggregate states to destroy, one pointer per state. The callback must release any resources the states own.
Syntax
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
);
Parameters
info: The destroy info handle.states: Receives the array of aggregate state pointers. Borrowed; valid only for the duration of the callback. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_aggregate_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.function: The aggregate function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_aggregate_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The aggregate function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_aggregate_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_aggregate_function_destroy(
duckdb_v2_aggregate_function_handle *function
);
Parameters
function: The function to destroy.
Return Value
DUCKDB_V2_ERROR
Catalog
duckdb_v2_table_description_handle
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.
duckdb_v2_column_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.
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);
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);
DUCKDB_V2_ERROR duckdb_v2_table_description_is_readonly(duckdb_v2_table_description_handle desc, bool *readonly, duckdb_v2_error_info_handle *err);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_table_description_destroy(duckdb_v2_table_description_handle *desc);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_column_description_has_default(duckdb_v2_column_description_handle column, bool *has_default, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_column_description_has_generated(duckdb_v2_column_description_handle column, bool *has_generated, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_column_description_destroy(duckdb_v2_column_description_handle *column);
duckdb_v2_connection_describe_table
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection whose catalogs and search path resolve the name.name: The possibly partial table name to resolve. Borrowed for the call only.desc: On success, receives the owned description. Destroy viaduckdb_v2_table_description_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_description_get_qname
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
desc: The description.name: Receives the owned resolved name. Destroy viaduckdb_v2_qname_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_description_is_readonly
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_table_description_is_readonly(
duckdb_v2_table_description_handle desc,
bool *readonly,
duckdb_v2_error_info_handle *err
);
Parameters
desc: The description.readonly: Receives whether the catalog is read-only. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_description_get_column_count
Unstable since 2.0.0.
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).
Syntax
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
);
Parameters
desc: The description.count: Receives the column count. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_description_get_column
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
desc: The description.index: Zero-based column index.column: Receives the owned column description. Destroy viaduckdb_v2_column_description_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_description_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_table_description_destroy(
duckdb_v2_table_description_handle *desc
);
Parameters
desc: The description to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_description_get_name
Unstable since 2.0.0.
Borrows the name of the column.
The name carries the casing the column was declared with.
Syntax
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
);
Parameters
column: The column description.name: Receives a borrowed view of the column name. Valid until the column description is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_description_get_type
Unstable since 2.0.0.
Borrows the type of the column.
Syntax
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
);
Parameters
column: The column description.type: Receives the borrowed column type. Valid until the column description is destroyed; do not destroy it. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_description_has_default
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_description_has_default(
duckdb_v2_column_description_handle column,
bool *has_default,
duckdb_v2_error_info_handle *err
);
Parameters
column: The column description.has_default: Receives whether the column has a default value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_description_has_generated
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_description_has_generated(
duckdb_v2_column_description_handle column,
bool *has_generated,
duckdb_v2_error_info_handle *err
);
Parameters
column: The column description.has_generated: Receives whether the column is generated. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_column_description_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_column_description_destroy(
duckdb_v2_column_description_handle *column
);
Parameters
column: The column description to destroy.
Return Value
DUCKDB_V2_ERROR
Copy
duckdb_v2_copy_function_handle
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.
duckdb_v2_copy_to_bind_info_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.
duckdb_v2_copy_to_batch_size_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.
duckdb_v2_copy_to_init_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.
duckdb_v2_copy_to_batch_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.
duckdb_v2_copy_to_flush_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.
duckdb_v2_copy_to_finalize_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.
duckdb_v2_copy_to_statistics_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.
duckdb_v2_copy_from_bind_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.
duckdb_v2_copy_from_init_global_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.
duckdb_v2_copy_from_init_local_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.
duckdb_v2_copy_from_exec_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.
duckdb_v2_copy_from_progress_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.
duckdb_v2_copy_to_bind_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_to_batch_size_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_to_init_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_to_batch_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_to_flush_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_to_finalize_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_to_statistics_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_from_bind_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_from_init_global_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_from_init_local_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_from_exec_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_copy_from_progress_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_copy_function_destroy(duckdb_v2_copy_function_handle *function);
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);
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);
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);
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);
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);
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);
duckdb_v2_copy_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the copy function through.function: On success, receives the newly created copy function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_function_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_function_set_file_extension
Unstable since 2.0.0.
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..
Syntax
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
);
Parameters
function: The function to set the file extension of.extension: The extension to set, without the leading dot. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_function_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_set_bind_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_set_batch_size_callback
Unstable since 2.0.0.
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).
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_set_init_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_set_batch_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_set_flush_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_set_finalize_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The bind info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_set_bind_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.data: Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_file_path
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.path: Receives a borrowed view of the file path. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_column_count
Unstable since 2.0.0.
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).
Syntax
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
);
Parameters
info: The bind info handle.count: Receives the number of columns. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_column_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the column to get the type of.type: Receives the column type. Owned by the caller; destroy viaduckdb_v2_logical_type_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_column_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the column to get the name of.name: Receives a borrowed view of the column name. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_option_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.count: Receives the number of options. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_option_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the option to get the name of.name: Receives a borrowed view of the option name. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_bind_get_option_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the option.value: Receives the option's value. Owned by the caller; destroy viaduckdb_v2_value_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_size_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The batch size info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_size_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... TO bind callback.
Syntax
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
);
Parameters
info: The batch size info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_size_set_target
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The batch size info handle.rows: The number of rows a batch should carry. Must be greater than 0.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_init_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The init info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_init_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... TO bind callback.
Syntax
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
);
Parameters
info: The init info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_init_get_file_path
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The init info handle.path: Receives a borrowed view of the file path. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_init_set_init_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The init info handle.data: Opaque handle bundling the init data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The batch info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... TO bind callback.
Syntax
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
);
Parameters
info: The batch info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_get_init_data
Unstable since 2.0.0.
Retrieves the init data set by the function's COPY ... TO init callback for the file this batch belongs to.
Syntax
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
);
Parameters
info: The batch info handle.data: Receives the init data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_take_input
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The batch info handle.collection: Receives the collection holding the rows of the batch. Owned by the caller; destroy viaduckdb_v2_column_data_collection_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_batch_set_batch_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The batch info handle.data: Opaque handle bundling the batch data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_flush_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The flush info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_flush_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... TO bind callback.
Syntax
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
);
Parameters
info: The flush info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_flush_get_init_data
Unstable since 2.0.0.
Retrieves the init data set by the function's COPY ... TO init callback for the file this batch belongs to.
Syntax
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
);
Parameters
info: The flush info handle.data: Receives the init data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_flush_get_batch_data
Unstable since 2.0.0.
Retrieves the batch data set by the function's batch callback for the batch being flushed.
Syntax
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
);
Parameters
info: The flush info handle.data: Receives the batch data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_finalize_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The finalize info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_finalize_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... TO bind callback.
Syntax
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
);
Parameters
info: The finalize info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_finalize_get_init_data
Unstable since 2.0.0.
Retrieves the init data set by the function's COPY ... TO init callback for the file being finalized.
Syntax
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
);
Parameters
info: The finalize info handle.data: Receives the init data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_set_bind_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_set_init_global_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_set_init_local_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_set_exec_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_set_progress_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The bind info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_set_bind_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.data: Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_file_path
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.path: Receives a borrowed view of the file path. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_column_count
Unstable since 2.0.0.
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).
Syntax
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
);
Parameters
info: The bind info handle.count: Receives the number of columns. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_column_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the column to get the type of.type: Receives the column type. Owned by the caller; destroy viaduckdb_v2_logical_type_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_column_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the column to get the name of.name: Receives a borrowed view of the column name. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_option_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.count: Receives the number of options. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_option_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the option to get the name of.name: Receives a borrowed view of the option name. Valid only for the duration of the callback. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_get_option_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.index: The index of the option.value: Receives the option's value. Owned by the caller; destroy viaduckdb_v2_value_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_bind_set_cardinality
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.cardinality: The estimated number of rows.is_exact: Whether the estimate is exact, which also makes it an upper bound on the row count.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_global_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The global init info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_global_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... FROM bind callback.
Syntax
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
);
Parameters
info: The global init info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_global_set_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The global init info handle.data: Opaque handle bundling the global state pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_global_set_max_threads
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The global init info handle.max_threads: The maximum number of threads. Must be at least 1.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_local_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The local init info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_local_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... FROM bind callback.
Syntax
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
);
Parameters
info: The local init info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_local_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The local init info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_init_local_set_local_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The local init info handle.data: Opaque handle bundling the local state pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_exec_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_exec_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... FROM bind callback.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_exec_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_exec_get_local_state
Unstable since 2.0.0.
Retrieves the worker-local local state set by the function's local init callback.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the local state pointer for the executing thread, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_exec_get_output_chunk
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.chunk: Receives the borrowed output chunk to write into. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_progress_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The progress info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_progress_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... FROM bind callback.
Syntax
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
);
Parameters
info: The progress info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_progress_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The progress info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_from_progress_set_progress
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The progress info handle.progress: The fraction of the read that is complete, in [0.0, 1.0].err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_copy_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.function: The copy function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_copy_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The copy function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_copy_function_destroy(
duckdb_v2_copy_function_handle *function
);
Parameters
function: The function to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_set_statistics_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_statistics_get_user_data
Unstable since 2.0.0.
Retrieves the user data set on the copy function via duckdb_v2_copy_function_set_user_data.
Syntax
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
);
Parameters
info: The statistics info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_statistics_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's COPY ... TO bind callback.
Syntax
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
);
Parameters
info: The statistics info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_statistics_get_init_data
Unstable since 2.0.0.
Retrieves the init data set by the function's COPY ... TO init callback for the file being reported.
Syntax
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
);
Parameters
info: The statistics info handle.data: Receives the init data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_statistics_set_row_count
Unstable since 2.0.0.
Reports how many rows were written to the file. Reported as 0 when the callback does not set it.
Syntax
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
);
Parameters
info: The statistics info handle.row_count: The number of rows written to the file.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_copy_to_statistics_set_file_size
Unstable since 2.0.0.
Reports the size of the written file in bytes. Reported as 0 when the callback does not set it.
Syntax
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
);
Parameters
info: The statistics info handle.file_size_bytes: The size of the file in bytes.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
Custom Option
duckdb_v2_custom_option_handle
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.
duckdb_v2_custom_option_update_info_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.
duckdb_v2_custom_option_update_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the update and the user data.context: Borrowed handle to the context setting the option. When the option is written through the config of an instance, or given at startup, this is an internal context rather than a user's connection: its session state is discarded after the update.err: Borrowed error info handle to use to report errors that occur during the callback. Reporting an error refuses the update: the option keeps its previous value.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_custom_option_destroy(duckdb_v2_custom_option_handle *option);
duckdb_v2_custom_option_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the custom option through.option: On success, receives the newly created custom option. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to set the type of.type: The type to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_default_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to set the default value of.value: The default value. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_description
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to set the description of.description: The description to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_default_scope
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to set the default scope of.scope: The default scope, GLOBAL or SESSION.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_supports_scope
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to configure.scope: The scope, GLOBAL or SESSION.supported: Whether the option can be written at the scope.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_set_update_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
option: The option to set the update callback of.callback: The update callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_update_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_custom_option_set_user_data.
Syntax
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
);
Parameters
info: The update info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_update_get_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The update info handle.value: Receives the new value. Owned by the caller; destroy viaduckdb_v2_value_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_update_set_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The update info handle.value: The value to store instead. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_update_get_scope
Unstable since 2.0.0.
Retrieves the scope the value is written at: GLOBAL or SESSION, a DEFAULT write already resolved to the option's default scope.
Syntax
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
);
Parameters
info: The update info handle.scope: Receives the scope. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_update_is_reset
Unstable since 2.0.0.
Retrieves whether the update is a reset to the default value, like SQL RESET.
Syntax
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
);
Parameters
info: The update info handle.is_reset: Receives whether the update is a reset. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_custom_option
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.option: The custom option to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_custom_option
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.option: The custom option to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_custom_option_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_custom_option_destroy(
duckdb_v2_custom_option_handle *option
);
Parameters
option: The option to destroy.
Return Value
DUCKDB_V2_ERROR
Expression
duckdb_v2_expression_handle
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.
DUCKDB_V2_EXPRESSION_TYPE
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.
Values
DUCKDB_V2_EXPRESSION_TYPE_INVALID= 0: A node type this API does not model. Its children can still be walked.DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_CAST= 12: A cast. One child; the target type is the node's return type andduckdb_v2_expression_cast_get_modetells aTRY_CASTapart.DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_NOT= 13: LogicalNOT. One child.DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_IS_NULL= 14:IS NULL. One child.DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_IS_NOT_NULL= 15:IS NOT NULL. One child.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:>=. Two children.DUCKDB_V2_EXPRESSION_TYPE_COMPARE_IN= 35:IN. The first child is the value tested, the remaining children are the candidates.DUCKDB_V2_EXPRESSION_TYPE_COMPARE_NOT_IN= 36:NOT IN. The first child is the value tested, the remaining children are the candidates.DUCKDB_V2_EXPRESSION_TYPE_COMPARE_DISTINCT_FROM= 37:IS DISTINCT FROM. Two children.DUCKDB_V2_EXPRESSION_TYPE_COMPARE_BETWEEN= 38:BETWEEN. Three children: the value tested, the lower bound and the upper bound.DUCKDB_V2_EXPRESSION_TYPE_COMPARE_NOT_DISTINCT_FROM= 40:IS NOT DISTINCT FROM. Two children.DUCKDB_V2_EXPRESSION_TYPE_CONJUNCTION_AND= 50: LogicalAND. Two or more children.DUCKDB_V2_EXPRESSION_TYPE_CONJUNCTION_OR= 51: LogicalOR. Two or more children.DUCKDB_V2_EXPRESSION_TYPE_VALUE_CONSTANT= 75: A constant. No children; read it withduckdb_v2_expression_constant_get_value.DUCKDB_V2_EXPRESSION_TYPE_VALUE_PARAMETER= 76: A prepared statement parameter whose value is not known yet. No children.DUCKDB_V2_EXPRESSION_TYPE_BOUND_FUNCTION= 141: A call to a scalar function other than the ones listed above. The children are its arguments; read the name withduckdb_v2_expression_function_get_name.DUCKDB_V2_EXPRESSION_TYPE_CASE_EXPR= 150: ACASEexpression. The children are eachWHENcondition followed by itsTHENresult, then theELSEresult.DUCKDB_V2_EXPRESSION_TYPE_OPERATOR_COALESCE= 152:COALESCE. One or more children.DUCKDB_V2_EXPRESSION_TYPE_BOUND_COLUMN_REF= 228: A reference to a column. No children; read it withduckdb_v2_expression_column_ref_get_index.
DUCKDB_V2_ERROR duckdb_v2_expression_get_type(duckdb_v2_expression_handle expression, DUCKDB_V2_EXPRESSION_TYPE *type, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_expression_get_child_count(duckdb_v2_expression_handle expression, idx_t *count, duckdb_v2_error_info_handle *err);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_expression_column_ref_get_index(duckdb_v2_expression_handle expression, idx_t *index, duckdb_v2_error_info_handle *err);
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);
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);
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);
duckdb_v2_expression_get_type
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_expression_get_type(
duckdb_v2_expression_handle expression,
DUCKDB_V2_EXPRESSION_TYPE *type,
duckdb_v2_error_info_handle *err
);
Parameters
expression: The expression node.type: Receives the node type. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_get_return_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
expression: The expression node.type: Receives the owned logical type. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_get_child_count
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_expression_get_child_count(
duckdb_v2_expression_handle expression,
idx_t *count,
duckdb_v2_error_info_handle *err
);
Parameters
expression: The expression node.count: Receives the number of children. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_get_child
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
expression: The expression node.index: The index of the child to retrieve.child: Receives the borrowed child node. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_constant_get_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
expression: The constant node.value: Receives the owned constant value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_column_ref_get_index
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_expression_column_ref_get_index(
duckdb_v2_expression_handle expression,
idx_t *index,
duckdb_v2_error_info_handle *err
);
Parameters
expression: The column reference node.index: Receives the column index. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_function_get_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
expression: The function node.name: Receives a borrowed view of the function name. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_function_get_qname
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
expression: The function node.name: Receives the owned qualified name. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_expression_cast_get_mode
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
expression: The cast node.mode: Receives the cast mode. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
Log Sink
duckdb_v2_log_sink_handle
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.
duckdb_v2_log_sink_write_info_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.
duckdb_v2_log_sink_flush_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.
duckdb_v2_log_sink_write_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle to the context of the entry, giving access to its ids.user_data: The user data set viaduckdb_v2_log_sink_set_user_data, or null if none was set.timestamp: When the entry was written, as a TIMESTAMP WITH TIME ZONE - microseconds since the epoch.level: The severity of the entry.scope: The scope the entry was written in, which decides which of its ids are present.type: The log type the entry was written under, e.g.QueryLog. Borrowed for the duration of the call.message: The message of the entry. Borrowed for the duration of the call.err: Borrowed error info handle to report a failure to receive the entry through. A reported error drops the entry; it never fails the operation that logged.
duckdb_v2_log_sink_flush_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle to the flush. Carries nothing yet.user_data: The user data set viaduckdb_v2_log_sink_set_user_data, or null if none was set.err: Borrowed error info handle to report a failure to flush through. A reported error is dropped; it never fails the operation that flushed.
DUCKDB_V2_LOG_SCOPE
The scope a log entry was written in, which decides which of its ids are present.
Values
DUCKDB_V2_LOG_SCOPE_DATABASE= 10: Written for the database as a whole, carrying no connection, transaction or query id.DUCKDB_V2_LOG_SCOPE_CONNECTION= 20: Written by a connection, carrying its connection id and, inside one, the transaction and query ids.DUCKDB_V2_LOG_SCOPE_THREAD= 30: Written by a thread executing a query, carrying the thread id next to the connection's ids.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_log_sink_destroy(duckdb_v2_log_sink_handle *sink);
duckdb_v2_log_sink_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the log sink through.sink: On success, receives the newly created log sink. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
sink: The log sink to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
sink: The log sink to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_set_write_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
sink: The log sink to set the write callback of.callback: The write callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_set_flush_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
sink: The log sink to set the flush callback of.callback: The flush callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_write_info_get_connection_id
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The write info handle of the entry.id: Receives the connection id, if present. (out)present: Receives whether the entry has a connection id. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_write_info_get_transaction_id
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The write info handle of the entry.id: Receives the transaction id, if present. (out)present: Receives whether the entry has a transaction id. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_write_info_get_query_id
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The write info handle of the entry.id: Receives the query id, if present. (out)present: Receives whether the entry has a query id. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_write_info_get_thread_id
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The write info handle of the entry.id: Receives the thread id, if present. (out)present: Receives whether the entry has a thread id. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_register_log_sink
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance to register on.sink: The log sink to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_log_sink
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.sink: The log sink to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_log_sink_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_log_sink_destroy(
duckdb_v2_log_sink_handle *sink
);
Parameters
sink: The log sink to destroy.
Return Value
DUCKDB_V2_ERROR
Logical Type
DUCKDB_V2_LOGICAL_TYPE_ID
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.
Values
DUCKDB_V2_LOGICAL_TYPE_ID_INVALID= 0: Invalid / unset.DUCKDB_V2_LOGICAL_TYPE_ID_SQLNULL= 1: NULL constant type.DUCKDB_V2_LOGICAL_TYPE_ID_UNKNOWN= 2: Unknown — used for unresolved parameter expressions.DUCKDB_V2_LOGICAL_TYPE_ID_ANY= 3: ANY — used for functions that accept any type.DUCKDB_V2_LOGICAL_TYPE_ID_TYPE= 6: A type carried as a value (type parameters). Values of this type are built via value_create_type.DUCKDB_V2_LOGICAL_TYPE_ID_BOOLEAN= 10DUCKDB_V2_LOGICAL_TYPE_ID_TINYINT= 11DUCKDB_V2_LOGICAL_TYPE_ID_SMALLINT= 12DUCKDB_V2_LOGICAL_TYPE_ID_INTEGER= 13DUCKDB_V2_LOGICAL_TYPE_ID_BIGINT= 14DUCKDB_V2_LOGICAL_TYPE_ID_DATE= 15: 32-bit days since epoch.DUCKDB_V2_LOGICAL_TYPE_ID_TIME= 16: 64-bit microseconds since midnight.DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_SEC= 17: 64-bit seconds since epoch.DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_MS= 18: 64-bit milliseconds since epoch.DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP= 19: 64-bit microseconds since epoch.DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_NS= 20: 64-bit nanoseconds since epoch.DUCKDB_V2_LOGICAL_TYPE_ID_DECIMAL= 21: Decimal with width and scale parameters.DUCKDB_V2_LOGICAL_TYPE_ID_FLOAT= 22DUCKDB_V2_LOGICAL_TYPE_ID_DOUBLE= 23DUCKDB_V2_LOGICAL_TYPE_ID_VARCHAR= 25DUCKDB_V2_LOGICAL_TYPE_ID_BLOB= 26DUCKDB_V2_LOGICAL_TYPE_ID_INTERVAL= 27DUCKDB_V2_LOGICAL_TYPE_ID_UTINYINT= 28DUCKDB_V2_LOGICAL_TYPE_ID_USMALLINT= 29DUCKDB_V2_LOGICAL_TYPE_ID_UINTEGER= 30DUCKDB_V2_LOGICAL_TYPE_ID_UBIGINT= 31DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_TZ= 32: 64-bit microseconds since epoch, timezone-aware.DUCKDB_V2_LOGICAL_TYPE_ID_TIMESTAMP_TZ_NS= 33: 64-bit nanoseconds since epoch, timezone-aware.DUCKDB_V2_LOGICAL_TYPE_ID_TIME_TZ= 34: 64-bit microseconds since midnight + 32-bit offset.DUCKDB_V2_LOGICAL_TYPE_ID_TIME_NS= 35: 64-bit nanoseconds since midnight.DUCKDB_V2_LOGICAL_TYPE_ID_BIT= 36DUCKDB_V2_LOGICAL_TYPE_ID_BIGNUM= 39: Arbitrary-precision integer (VARINT-encoded).DUCKDB_V2_LOGICAL_TYPE_ID_UHUGEINT= 49DUCKDB_V2_LOGICAL_TYPE_ID_HUGEINT= 50DUCKDB_V2_LOGICAL_TYPE_ID_UUID= 54DUCKDB_V2_LOGICAL_TYPE_ID_GEOMETRY= 60: Geometry (spatial extension).DUCKDB_V2_LOGICAL_TYPE_ID_STRUCT= 100DUCKDB_V2_LOGICAL_TYPE_ID_LIST= 101DUCKDB_V2_LOGICAL_TYPE_ID_MAP= 102DUCKDB_V2_LOGICAL_TYPE_ID_ENUM= 104DUCKDB_V2_LOGICAL_TYPE_ID_UNION= 107DUCKDB_V2_LOGICAL_TYPE_ID_ARRAY= 108DUCKDB_V2_LOGICAL_TYPE_ID_VARIANT= 109DUCKDB_V2_LOGICAL_TYPE_ID_TUPLE= 110: Unnamed struct; shares the physical representation of STRUCT.
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_logical_type_destroy(duckdb_v2_logical_type_handle *type);
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);
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);
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);
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);
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);
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);
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);
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);
duckdb_v2_factory_create_type_from_id
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to resolve the type in.type_id: The type id to instantiate.param_names: Optional. An array of param_count parameter names; a {NULL, 0} entry is positional. Pass NULL for all-positional parameters.param_values: An array of param_count parameter values. Borrowed (copied in). Pass NULL when param_count is 0.param_count: The number of parameters. 0 instantiates a parameterless primitive.out_type: Receives the new logical type handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_factory_create_type_from_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to resolve the type in.name: The type name to resolve. Parts are matched case-insensitively; qualify it to name a type in a particular catalog or schema.param_names: Optional. An array of param_count parameter names; a {NULL, 0} entry is positional. Pass NULL for all-positional parameters.param_values: An array of param_count parameter values. Borrowed (copied in). Pass NULL when param_count is 0.param_count: The number of parameters.out_type: Receives the new logical type handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_factory_create_type_from_text
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to resolve the type in.text: View of the SQL type expression to parse.out_type: Receives the new logical type handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_copy
Unstable since 2.0.0.
Creates a copy of a logical type.
On success, writes the new caller-owned handle into *out_type; destroy it via logical_type_destroy.
Syntax
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
);
Parameters
type: The logical type to copy.out_type: Receives the new logical type handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_logical_type_destroy(
duckdb_v2_logical_type_handle *type
);
Parameters
type: The logical type to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_is_equal
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
left: The first logical type.right: The second logical type.result: Receives the result of the comparison. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_get_id
Unstable since 2.0.0.
Returns the logical type id.
Syntax
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
);
Parameters
type: The logical type.out_id: Receives the type id. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_get_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
type: The logical type.out_name: Receives a borrowed view of the name (alias when set, else the id's canonical name). (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_to_text
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
type: The logical type.out_text: Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required length in out_length. (out)out_capacity: Bytes available in out_text, terminator included. Ignored when out_text is NULL.out_length: Receives the text length excluding the null terminator — written on success and on ERROR_INPUT_OBJECT_SIZE. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_get_param_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
type: The logical type.out_count: Receives the number of parameters. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_logical_type_get_param
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
type: The logical type.index: The parameter index, in [0, param_count).out_name: Receives a borrowed view of the parameter name, or the empty view {NULL, 0} for a positional parameter. (out, borrowed)out_value: Receives the owned parameter value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_factory_create_type_with_alias
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to resolve the type in.base_type: The logical type to alias. Typically the base type supplied in the custom type bind info.alias_name: The name for the resulting type. Typically the name of the custom type being constructed, also available from the bind info.out_type: Receives the new type: the base type's internal representation under the given alias name. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_factory_create_common_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to resolve the type in.types: An array of type_count logical types. Borrowed.type_count: The number of types. Must be at least 1.out_type: Receives the new logical type handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Macro
duckdb_v2_macro_function_handle
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.
DUCKDB_V2_MACRO_FUNCTION_TYPE
The kind of a macro function, deciding how its body is read. Pass one to duckdb_v2_macro_function_create.
Values
DUCKDB_V2_MACRO_FUNCTION_TYPE_SCALAR= 0: A scalar macro. The body is a single expression, and the macro is called like a scalar function.DUCKDB_V2_MACRO_FUNCTION_TYPE_TABLE= 1: A table macro. The body is a single SELECT query, and the macro is called like a table function.
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_macro_function_destroy(duckdb_v2_macro_function_handle *function);
duckdb_v2_macro_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the macro function through.type: Whether the macro is a scalar or a table macro.function: On success, receives the newly created macro function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_macro_function_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The macro function to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_macro_function_set_body
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The macro function to set the body of.body: The SQL text of the body. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_macro_function_get_signature
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The macro function to get the signature of.sig: The returned signature. Borrowed and valid for the lifetime of the macro function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_macro_function_get_docs
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The macro function to get the documentation of.docs: The returned documentation. Borrowed and valid for the lifetime of the macro function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_macro_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The macro function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_macro_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_macro_function_destroy(
duckdb_v2_macro_function_handle *function
);
Parameters
function: The macro function to destroy.
Return Value
DUCKDB_V2_ERROR
Pragma
duckdb_v2_pragma_function_handle
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.
duckdb_v2_pragma_function_query_info_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.
duckdb_v2_pragma_function_query_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the arguments of thePRAGMAstatement and the user data.result: Borrowed opaque handle to set the query to run in place of thePRAGMAstatement through.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_pragma_function_exec_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the arguments of thePRAGMAstatement and the user data.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_pragma_function_destroy(duckdb_v2_pragma_function_handle *function);
duckdb_v2_pragma_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the pragma function through.function: On success, receives the newly created pragma function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_get_docs
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the documentation of.docs: The returned documentation. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_get_signature
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the signature of.sig: The returned signature. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_set_query_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the query callback of.callback: The query callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_set_exec_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the exec callback of.callback: The exec callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_query_set_query
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The query info handle.query: The SQL to run. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_pragma_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.function: The pragma function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_pragma_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The pragma function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_pragma_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_pragma_function_destroy(
duckdb_v2_pragma_function_handle *function
);
Parameters
function: The function to destroy.
Return Value
DUCKDB_V2_ERROR
Replacement Scan
duckdb_v2_replacement_scan_handle
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.
duckdb_v2_replacement_scan_info_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.
duckdb_v2_replacement_scan_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_replacement_scan_destroy(duckdb_v2_replacement_scan_handle *scan);
duckdb_v2_replacement_scan_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the scan through.scan: On success, receives the newly created replacement scan. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_set_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
scan: The scan to set the callback of.callback: The callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
scan: The scan to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_replacement_scan_set_user_data.
Syntax
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
);
Parameters
info: The info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_get_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The info handle.name: Receives the unresolved name. Owned by the caller; destroy viaduckdb_v2_qname_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_set_function_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The info handle.name: The table function to read instead. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_add_argument
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The info handle.value: The argument value. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_add_named_argument
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The info handle.name: The name of the parameter to bind the value to. Borrowed and copied.value: The argument value. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_set_collection
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The info handle.collection: The collection to read instead. Borrowed; the caller keeps ownership and must keep it alive.column_names: Optional. An array ofcolumn_countcolumn names, in order. Pass NULL for the default names col1..colN.column_count: The number of names incolumn_names. Must equal the collection's column count, or 0 for the default names.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_set_subquery
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The info handle.sql: The SELECT statement to read instead. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_set_alias
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The info handle.alias: The alias to bind the replacement under. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_replacement_scan
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.scan: The replacement scan to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_instance_register_replacement_scan
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
instance: The instance to register on.scan: The replacement scan to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_replacement_scan
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.scan: The replacement scan to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_replacement_scan_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_replacement_scan_destroy(
duckdb_v2_replacement_scan_handle *scan
);
Parameters
scan: The scan to destroy.
Return Value
DUCKDB_V2_ERROR
Scalar
duckdb_v2_scalar_function_handle
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.
duckdb_v2_scalar_function_resolve_types_info_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.
duckdb_v2_scalar_function_bind_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.
duckdb_v2_scalar_function_init_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.
duckdb_v2_scalar_function_exec_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.
duckdb_v2_scalar_function_resolve_types_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the arguments of the call site being bound and the user data.result: Borrowed opaque handle to set the return type of the call site being bound through.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_scalar_function_bind_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the arguments of the call site being bound and the user data.result: Borrowed opaque handle to set the bind data of the call site being bound through.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_scalar_function_init_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_scalar_function_exec_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_scalar_function_destroy(duckdb_v2_scalar_function_handle *function);
duckdb_v2_scalar_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the scalar function through.function: On success, receives the newly created scalar function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_get_docs
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the documentation of.docs: The returned documentation. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_get_signature
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the signature of.sig: The returned signature. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_set_property
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the property of.key: The property to set.value: The value to set for the property. Must belong tokey.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_set_resolve_types_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the resolve types callback of.callback: The resolve types callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_set_bind_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the bind callback of.callback: The bind callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_set_init_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the init callback of.callback: The init callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_set_exec_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the exec callback of.callback: The exec callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_resolve_types_set_return_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The resolve types info handle.return_type: The return type to set. Borrowed for the call only.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_bind_set_bind_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.data: Opaque handle bundling the bind data pointer plus optional destructor and equality callbacks.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_init_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_scalar_function_set_user_data.
Syntax
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
);
Parameters
info: The init info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_init_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The init info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_init_set_init_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The init info handle.data: Opaque handle bundling the init data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_exec_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_scalar_function_set_user_data.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_exec_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_exec_get_init_data
Unstable since 2.0.0.
Retrieves the worker-local init data set by the function's init callback.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the init data pointer for the executing thread, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_exec_get_row_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.count: Receives the number of rows. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_exec_get_arg_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.positional_fixed: Optional. Receives the number of positional-only and standard parameters. (out)positional_variadic: Optional. Receives the number of arguments*argsreceived, 0 when the signature has none. (out)named_fixed: Optional. Receives the number of named-only parameters. (out)named_variadic: Optional. Receives the number of arguments**kwargsreceived, 0 when the signature has none. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_exec_get_arg
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.index: The index of the argument.vector: Receives the borrowed argument vector. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_exec_get_result
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.vector: Receives the borrowed result vector to write into. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_scalar_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.function: The scalar function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_scalar_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The scalar function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_scalar_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_scalar_function_destroy(
duckdb_v2_scalar_function_handle *function
);
Parameters
function: The function to destroy.
Return Value
DUCKDB_V2_ERROR
SQL Statement
duckdb_v2_sql_statement_handle
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.
duckdb_v2_statement_iterator_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.
DUCKDB_V2_STATEMENT_TYPE
SQL statement type of a parsed statement or an executed query.
Values
DUCKDB_V2_STATEMENT_TYPE_INVALID= 0DUCKDB_V2_STATEMENT_TYPE_SELECT= 1DUCKDB_V2_STATEMENT_TYPE_INSERT= 2DUCKDB_V2_STATEMENT_TYPE_UPDATE= 3DUCKDB_V2_STATEMENT_TYPE_CREATE= 4DUCKDB_V2_STATEMENT_TYPE_DELETE= 5DUCKDB_V2_STATEMENT_TYPE_PREPARE= 6DUCKDB_V2_STATEMENT_TYPE_EXECUTE= 7DUCKDB_V2_STATEMENT_TYPE_ALTER= 8DUCKDB_V2_STATEMENT_TYPE_TRANSACTION= 9DUCKDB_V2_STATEMENT_TYPE_COPY= 10DUCKDB_V2_STATEMENT_TYPE_ANALYZE= 11DUCKDB_V2_STATEMENT_TYPE_VARIABLE_SET= 12DUCKDB_V2_STATEMENT_TYPE_CREATE_FUNC= 13DUCKDB_V2_STATEMENT_TYPE_EXPLAIN= 14DUCKDB_V2_STATEMENT_TYPE_DROP= 15DUCKDB_V2_STATEMENT_TYPE_EXPORT= 16DUCKDB_V2_STATEMENT_TYPE_PRAGMA= 17DUCKDB_V2_STATEMENT_TYPE_VACUUM= 18DUCKDB_V2_STATEMENT_TYPE_CALL= 19DUCKDB_V2_STATEMENT_TYPE_SET= 20DUCKDB_V2_STATEMENT_TYPE_LOAD= 21DUCKDB_V2_STATEMENT_TYPE_RELATION= 22DUCKDB_V2_STATEMENT_TYPE_EXTENSION= 23DUCKDB_V2_STATEMENT_TYPE_LOGICAL_PLAN= 24DUCKDB_V2_STATEMENT_TYPE_ATTACH= 25DUCKDB_V2_STATEMENT_TYPE_DETACH= 26DUCKDB_V2_STATEMENT_TYPE_MULTI= 27DUCKDB_V2_STATEMENT_TYPE_COPY_DATABASE= 28DUCKDB_V2_STATEMENT_TYPE_UPDATE_EXTENSIONS= 29DUCKDB_V2_STATEMENT_TYPE_MERGE_INTO= 30DUCKDB_V2_STATEMENT_TYPE_CONNECT= 31DUCKDB_V2_STATEMENT_TYPE_DISCONNECT= 32DUCKDB_V2_STATEMENT_TYPE_EXTERNAL_RESOURCE= 33DUCKDB_V2_STATEMENT_TYPE_PASSTHROUGH= 34
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_sql_statement_destroy(duckdb_v2_sql_statement_handle *statement);
DUCKDB_V2_ERROR duckdb_v2_statement_iterator_destroy(duckdb_v2_statement_iterator_handle *iterator);
duckdb_v2_parse_sql
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection supplying the parser configuration.sql: Null-terminated SQL string; may contain any number of statements.out_iterator: Receives the new iterator handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_statement_iterator_next
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
iterator: The iterator to advance.out_statement: Receives an owned statement, or NULL when the iterator is exhausted. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_statement_bind
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection supplying the catalog, transaction, and parser configuration.statement: The statement to bind. Borrowed; not consumed.out_schema: Receives the owned output schema (result columns). Destroy via schema_destroy. (out)out_parameters: Optional. When non-NULL, receives the owned input schema (parameter types, ordered by binding index). Destroy via schema_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_statement_add_collection
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
statement: The statement to bind the collection to. Modified in place.name: The non-empty name the statement refers to the collection by. Borrowed and copied.collection: The collection to bind. Borrowed; the caller keeps ownership and must keep it alive.column_names: Optional. An array ofcolumn_countnames for the collection's columns, in order. Pass NULL for col1..colN.column_count: The number of names incolumn_names. 0 for the default names; otherwise the collection's column count.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_sql_statement_get_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
statement: The statement.out_type: Receives the statement type. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_sql_statement_get_text
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
statement: The statement.out_text: Receives a borrowed view of the statement text, valid until the statement is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_sql_statement_get_parameter_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
statement: The statement.out_count: Receives the number of distinct parameters. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_sql_statement_get_parameter_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
statement: The statement.index: Zero-based position in binding order.out_name: Receives a borrowed view of the parameter name, valid until the statement is destroyed. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_sql_statement_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_sql_statement_destroy(
duckdb_v2_sql_statement_handle *statement
);
Parameters
statement: The statement to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_statement_iterator_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_statement_iterator_destroy(
duckdb_v2_statement_iterator_handle *iterator
);
Parameters
iterator: The iterator to destroy.
Return Value
DUCKDB_V2_ERROR
Vector
duckdb_v2_vector_view
Fields
data(const void *)validity(const uint64_t *)sel(const duckdb_v2_sel_t *)count(idx_t)
duckdb_v2_list_entry
Fields
offset(idx_t)length(idx_t)
duckdb_v2_hugeint_t
Fields
lower(uint64_t)upper(int64_t)
duckdb_v2_uhugeint_t
Fields
lower(uint64_t)upper(uint64_t)
duckdb_v2_interval_t
Fields
months(int32_t)days(int32_t)micros(int64_t)
DUCKDB_V2_VECTOR_TYPE
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.
Values
DUCKDB_V2_VECTOR_TYPE_OTHER= 0: Default for zero-init. Covers FSST / SEQUENCE / SHREDDED — call vector_flatten first.DUCKDB_V2_VECTOR_TYPE_FLAT= 1: Standard per-row storage.DUCKDB_V2_VECTOR_TYPE_CONSTANT= 2: A single value applies to every row in the vector.DUCKDB_V2_VECTOR_TYPE_DICTIONARY= 3: Data + selection vector indirection into another vector.
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_vector_get_size(duckdb_v2_vector_handle vector, idx_t *out_size, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_vector_set_size(duckdb_v2_vector_handle vector, idx_t size, duckdb_v2_error_info_handle *err);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_vector_get_data_mutable(duckdb_v2_vector_handle vector, void **out_data, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_vector_flatten(duckdb_v2_vector_handle vector, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_vector_reference(duckdb_v2_vector_handle vector, duckdb_v2_vector_handle source, duckdb_v2_error_info_handle *err);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_vector_set_null(duckdb_v2_vector_handle vector, idx_t row, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_vector_constant_set_valid(duckdb_v2_vector_handle vector, bool validity, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_vector_get_child_count(duckdb_v2_vector_handle vector, idx_t *out_count, duckdb_v2_error_info_handle *err);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_validate_utf8(const duckdb_v2_str *text, duckdb_v2_error_info_handle *err);
duckdb_v2_vector_get_vector_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector.out_type: Receives the representation kind. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_logical_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector.out_type: Receives the caller-owned logical type handle. Destroy via logical_type_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_view
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector to read.out_view: Receives the view. Its pointers are borrowed and valid until the owning chunk is destroyed. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_size
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_get_size(
duckdb_v2_vector_handle vector,
idx_t *out_size,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The vector.out_size: Receives the number of elements. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_set_size
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_set_size(
duckdb_v2_vector_handle vector,
idx_t size,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The vector.size: The new number of logical elements.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector to read from.row: The logical row index, in [0, vector_get_size).out_value: Receives the owned cell value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_set_value
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector to write to.row: The logical row index, in [0, vector_get_size).value: The borrowed value to write. Copied in; cast to the vector's type.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_data_mutable
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_get_data_mutable(
duckdb_v2_vector_handle vector,
void **out_data,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The vector.out_data: Receives a mutable pointer to the data. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_flatten
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_flatten(
duckdb_v2_vector_handle vector,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The vector to flatten.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_cast
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory supplying the cast functions.source: The vector to cast. Borrowed for the call only.target: The vector to write the cast rows into. Its logical type is the target type.mode: Whether a row that does not convert fails the call, or becomes NULL.out_converted: Optional. Receives whether every row converted. Always true when a CAST_MODE_NORMAL cast succeeds. (out)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. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_reference
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_reference(
duckdb_v2_vector_handle vector,
duckdb_v2_vector_handle source,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The vector to repoint at the source's data.source: The vector whose data to reference. Its logical type must equal the vector's.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_make_constant
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector to make constant.value: The value every row takes. Its logical type must equal the vector's.count: The number of elements in the vector.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_make_sequence
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector to turn into a sequence.start: The first value of the sequence.increment: The step between consecutive values.count: The number of elements in the sequence.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_set_null
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_set_null(
duckdb_v2_vector_handle vector,
idx_t row,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The vector to write to.row: The logical row index, in [0, vector_get_size).err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_flat_get_validity_mutable
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The vector.out_validity: Receives a mutable pointer to the validity mask. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_constant_set_valid
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_constant_set_valid(
duckdb_v2_vector_handle vector,
bool validity,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The constant vector.validity: True to mark the vector's single element valid, false to mark it NULL.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_arena
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The string-backed vector whose arena to borrow.out_arena: Receives the borrowed arena handle. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_child_count
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_vector_get_child_count(
duckdb_v2_vector_handle vector,
idx_t *out_count,
duckdb_v2_error_info_handle *err
);
Parameters
vector: The vector.out_count: Receives the number of child vectors. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_vector_get_child
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
vector: The nested vector to descend into.index: The child index, in [0, vector_get_child_count).out_child: Receives the borrowed child vector. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_bignum_decode
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
in_data: The value's raw BIGNUM storage bytes.in_length: Size of in_data in bytes.out_data: Caller-owned buffer receiving the magnitude bytes, or NULL to only report the required size in out_length. (out)out_capacity: Bytes available in out_data. Ignored when out_data is NULL.out_length: Receives the magnitude size in bytes, written on success and on ERROR_INPUT_OBJECT_SIZE. (out)out_is_negative: Receives true if the value is negative, false otherwise. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_bignum_encode
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
in_data: Big-endian magnitude bytes, with no leading zero bytes.in_length: Size of in_data in bytes. Must be >= 1.is_negative: True to encode a negative value.out_data: Caller-owned buffer receiving the storage bytes, or NULL to only report the required size in out_length. (out)out_capacity: Bytes available in out_data. Ignored when out_data is NULL.out_length: Receives the storage size in bytes — written on success and on ERROR_INPUT_OBJECT_SIZE. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_validate_utf8
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_validate_utf8(
const duckdb_v2_str *text,
duckdb_v2_error_info_handle *err
);
Parameters
text: The bytes to validate.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Prepared Statement
duckdb_v2_prepared_statement_handle
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.
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);
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);
DUCKDB_V2_ERROR duckdb_v2_prepared_statement_reuses_plan(duckdb_v2_prepared_statement_handle prepared, bool *out_reuses, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_prepared_statement_destroy(duckdb_v2_prepared_statement_handle *prepared);
duckdb_v2_prepared_statement_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection supplying the catalog, transaction, and parser state. The prepared statement belongs to it.statement: The statement to prepare. Borrowed and copied, not consumed; destroy it withduckdb_v2_sql_statement_destroy.require_cacheable: When true, fail withERROR_INPUT_INVALIDunless the prepared plan will be reused across executions, asduckdb_v2_prepared_statement_reuses_planwould report it.out_prepared: On success, receives the new prepared statement. Owned by the caller; destroy viaduckdb_v2_prepared_statement_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_prepared_statement_execute
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
prepared: The prepared statement to execute. Borrowed; not consumed.parameter_names: Optional. An array ofparameter_countparameter 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.parameter_values: Optional. An array ofparameter_countvalues. Each binds by name whenparameter_namessupplies one, and positionally ($1 = element 0) otherwise. Borrowed and copied in. Pass NULL for a statement without parameters.parameter_count: The number of entries inparameter_namesandparameter_values. Pass 0 for a statement without parameters.out_result: On success, receives the new result. Owned by the caller; destroy viaduckdb_v2_result_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_prepared_statement_reuses_plan
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_prepared_statement_reuses_plan(
duckdb_v2_prepared_statement_handle prepared,
bool *out_reuses,
duckdb_v2_error_info_handle *err
);
Parameters
prepared: The prepared statement to inspect.out_reuses: Receives true when the compiled plan is reused across executions, false when the statement re-binds each time. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_prepared_statement_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_prepared_statement_destroy(
duckdb_v2_prepared_statement_handle *prepared
);
Parameters
prepared: The prepared statement to destroy.
Return Value
DUCKDB_V2_ERROR
Query Result
DUCKDB_V2_RESULT_TYPE
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.
Values
DUCKDB_V2_RESULT_TYPE_QUERY_RESULT= 0DUCKDB_V2_RESULT_TYPE_CHANGED_ROWS= 1DUCKDB_V2_RESULT_TYPE_NOTHING= 2
DUCKDB_V2_RESULT_STEP_STATUS
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.
Values
DUCKDB_V2_RESULT_STEP_STATUS_WAITING= 0: No chunk yet; step again, or block in result_wait.DUCKDB_V2_RESULT_STEP_STATUS_CHUNK= 1: A caller-owned chunk was written to *out_chunk, or an array to *out_array.DUCKDB_V2_RESULT_STEP_STATUS_FINISHED= 2: Stream exhausted. Sticky.DUCKDB_V2_RESULT_STEP_STATUS_CANCELLED= 3: Query was interrupted. Sticky.
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);
DUCKDB_V2_ERROR duckdb_v2_result_destroy(duckdb_v2_result_handle *result);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_result_wait(duckdb_v2_result_handle result, duckdb_v2_error_info_handle *err);
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);
DUCKDB_V2_ERROR duckdb_v2_result_drain(duckdb_v2_result_handle result, idx_t *out_rows_changed, duckdb_v2_error_info_handle *err);
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);
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);
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);
duckdb_v2_statement_execute
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection on which to execute the statement.statement: The statement to execute. Borrowed and copied; not consumed. Destroy it with sql_statement_destroy.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.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.parameter_count: The number of parameters in parameter_names and parameter_values. Pass 0 for an unparameterized statement.out_result: Receives the new result handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_result_destroy(
duckdb_v2_result_handle *result
);
Parameters
result: The result to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_step
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result to step.out_chunk: Receives an owned chunk if *out_status is CHUNK; set to nullptr otherwise. (out)out_status: Receives the step status. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_fetch_chunk
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result to fetch from.out_chunk: Receives an owned chunk, or nullptr at end-of-stream. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_wait
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_result_wait(
duckdb_v2_result_handle result,
duckdb_v2_error_info_handle *err
);
Parameters
result: The result to wait on.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_render_box
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result to render; consumed and set to NULL. Left intact only when the call rejects null arguments. (ownership passes to the callee)max_rows: Maximum rows displayed; 0 selects the renderer default (20).max_width: Maximum total width in characters; 0 selects the renderer default.max_col_width: Maximum width of one column; 0 selects the renderer default (20).null_value: Text rendered for NULL cells; empty selects “NULL”.render_mode: 0 renders rows (records down the page); 1 renders columns; other values are rejected with INVALID_INPUT.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.sink: Receives the whole rendered box in a single call. Borrowed for the duration of that call; see text_sink for the full contract.user_data: Opaque pointer passed through to sink untouched. May be NULL.err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_drain
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_result_drain(
duckdb_v2_result_handle result,
idx_t *out_rows_changed,
duckdb_v2_error_info_handle *err
);
Parameters
result: The result to drain.out_rows_changed: Receives the affected row count for CHANGED_ROWS results, 0 otherwise. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_get_result_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result.out_type: Receives the result shape. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_get_statement_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result.out_type: Receives the statement type. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_result_get_schema
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result.out_schema: Receives the owned output schema. Destroy via schema_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Table
duckdb_v2_table_function_handle
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.
duckdb_v2_table_function_bind_info_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.
duckdb_v2_table_function_init_global_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.
duckdb_v2_table_function_init_local_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.
duckdb_v2_table_function_exec_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.
duckdb_v2_table_function_progress_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.
duckdb_v2_table_function_filter_pushdown_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.
duckdb_v2_table_function_partition_data_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.
duckdb_v2_table_function_partitioning_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.
duckdb_v2_table_function_claim_batch_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.
duckdb_v2_table_function_get_bind_info_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.
duckdb_v2_multi_file_function_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.
duckdb_v2_table_function_bind_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the arguments of the call site being bound, the user data and the bind data.result: Borrowed opaque handle to declare the result columns and the estimated cardinality of the scan through.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_init_global_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_init_local_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_exec_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_progress_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_filter_pushdown_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_partition_data_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_partitioning_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_claim_batch_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query currently executing the callback.err: Borrowed error info handle to use to report errors that occur during the callback.
duckdb_v2_table_function_get_bind_info_callback_fn
Syntax
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
);
Parameters
info: Borrowed opaque handle providing access to the information available to the callback.context: Borrowed handle to the context of the query the bound call is part of.err: Borrowed error info handle to use to report errors that occur during the callback.
DUCKDB_V2_TABLE_PARTITION_INFO
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.
Values
DUCKDB_V2_TABLE_PARTITION_INFO_NOT_PARTITIONED= 0: The scan is not known to be partitioned by the requested columns.DUCKDB_V2_TABLE_PARTITION_INFO_SINGLE_VALUE_PARTITIONS= 1: Each partition the scan produces carries exactly one distinct value for the requested columns.DUCKDB_V2_TABLE_PARTITION_INFO_OVERLAPPING_PARTITIONS= 2: The partitions the scan produces overlap only at their boundaries.DUCKDB_V2_TABLE_PARTITION_INFO_DISJOINT_PARTITIONS= 3: The partitions the scan produces are disjoint ranges.
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_table_function_set_projection_pushdown(duckdb_v2_table_function_handle function, bool enable, duckdb_v2_error_info_handle *err);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_table_function_destroy(duckdb_v2_table_function_handle *function);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_multi_file_function_destroy(duckdb_v2_multi_file_function_handle *function);
duckdb_v2_table_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the table function through.function: On success, receives the newly created table function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_get_docs
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the documentation of.docs: The returned documentation. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_get_signature
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to get the signature of.sig: The returned signature. Borrowed and valid for the lifetime of the function handle. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_user_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the user data of.data: Opaque handle bundling the user data pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_bind_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the bind callback of.callback: The bind callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_init_global_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the global init callback of.callback: The global init callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_init_local_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the local init callback of.callback: The local init callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_exec_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the exec callback of.callback: The exec callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_progress_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the progress callback of.callback: The progress callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_projection_pushdown
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_table_function_set_projection_pushdown(
duckdb_v2_table_function_handle function,
bool enable,
duckdb_v2_error_info_handle *err
);
Parameters
function: The function to configure.enable: Whether the function supports projection pushdown.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_filter_pushdown_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the filter pushdown callback of.callback: The filter pushdown callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_partition_data_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the partition data callback of.callback: The partition data callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_partitioning_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the partitioning callback of.callback: The partitioning callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_bind_add_result_column
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.name: The name of the column. Borrowed and copied.type: The type of the column. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_bind_set_cardinality
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.cardinality: The estimated number of rows.is_exact: Whether the estimate is exact, which also makes it an upper bound on the row count.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_bind_set_order_preservation
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The bind info handle.order: The order guarantee of the produced rows.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_global_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The global init info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_global_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The global init info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_global_set_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The global init info handle.data: Opaque handle bundling the global state pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_global_set_max_threads
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The global init info handle.max_threads: The maximum number of threads. Must be at least 1.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_global_get_column_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The global init info handle.count: Receives the number of columns the scan produces. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_global_get_column_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The global init info handle.index: The index of the column in the scan's output.column_index: Receives the index of the declared column. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_local_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The local init info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_local_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The local init info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_local_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The local init info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_local_set_local_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The local init info handle.data: Opaque handle bundling the local state pointer plus an optional destructor.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_local_get_column_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The local init info handle.count: Receives the number of columns the scan produces. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_init_local_get_column_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The local init info handle.index: The index of the column in the scan's output.column_index: Receives the index of the declared column. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_local_state
Unstable since 2.0.0.
Retrieves the worker-local local state set by the function's local init callback.
Syntax
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
);
Parameters
info: The exec info handle.data: Receives the local state pointer for the executing thread, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_output_chunk
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.chunk: Receives the borrowed output chunk to write into. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_column_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.count: Receives the number of columns the scan produces. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_exec_get_column_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The exec info handle.index: The index of the column in the scan's output.column_index: Receives the index of the declared column. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_progress_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The progress info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_progress_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The progress info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_progress_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The progress info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_progress_set_progress
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The progress info handle.progress: The fraction of the scan that is complete, in [0.0, 1.0].err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_filter_pushdown_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data, or null if none was set.
Syntax
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
);
Parameters
info: The filter pushdown info handle.data: Receives the user data pointer. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_filter_pushdown_get_bind_data
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The filter pushdown info handle.data: Receives the bind data pointer. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_filter_pushdown_get_filter_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The filter pushdown info handle.count: Receives the number of predicates. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_filter_pushdown_get_filter
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The filter pushdown info handle.index: The index of the predicate to retrieve.filter: Receives the borrowed predicate. (out, borrowed)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_filter_pushdown_accept
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The filter pushdown info handle.index: The index of the predicate to accept.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_filter_pushdown_get_column_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The filter pushdown info handle.count: Receives the number of referable columns. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_filter_pushdown_get_column_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The filter pushdown info handle.index: The column index reported by a column reference node.column_index: Receives the index of the declared column. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The partition data info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The partition data info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partition data info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_get_local_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partition data info handle.data: Receives the local state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_requires_batch_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partition data info handle.required: Receives whether a batch index is required. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_requires_partition_columns
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partition data info handle.required: Receives whether partitioning column values are required. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_get_partition_column_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partition data info handle.count: Receives the number of requested partitioning columns. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_get_partition_column_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partition data info handle.index: The index of the requested partitioning column.column_index: Receives the index of the declared column. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_set_batch_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partition data info handle.batch_index: The batch's ordering position.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partition_data_set_partition_value
Unstable since 2.0.0.
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](#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.
Syntax
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
);
Parameters
info: The partition data info handle.index: The index of the partitioning column being reported.value: The single value of the partitioning column. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partitioning_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The partitioning info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partitioning_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The partitioning info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partitioning_get_partition_column_count
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partitioning info handle.count: Receives the number of columns in the candidate set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partitioning_get_partition_column_index
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partitioning info handle.index: The index of the candidate column.column_index: Receives the index of the declared column. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_partitioning_set_partition_info
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The partitioning info handle.partition_info: Whether, and how, the scan is partitioned by the candidate column set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_table_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.function: The table function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_table_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The table function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_table_function_destroy(
duckdb_v2_table_function_handle *function
);
Parameters
function: The function to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_claim_batch_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the claim batch callback of.callback: The claim batch callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_claim_batch_get_user_data
Unstable since 2.0.0.
Retrieves the user data set on the table function via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The claim batch info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_claim_batch_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data set by the function's bind callback.
Syntax
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
);
Parameters
info: The claim batch info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_claim_batch_get_global_state
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The claim batch info handle.data: Receives the global state pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_claim_batch_get_local_state
Unstable since 2.0.0.
Retrieves the local state set by the function's local init callback, for the thread claiming a batch.
Syntax
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
);
Parameters
info: The claim batch info handle.data: Receives the local state pointer for the claiming thread, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_claim_batch_set_claimed
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The claim batch info handle.claimed: Whether a batch was claimed.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_set_get_bind_info_callback
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the callback of.callback: The “get bind info” callback to set.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_get_bind_info_get_user_data
Unstable since 2.0.0.
Retrieves the user data set via duckdb_v2_table_function_set_user_data.
Syntax
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
);
Parameters
info: The get bind info handle.data: Receives the user data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_get_bind_info_get_bind_data
Unstable since 2.0.0.
Retrieves the bind data the function's bind callback set for the bound call being described.
Syntax
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
);
Parameters
info: The get bind info handle.data: Receives the bind data pointer, or null if none was set. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_get_bind_info_set_column_identifier
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The get bind info handle.column_index: The index of the result column, in the order the bind callback declared the columns.child_path: The path of child indexes addressing the nested field, or null for the column itself.child_path_length: The number of entries in the path, 0 for the column itself.identifier: The identifier, an INTEGER or VARCHAR value. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_table_function_get_bind_info_set_option
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
info: The get bind info handle.key: The key of the option. Borrowed and copied.value: The value of the option. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_multi_file_function_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create the multi-file function through.function: On success, receives the newly created multi-file function. Owned by the caller. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_multi_file_function_set_name
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the name of.name: The name to set. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_multi_file_function_set_single_file_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the single-file function of.name: The name of the registered single-file table function. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_multi_file_function_set_reader_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the reader type of.reader_type: The reader type. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_multi_file_function_set_file_extension
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
function: The function to set the file extension of.extension: The file extension, without a leading dot. Borrowed and copied.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_connection_register_multi_file_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
conn: The connection to register on.function: The multi-file function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_extension_register_multi_file_function
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
extension: The loading extension.function: The multi-file function to register.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_multi_file_function_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_multi_file_function_destroy(
duckdb_v2_multi_file_function_handle *function
);
Parameters
function: The function to destroy.
Return Value
DUCKDB_V2_ERROR
Value
DUCKDB_V2_ERROR duckdb_v2_value_destroy(duckdb_v2_value_handle *value);
DUCKDB_V2_ERROR duckdb_v2_value_get_bool(duckdb_v2_value_handle value, bool *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_utinyint(duckdb_v2_value_handle value, uint8_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_usmallint(duckdb_v2_value_handle value, uint16_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_uint(duckdb_v2_value_handle value, uint32_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_ubigint(duckdb_v2_value_handle value, uint64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_uhugeint(duckdb_v2_value_handle value, duckdb_v2_uhugeint_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_tinyint(duckdb_v2_value_handle value, int8_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_smallint(duckdb_v2_value_handle value, int16_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_int(duckdb_v2_value_handle value, int32_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_bigint(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_hugeint(duckdb_v2_value_handle value, duckdb_v2_hugeint_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_varchar(duckdb_v2_value_handle value, duckdb_v2_str *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_blob(duckdb_v2_value_handle value, duckdb_v2_str *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_float(duckdb_v2_value_handle value, float *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_double(duckdb_v2_value_handle value, double *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_date(duckdb_v2_value_handle value, int32_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_time(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_time_ns(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_time_tz(duckdb_v2_value_handle value, uint64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_sec(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_ms(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_ns(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_tz(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_tz_ns(duckdb_v2_value_handle value, int64_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_interval(duckdb_v2_value_handle value, duckdb_v2_interval_t *out, duckdb_v2_error_info_handle *err);
DUCKDB_V2_ERROR duckdb_v2_value_get_uuid(duckdb_v2_value_handle value, duckdb_v2_hugeint_t *out, duckdb_v2_error_info_handle *err);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_value_get_child_count(duckdb_v2_value_handle value, idx_t *out_count, duckdb_v2_error_info_handle *err);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_value_is_null(duckdb_v2_value_handle value, bool *out_is_null, duckdb_v2_error_info_handle *err);
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);
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);
duckdb_v2_value_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_destroy(
duckdb_v2_value_handle *value
);
Parameters
value: The value to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_bool
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_bool(
duckdb_v2_value_handle value,
bool *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a bool. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_utinyint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_utinyint(
duckdb_v2_value_handle value,
uint8_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a uint8_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_usmallint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_usmallint(
duckdb_v2_value_handle value,
uint16_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a uint16_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_uint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_uint(
duckdb_v2_value_handle value,
uint32_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a uint32_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_ubigint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_ubigint(
duckdb_v2_value_handle value,
uint64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a uint64_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_uhugeint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_uhugeint(
duckdb_v2_value_handle value,
duckdb_v2_uhugeint_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a uint128_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_tinyint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_tinyint(
duckdb_v2_value_handle value,
int8_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as an int8_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_smallint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_smallint(
duckdb_v2_value_handle value,
int16_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as an int16_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_int
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_int(
duckdb_v2_value_handle value,
int32_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as an int32_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_bigint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_bigint(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as an int64_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_hugeint
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_hugeint(
duckdb_v2_value_handle value,
duckdb_v2_hugeint_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as an int128_t. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_varchar
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_varchar(
duckdb_v2_value_handle value,
duckdb_v2_str *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a UTF-8 string. The returned string is borrowed and valid until the value handle is destroyed. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_blob
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_blob(
duckdb_v2_value_handle value,
duckdb_v2_str *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a byte string. The returned string is borrowed and valid until the value handle is destroyed. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_float
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_float(
duckdb_v2_value_handle value,
float *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a float. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_double
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_double(
duckdb_v2_value_handle value,
double *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload as a double. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_date
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_date(
duckdb_v2_value_handle value,
int32_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_time
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_time(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_time_ns
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_time_ns(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_time_tz
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_time_tz(
duckdb_v2_value_handle value,
uint64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_timestamp
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_timestamp_sec
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_sec(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_timestamp_ms
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_ms(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_timestamp_ns
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_ns(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_timestamp_tz
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_tz(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_timestamp_tz_ns
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_timestamp_tz_ns(
duckdb_v2_value_handle value,
int64_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_interval
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_interval(
duckdb_v2_value_handle value,
duckdb_v2_interval_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the payload. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_uuid
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_uuid(
duckdb_v2_value_handle value,
duckdb_v2_hugeint_t *out,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out: Receives the internal 128-bit storage form. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_decimal
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
value: The value to read.out: Receives the backing integer, scaled by 10^scale. (out)out_width: Receives the total digit count of the value's type. (out)out_scale: Receives the digits after the decimal point. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
value: The value to read.out_type: Receives the owned logical type. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_null
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.type: The borrowed logical type to attach to the NULL value.out_value: Receives the new NULL value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_bool
Unstable since 2.0.0.
Creates a BOOLEAN value from a bool.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The bool to wrap.out_value: Receives the new BOOLEAN value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_utinyint
Unstable since 2.0.0.
Creates a UTINYINT value from a uint8_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The uint8_t to wrap.out_value: Receives the new UTINYINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_usmallint
Unstable since 2.0.0.
Creates a USMALLINT value from a uint16_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The uint16_t to wrap.out_value: Receives the new USMALLINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_uint
Unstable since 2.0.0.
Creates a UINTEGER value from a uint32_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The uint32_t to wrap.out_value: Receives the new UINTEGER value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_ubigint
Unstable since 2.0.0.
Creates a UBIGINT value from a uint64_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The uint64_t to wrap.out_value: Receives the new UBIGINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_uhugeint
Unstable since 2.0.0.
Creates a UHUGEINT value from a uint128_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The uint128_t to wrap.out_value: Receives the new UHUGEINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_tinyint
Unstable since 2.0.0.
Creates a TINYINT value from an int8_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The int8_t to wrap.out_value: Receives the new TINYINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_smallint
Unstable since 2.0.0.
Creates a SMALLINT value from an int16_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The int16_t to wrap.out_value: Receives the new SMALLINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_int
Unstable since 2.0.0.
Creates an INTEGER value from an int32_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The int32_t to wrap.out_value: Receives the new INTEGER value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_bigint
Unstable since 2.0.0.
Creates a BIGINT value from an int64_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The int64_t to wrap.out_value: Receives the new BIGINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_hugeint
Unstable since 2.0.0.
Creates a HUGEINT value from an int128_t.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The int128_t to wrap.out_value: Receives the new HUGEINT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_varchar
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The UTF-8 string to wrap. May be null only when len is 0 (empty string).out_value: Receives the new VARCHAR value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_blob
Unstable since 2.0.0.
Creates a BLOB value from a byte string.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The byte string to wrap. May be null only when len is 0 (empty string).out_value: Receives the new BLOB value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_float
Unstable since 2.0.0.
Creates a FLOAT value from a float.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The float to wrap.out_value: Receives the new FLOAT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_double
Unstable since 2.0.0.
Creates a DOUBLE value from a double.
The input is copied in. The returned value is caller-owned; destroy it via value_destroy.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The double to wrap.out_value: Receives the new DOUBLE value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_type
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_type: The borrowed logical type to wrap.out_value: Receives the new TYPE value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_date
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new DATE value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_time
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIME value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_time_ns
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIME_NS value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_time_tz
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIME_TZ value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_timestamp
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIMESTAMP value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_timestamp_sec
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIMESTAMP_SEC value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_timestamp_ms
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIMESTAMP_MS value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_timestamp_ns
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIMESTAMP_NS value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_timestamp_tz
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIMESTAMP_TZ value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_timestamp_tz_ns
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new TIMESTAMP_TZ_NS value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_interval
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The payload to wrap.out_value: Receives the new INTERVAL value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_decimal
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The backing integer, scaled by 10^scale.width: Total digit count, 1..38.scale: Digits after the decimal point; must not exceed width.out_value: Receives the new DECIMAL value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_uuid
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The internal 128-bit storage form.out_value: Receives the new UUID value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_bit
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The wire bytes, a padding header byte followed by data. Must be at least 1 byte.out_value: Receives the new BIT value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_bignum
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.in_value: The opaque storage bytes from bignum_encode. Must exceed 3 bytes.out_value: Receives the new BIGNUM value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_list
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.child_type: Optional. The element type. Pass NULL to resolve it from the elements.children: An array of child_count elements. Borrowed (copied in). Pass NULL when child_count is 0.child_count: The number of elements.out_value: Receives the new composite value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_array
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.child_type: Optional. The element type. Pass NULL to resolve it from the elements.children: An array of child_count elements. Borrowed (copied in). Pass NULL when child_count is 0.child_count: The number of elements.out_value: Receives the new composite value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_struct
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.names: An array of field_count field names. Pass NULL when field_count is 0.children: An array of field_count field values. Borrowed (copied in). Pass NULL when field_count is 0.field_count: The number of fields.out_value: Receives the new composite value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_tuple
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.children: An array of field_count field values. Borrowed (copied in). Pass NULL when field_count is 0.field_count: The number of fields.out_value: Receives the new composite value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_create_map
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory to create with.key_type: Optional. The key type. Pass NULL to resolve it from the keys.value_type: Optional. The value type. Pass NULL to resolve it from the values.keys: An array of entry_count keys. Borrowed (copied in). Pass NULL when entry_count is 0.values: An array of entry_count values, parallel to keys. Borrowed (copied in). Pass NULL when entry_count is 0.entry_count: The number of entries.out_value: Receives the new composite value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_child_count
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_get_child_count(
duckdb_v2_value_handle value,
idx_t *out_count,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out_count: Receives the number of children. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_child
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
value: The value to read.index: The child index, in [0, child_count).out_child: Receives the owned child value. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_cast
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
factory: The factory supplying the cast functions.value: The borrowed value to cast.target_type: The borrowed target logical type.out_value: Receives the owned cast result. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_is_null
Unstable since 2.0.0.
Returns whether the value is NULL.
Syntax
DUCKDB_V2_ERROR duckdb_v2_value_is_null(
duckdb_v2_value_handle value,
bool *out_is_null,
duckdb_v2_error_info_handle *err
);
Parameters
value: The value to read.out_is_null: Receives true if the value is NULL, false otherwise. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_get_logical_type
Unstable since 2.0.0.
Returns the logical type of the value.
The returned logical type is caller-owned; destroy it via logical_type_destroy.
Syntax
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
);
Parameters
value: The value to read.out_type: Receives the owned logical type. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
duckdb_v2_value_to_string
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
value: The value to read.out_string: Caller-owned buffer receiving the text plus a null terminator, or NULL to only report the required length in out_length. (out)out_capacity: Bytes available in out_string, terminator included. Ignored when out_string is NULL.out_length: Receives the text length excluding the null terminator — written on success and on ERROR_INPUT_OBJECT_SIZE. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy via error_info_destroy. (out)
Return Value
DUCKDB_V2_ERROR
Arrow
duckdb_v2_arrow_importer_handle
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.
duckdb_v2_arrow_exporter_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.
duckdb_v2_arrow_result_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_interruptcancels it:duckdb_v2_arrow_result_stepreportsCANCELLED, andduckdb_v2_arrow_result_fetch_arrayand a stream'sget_nextfail.- Arrays and schemas it hands out belong to the caller and stay valid after the result is destroyed.
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_arrow_importer_destroy(duckdb_v2_arrow_importer_handle *importer);
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);
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);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_arrow_exporter_destroy(duckdb_v2_arrow_exporter_handle *exporter);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_arrow_result_destroy(duckdb_v2_arrow_result_handle *result);
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);
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);
DUCKDB_V2_ERROR duckdb_v2_arrow_result_wait(duckdb_v2_arrow_result_handle result, duckdb_v2_error_info_handle *err);
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);
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);
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);
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);
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);
duckdb_v2_arrow_importer_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
context: The context used to resolve the Arrow types, extension types included.schema: The schema to resolve. Read, not consumed; the caller keeps ownership.batch_size: Maximum rows per produced chunk, or 0 for no maximum.out_importer: On success, receives the new importer. Owned by the caller; destroy viaduckdb_v2_arrow_importer_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_importer_get_schema
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
importer: The importer to read.out_schema: On success, receives an owned schema. Destroy viaduckdb_v2_schema_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_importer_append
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
importer: The importer to feed.array: The array to convert. Itsreleaseis set to NULL whenconsumeis true.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.flush: True to mark the end of the input, releasing held rows as a final short chunk. Pass NULL forarraywith this set to flush without supplying more input.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_importer_next_chunk
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
importer: The importer to drain.out_chunk: On success, receives the next chunk, or NULL once the array is drained. Destroy viaduckdb_v2_data_chunk_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_importer_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_arrow_importer_destroy(
duckdb_v2_arrow_importer_handle *importer
);
Parameters
importer: The importer to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_exporter_create
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
context: The context whose Arrow settings are captured and whose transaction resolves the types.types: An array ofcountcolumn types. May be NULL only whencountis 0.names: An array ofcountcolumn names, parallel totypes. Each name must be valid UTF-8. May be NULL only whencountis 0.count: The number of columns, being the length of bothtypesandnames.batch_size: Maximum rows per produced array, or 0 for no maximum.out_exporter: On success, receives the new exporter. Owned by the caller; destroy viaduckdb_v2_arrow_exporter_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_exporter_get_schema
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
exporter: The exporter to read.out_schema: Caller-allocated schema the library fills. Release it without_schema->release(out_schema). (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_exporter_append
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
exporter: The exporter to feed.chunk: The chunk to convert. Destroyed and set to NULL only whenconsumeis true.consume: True to hand the chunk over, destroying it; false to leave the caller's handle untouched.flush: True to mark the end of the input, releasing the held rows as a final short array. Pass NULL forchunkwith this set to flush without supplying more input.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_exporter_next_array
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
exporter: The exporter to drain.out_array: Caller-allocated array the library fills. Left released –releaseNULL – when none is ready. Release a filled one without_array->release(out_array). (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_exporter_destroy
Unstable since 2.0.0.
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.
Syntax
DUCKDB_V2_ERROR duckdb_v2_arrow_exporter_destroy(
duckdb_v2_arrow_exporter_handle *exporter
);
Parameters
exporter: The exporter to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_statement_execute_arrow
Unstable since 2.0.0.
Executes a parsed statement. The result produces Arrow arrays.
Works like duckdb_v2_statement_execute. *out_result is set to NULL on failure.
Syntax
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
);
Parameters
conn: The connection to run the statement on.statement: The statement to execute. Not consumed.parameter_names: Optional. As induckdb_v2_statement_execute.parameter_values: Optional. As induckdb_v2_statement_execute.parameter_count: The number of parameters. 0 for none.batch_size: Maximum rows per array. Arrays can be shorter. 0 means 131072.out_result: Receives the new result. Destroy viaduckdb_v2_arrow_result_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_prepared_statement_execute_arrow
Unstable since 2.0.0.
Executes a prepared statement. The result produces Arrow arrays.
Works like duckdb_v2_prepared_statement_execute. *out_result is set to NULL on failure.
Syntax
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
);
Parameters
prepared: The prepared statement to execute. Not consumed.parameter_names: Optional. As induckdb_v2_prepared_statement_execute.parameter_values: Optional. As induckdb_v2_prepared_statement_execute.parameter_count: The number of parameters. 0 for none.batch_size: Maximum rows per array. Arrays can be shorter. 0 means 131072.out_result: Receives the new result. Destroy viaduckdb_v2_arrow_result_destroy. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_destroy
Unstable since 2.0.0.
Destroys the result. Works like duckdb_v2_result_destroy.
Syntax
DUCKDB_V2_ERROR duckdb_v2_arrow_result_destroy(
duckdb_v2_arrow_result_handle *result
);
Parameters
result: The result to destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_step
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result to step.out_array: Caller-allocated array the library fills. Release it without_array->release(out_array). (out)out_status: Receives the step status. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_fetch_array
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result to fetch from.out_array: Caller-allocated array the library fills. Release it without_array->release(out_array). (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_wait
Unstable since 2.0.0.
Blocks until duckdb_v2_arrow_result_step can make progress. Works like duckdb_v2_result_wait.
Syntax
DUCKDB_V2_ERROR duckdb_v2_arrow_result_wait(
duckdb_v2_arrow_result_handle result,
duckdb_v2_error_info_handle *err
);
Parameters
result: The result to wait on.err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_drain
Unstable since 2.0.0.
Runs the query to the end and reports the changed-row count. Works like duckdb_v2_result_drain.
Syntax
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
);
Parameters
result: The result to drain.out_rows_changed: Receives the changed-row count for an INSERT, UPDATE or DELETE, 0 otherwise. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_get_result_type
Unstable since 2.0.0.
Returns the shape of the result. Works like duckdb_v2_result_get_result_type.
Syntax
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
);
Parameters
result: The result.out_type: Receives the result shape. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_get_statement_type
Unstable since 2.0.0.
Returns the type of statement that produced the result. Works like duckdb_v2_result_get_statement_type.
Syntax
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
);
Parameters
result: The result.out_type: Receives the statement type. (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_get_schema
Unstable since 2.0.0.
Returns the Arrow schema of the result's arrays.
Available whenever duckdb_v2_result_get_schema would be.
Syntax
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
);
Parameters
result: The result.out_schema: Caller-allocated schema the library fills. Release it without_schema->release(out_schema). (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR
duckdb_v2_arrow_result_to_arrow_c_stream
Unstable since 2.0.0.
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.
Syntax
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
);
Parameters
result: The result to take over. Set to NULL on success. (ownership passes to the callee)out_stream: Caller-allocated stream the library fills. Release it without_stream->release(out_stream). (out)err: Optional. On failure, receives an opaque info handle the caller must destroy viaduckdb_v2_error_info_destroy.
Return Value
DUCKDB_V2_ERROR