Skip to main content

TableFunctionBuilder

Struct TableFunctionBuilder 

Source
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

Implementations§

Source§

impl TableFunctionBuilder

Source

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.

Source

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.

Source

pub fn name(&self) -> &str

Returns the function name.

Useful for introspection and for MockRegistrar.

Source

pub fn param(self, type_id: TypeId) -> Self

Adds a positional parameter with the given type.

Source

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(...).

Source

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.

Source

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.

Source

pub fn bind(self, f: BindFn) -> Self

Sets the bind callback.

The bind callback is called once at query-parse time. It must:

§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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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
  • data must remain valid until DuckDB calls destroy. The typical pattern is to box your data: Box::into_raw(Box::new(my_data)).cast().
  • The pointee must be Send + Sync. DuckDB hands 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_threads above 1) — and destroy runs on whichever thread releases the function. Shared mutable state behind the pointer needs a Mutex or atomics.
  • destroy must not panic; wrap its body in catch_ffi_panic.
  • The pointee must be the type the installed callbacks read it as. A builder from TypedTableFunctionBuilder::build carries its own extra_info; replacing it is refused at registration.
Source

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 a LogicalType and use the *_logical method. The error names the slot.
  • The bind, init, or scan callback was not set.
  • The builder came from TypedTableFunctionBuilder::build and projection_pushdown was switched on, or bind, init, local_init, scan or extra_info replaced, afterwards.
  • DuckDB reports 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.

Source

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

Source

pub fn with_state<S, F>(self, bind: F) -> TypedTableFunctionBuilder<S>
where S: Clone + Send + 'static, F: Fn(&BindInfo) -> Result<S, ExtensionError> + Send + Sync + 'static,

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. With duckdb-1-5, a bind that declares none is reported as an ordinary bind error instead of the INTERNAL Error DuckDB raises for it. Used as a COPY … FROM reader, it must instead declare none and read the target table’s columns (BindInfo::result_column_count); with duckdb-1-5 a column declared there fails the bind.
  • Read parameters (positional or named) from the BindInfo.
  • Return the template scan state S on success, or an ExtensionError on failure. Errors are propagated to DuckDB via duckdb_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.

Source

pub fn with_bind_init<B, S, FB, FI>( self, bind: FB, init: FI, ) -> TypedTableFunctionBuilder<S>
where B: Send + Sync + 'static, S: Send + 'static, FB: Fn(&BindInfo) -> Result<B, ExtensionError> + Send + Sync + 'static, FI: Fn(&B) -> Result<S, ExtensionError> + Send + Sync + 'static,

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.

  • bind runs once per bind: declare the output schema with BindInfo::add_result_column, read parameters, and return the bind data B.
  • init runs once per execution of the bound plan — every EXECUTE of a prepared statement, every re-scan inside a recursive CTE — and builds the scan state S from &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) }
}

Trait Implementations§

Source§

impl Debug for TableFunctionBuilder

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.