Skip to main content

Module table

Module table 

Source
Expand description

Builder for registering DuckDB table functions.

Table functions are the most powerful extension type — they bridge the gap between “toy” and “real” extensions. Unlike scalar or aggregate functions that transform existing data, table functions generate data from scratch: reading files, querying remote APIs, parsing custom formats, or producing synthetic datasets.

§Table function lifecycle

bind  ─── declare output schema, read parameters, hint cardinality
init  ─── allocate global scan state (shared across threads)
local_init ─── allocate per-thread scan state (optional; parallelism comes
               from InitInfo::set_max_threads in init, not from local_init)
scan  ─── fill output chunk; repeat until chunk size == 0

§Key types

TypePurpose
TableFunctionBuilderRegisters the table function with DuckDB (raw callback mode)
TypedTableFunctionBuilderClosure-based builder with typed, mutable scan state
BindInfoErgonomic wrapper for duckdb_bind_info in bind callbacks
InitInfoErgonomic wrapper for duckdb_init_info in init callbacks
FunctionInfoErgonomic wrapper for duckdb_function_info in scan callbacks
FfiBindData<T>Type-safe bind-phase data storage
FfiInitData<T>Type-safe global init-phase data storage
FfiLocalInitData<T>Type-safe per-thread init-phase data storage

§Two layers: raw vs. typed

  • Reach for TypedTableFunctionBuilder first. It hides the bind/init/scan trampolines behind safe Rust closures, gives every execution a fresh typed scan state built from what bind produced, and catches panics via catch_unwind. See the typed module for the full API and an end-to-end example.
  • Drop down to TableFunctionBuilder when you need raw control: projection pushdown (the typed builder does not offer it), parallel scans (InitInfo::set_max_threads above 1, usually with local_init for per-thread state), or any callback shape that doesn’t fit the “produce state in bind, mutate it in scan” model.

§Example: Simple table function

use quack_rs::table::{TableFunctionBuilder, FfiBindData, FfiInitData, BindInfo, InitInfo};
use quack_rs::types::TypeId;
use libduckdb_sys::{duckdb_bind_info, duckdb_init_info, duckdb_function_info,
                    duckdb_data_chunk, duckdb_data_chunk_set_size};

struct Config { count: u64 }
struct State  { row:   u64 }

unsafe extern "C" fn bind(info: duckdb_bind_info) {
    unsafe {
        BindInfo::new(info)
            .add_result_column("n", TypeId::BigInt)
            .set_cardinality(3, true);
        FfiBindData::<Config>::set(info, Config { count: 3 });
    }
}

unsafe extern "C" fn init(info: duckdb_init_info) {
    unsafe { FfiInitData::<State>::set(info, State { row: 0 }); }
}

unsafe extern "C" fn scan(info: duckdb_function_info, output: duckdb_data_chunk) {
    unsafe {
        let cfg   = FfiBindData::<Config>::get_from_function(info);
        let state = FfiInitData::<State>::get_mut(info);
        if let (Some(cfg), Some(state)) = (cfg, state) {
            if state.row >= cfg.count {
                duckdb_data_chunk_set_size(output, 0);
                return;
            }
            // write data into `output`…
            state.row += 1;
            duckdb_data_chunk_set_size(output, 1);
        }
    }
}

// fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
//     unsafe {
//         TableFunctionBuilder::new("generate_n")
//             .bind(bind)
//             .init(init)
//             .scan(scan)
//             .register(con)
//     }
// }

Re-exports§

pub use bind_data::FfiBindData;
pub use builder::BindFn;
pub use builder::InitFn;
pub use builder::ScanFn;
pub use builder::TableFunctionBuilder;
pub use builder::TableFunctionHandle;
pub use info::BindInfo;
pub use info::FunctionInfo;
pub use info::InitInfo;
pub use init_data::FfiInitData;
pub use init_data::FfiLocalInitData;
pub use typed::TypedTableFunctionBuilder;

Modules§

bind_data
Type-safe bind data management for table functions.
builder
Builder for registering DuckDB table functions.
info
Ergonomic wrappers around DuckDB callback info handles.
init_data
Type-safe init data management for table functions.
typed
Closure-based table functions with typed scan state.