pub struct TableFunctionBuilder { /* private fields */ }Expand description
Builder for registering a DuckDB table function.
Table functions are the most powerful extension type — they can return arbitrary result schemas, support named parameters, projection pushdown, and parallel execution.
§Required fields
§Optional features
param: positional parameters.named_param: named parameters (name := value).local_init: per-thread scan state. It does not by itself make the scan parallel;InitInfo::set_max_threadsdoes.projection_pushdown: hint projection info toDuckDB.extra_info: function-level data available in all callbacks.
Implementations§
Source§impl TableFunctionBuilder
impl TableFunctionBuilder
Sourcepub fn new(name: &str) -> Self
pub fn new(name: &str) -> Self
Creates a new builder for a table function with the given name.
§Panics
Panics if name contains an interior null byte.
Sourcepub fn try_new(name: &str) -> Result<Self, ExtensionError>
pub fn try_new(name: &str) -> Result<Self, ExtensionError>
Creates a new builder with function name validation.
§Errors
Returns ExtensionError if the name is invalid.
Sourcepub fn name(&self) -> &str
pub fn name(&self) -> &str
Returns the function name.
Useful for introspection and for MockRegistrar.
Sourcepub fn param_logical(self, logical_type: LogicalType) -> Self
pub fn param_logical(self, logical_type: LogicalType) -> Self
Adds a positional parameter with a complex LogicalType.
Use this for parameterized types that TypeId cannot express, such as
LIST(BIGINT), MAP(VARCHAR, INTEGER), or STRUCT(...).
Sourcepub fn named_param(self, name: &str, type_id: TypeId) -> Self
pub fn named_param(self, name: &str, type_id: TypeId) -> Self
Adds a named parameter (e.g., my_fn(path := 'data.csv')).
Named parameters are accessed in the bind callback via
duckdb_bind_get_named_parameter.
§Panics
Panics if name contains an interior null byte.
Sourcepub fn named_param_logical(self, name: &str, logical_type: LogicalType) -> Self
pub fn named_param_logical(self, name: &str, logical_type: LogicalType) -> Self
Adds a named parameter with a complex LogicalType.
Use this for parameterized types that TypeId cannot express.
§Panics
Panics if name contains an interior null byte.
Sourcepub fn bind(self, f: BindFn) -> Self
pub fn bind(self, f: BindFn) -> Self
Sets the bind callback.
The bind callback is called once at query-parse time. It must:
- Declare all output columns via
crate::table::BindInfo::add_result_column. - Optionally read parameters and store bind data via
crate::table::FfiBindData::set.
§At least one column
A bind that returns without declaring a column (and without calling
BindInfo::set_error) makes
DuckDB fail the query with an INTERNAL Error — “Table function must
return at least one column”, with a C++ stack trace
(src/planner/binder/tableref/bind_table_function.cpp). A raw callback
cannot be checked after it returns, so report the problem yourself with
set_error. The typed builder
does this for you.
Sourcepub fn init(self, f: InitFn) -> Self
pub fn init(self, f: InitFn) -> Self
Sets the global init callback.
Called once per query. Use crate::table::FfiInitData::set to store global scan state.
Sourcepub fn local_init(self, f: InitFn) -> Self
pub fn local_init(self, f: InitFn) -> Self
Sets the per-thread local init callback (optional).
When set, DuckDB calls this once per worker thread that runs the scan.
Use crate::table::FfiLocalInitData::set to store thread-local scan state.
Setting a local init does not make the scan parallel. DuckDB
schedules at most MaxThreads scanners, and a C API table function’s
MaxThreads is exactly what the global init passed to
InitInfo::set_max_threads —
1 when it was never called (src/main/capi/table_function-c.cpp,
CTableGlobalInitData::MaxThreads). Parallelism needs set_max_threads
above 1; local_init only gives each of those threads its own state.
Sourcepub fn scan(self, f: ScanFn) -> Self
pub fn scan(self, f: ScanFn) -> Self
Sets the scan callback.
Called repeatedly until all rows are produced. Set the output chunk’s size
to 0 (via duckdb_data_chunk_set_size(output, 0)) to signal end of stream.
Sourcepub const fn projection_pushdown(self, enable: bool) -> Self
pub const fn projection_pushdown(self, enable: bool) -> Self
Enables or disables projection pushdown support (default: disabled).
When enabled, DuckDB informs the init callback which columns were
requested. Use duckdb_init_get_column_count and duckdb_init_get_column_index
in your init callback to skip producing unrequested columns.
A builder returned by
TypedTableFunctionBuilder::build
is refused at registration with pushdown on: its scan closure cannot
see the projection.
Sourcepub unsafe fn extra_info(
self,
data: *mut c_void,
destroy: ExtraDestroyFn,
) -> Self
pub unsafe fn extra_info( self, data: *mut c_void, destroy: ExtraDestroyFn, ) -> Self
Sets function-level extra info shared across all callbacks.
This data is available via duckdb_function_get_extra_info and
duckdb_bind_get_extra_info in all callbacks. The destroy callback
is called by DuckDB when the function is dropped.
§Safety
datamust remain valid untilDuckDBcallsdestroy. The typical pattern is to box your data:Box::into_raw(Box::new(my_data)).cast().- The pointee must be
Send + Sync.DuckDBhands the same pointer to bind, init and scan on whichever threads run them — several at once when queries run concurrently or the scan is parallel (InitInfo::set_max_threadsabove 1) — anddestroyruns on whichever thread releases the function. Shared mutable state behind the pointer needs aMutexor atomics. destroymust not panic; wrap its body incatch_ffi_panic.- The pointee must be the type the installed callbacks read it as. A
builder from
TypedTableFunctionBuilder::buildcarries its ownextra_info; replacing it is refused at registration.
Sourcepub unsafe fn register(
self,
con: duckdb_connection,
) -> Result<(), ExtensionError>
pub unsafe fn register( self, con: duckdb_connection, ) -> Result<(), ExtensionError>
Registers the table function on the given connection.
§A name can be registered once
duckdb_register_table_function adds the function to the system
catalog, which keys table functions by name, and the C API has no table
function sets, so there is no way to add an overload to a name that
exists: the existing entry keeps answering. What the call reports about
the duplicate differs by release — v1.5.x asks for ALTER_ON_CONFLICT,
which keeps the existing entry, drops the new function and returns
success; v1.4.x leaves the default ERROR_ON_CONFLICT, so the catalog
throws and the call fails with no reason to report
(DuckSchemaEntry::AddEntryInternal,
src/catalog/catalog_entry/duck_schema_entry.cpp). A second register
under the same name, a name another extension registered, or a built-in’s
name (range, read_csv) therefore does not take effect either way:
the old function keeps answering. So register checks
duckdb_functions() first and refuses a name that is already a
table function or table macro in the system catalog (compared
case-insensitively, as DuckDB resolves names).
Registering through the entry point’s
Connection checks against a snapshot
of the catalog listed on the first registration and kept up to date with
that connection’s own registrations, so an extension with many table
functions lists the catalog once per LOAD rather than once per
function. Being a one-time copy, the snapshot does not see a table
function registered on the raw connection after it was listed — by
another extension’s LOAD, or by a direct call to this method — so a
later register_table under that name passes the check and is left to
DuckDB, which drops it with a success report on v1.5.x and fails the
call with no reason on v1.4.x. The scalar check has the same gap.
Table functions registered through the C API live only in the
in-memory system catalog and are never written to a database file, so
a name found there is always a live conflict — not a leftover from an
earlier session that the next LOAD would trip over.
The check does not look in user databases. A table macro of the same
name there — CREATE MACRO f() AS TABLE …, persisted in the database
file — does not stop the registration, but it shadows the function
for unqualified calls from that database: SELECT * FROM f() runs the
macro, and only system.main.f() reaches the extension’s function.
Refusing here would make the extension fail to load into any database
that happens to hold such a macro, so the name is left to the user.
§Errors
Returns ExtensionError if:
- The name is already taken (see above), or the check cannot run.
- A parameter or named parameter was given as a bare composite
TypeId(DECIMAL,ENUM,LIST,STRUCT,MAP,ARRAY,UNION); build it as aLogicalTypeand use the*_logicalmethod. The error names the slot. - The bind, init, or scan callback was not set.
- The builder came from
TypedTableFunctionBuilder::buildandprojection_pushdownwas switched on, orbind,init,local_init,scanorextra_inforeplaced, afterwards. DuckDBreports a registration failure.
§Cost
Each call lists the catalog once — one scan of duckdb_functions(),
tens of milliseconds on DuckDB 1.5.x, hardware-dependent.
Registering through the entry point’s
Connection instead (its
Registrar methods) lists the catalog
once per extension load, so an extension with many table functions
pays for one scan rather than one per function.
§Safety
con must be a valid, open duckdb_connection.
Sourcepub unsafe fn build_handle(self) -> Result<TableFunctionHandle, ExtensionError>
pub unsafe fn build_handle(self) -> Result<TableFunctionHandle, ExtensionError>
Builds a configured, unregistered duckdb_table_function.
register is this plus
duckdb_register_table_function. The handle is exposed separately
because COPY … FROM needs a table function that is attached to a copy
function rather than registered on its own — see
CopyFunctionBuilder::copy_from (duckdb-1-5).
§Errors
Returns ExtensionError if a parameter type is invalid, if the bind,
init or scan callback was not set, or if projection pushdown was
switched on, or a callback or extra_info replaced, after a typed
builder’s build (see
register).
§Safety
The DuckDB C API dispatch table must be initialised (it always is
inside an extension).
Source§impl TableFunctionBuilder
impl TableFunctionBuilder
Sourcepub fn with_state<S, F>(self, bind: F) -> TypedTableFunctionBuilder<S>
pub fn with_state<S, F>(self, bind: F) -> TypedTableFunctionBuilder<S>
Switches this builder into closure-based “typed state” mode, with the scan state cloned from a template for every execution.
The supplied bind closure runs once per bind (see the
module docs for what that means for prepared
statements). It must:
- Declare the output schema via
BindInfo::add_result_column— at least one column. Withduckdb-1-5, a bind that declares none is reported as an ordinary bind error instead of theINTERNAL ErrorDuckDBraises for it. Used as aCOPY … FROMreader, it must instead declare none and read the target table’s columns (BindInfo::result_column_count); withduckdb-1-5a column declared there fails the bind. - Read parameters (positional or named) from the
BindInfo. - Return the template scan state
Son success, or anExtensionErroron failure. Errors are propagated toDuckDBviaduckdb_bind_set_error.
Every execution of the bound plan starts from template.clone(), so a
prepared statement executed twice scans the same rows twice. If S is
expensive or impossible to clone, use
with_bind_init instead.
Continue building the function by calling scan.
See the module-level docs for an end-to-end example.
Sourcepub fn with_bind_init<B, S, FB, FI>(
self,
bind: FB,
init: FI,
) -> TypedTableFunctionBuilder<S>
pub fn with_bind_init<B, S, FB, FI>( self, bind: FB, init: FI, ) -> TypedTableFunctionBuilder<S>
Switches this builder into closure-based “typed state” mode, with
immutable bind data B and a fresh scan state S built from it for
every execution.
bindruns once per bind: declare the output schema withBindInfo::add_result_column, read parameters, and return the bind dataB.initruns once per execution of the bound plan — everyEXECUTEof a prepared statement, every re-scan inside a recursive CTE — and builds the scan stateSfrom&B. This is where to open files or reset cursors.
B must be Send + Sync because DuckDB may run init for the same
bind data on any worker thread. S need only be Send: scans are
serialised (see the module docs).
Errors from either closure are reported to DuckDB (bind as a binder
error, init as an invalid-input error).
§Example
use quack_rs::prelude::*;
struct Params { n: i64 }
struct Cursor { next: i64, end: i64 }
fn register(reg: &impl Registrar) -> ExtResult<()> {
let builder = TableFunctionBuilder::new("count_up")
.param(TypeId::BigInt)
.with_bind_init(
|bind| {
bind.add_result_column("n", TypeId::BigInt);
let n = unsafe { bind.get_parameter_value(0) }.as_i64_or(0);
Ok(Params { n })
},
|params: &Params| Ok(Cursor { next: 1, end: params.n }),
)
.scan(|cursor, chunk| {
if cursor.next > cursor.end {
unsafe { chunk.set_size(0) };
return Ok(());
}
unsafe {
chunk.writer(0).write_i64(0, cursor.next);
chunk.set_size(1);
}
cursor.next += 1;
Ok(())
})
.build()?;
unsafe { reg.register_table(builder) }
}