Skip to main content

quack_rs/table/
mod.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Builder for registering `DuckDB` table functions.
7//!
8//! Table functions are the most powerful extension type — they bridge the gap
9//! between "toy" and "real" extensions. Unlike scalar or aggregate functions that
10//! transform existing data, table functions **generate** data from scratch: reading
11//! files, querying remote APIs, parsing custom formats, or producing synthetic datasets.
12//!
13//! # Table function lifecycle
14//!
15//! ```text
16//! bind  ─── declare output schema, read parameters, hint cardinality
17//! init  ─── allocate global scan state (shared across threads)
18//! local_init ─── allocate per-thread scan state (optional; parallelism comes
19//!                from InitInfo::set_max_threads in init, not from local_init)
20//! scan  ─── fill output chunk; repeat until chunk size == 0
21//! ```
22//!
23//! # Key types
24//!
25//! | Type | Purpose |
26//! |------|---------|
27//! | [`TableFunctionBuilder`] | Registers the table function with `DuckDB` (raw callback mode) |
28//! | [`TypedTableFunctionBuilder`] | Closure-based builder with typed, mutable scan state |
29//! | [`BindInfo`] | Ergonomic wrapper for `duckdb_bind_info` in bind callbacks |
30//! | [`InitInfo`] | Ergonomic wrapper for `duckdb_init_info` in init callbacks |
31//! | [`FunctionInfo`] | Ergonomic wrapper for `duckdb_function_info` in scan callbacks |
32//! | [`FfiBindData<T>`] | Type-safe bind-phase data storage |
33//! | [`FfiInitData<T>`] | Type-safe global init-phase data storage |
34//! | [`FfiLocalInitData<T>`] | Type-safe per-thread init-phase data storage |
35//!
36//! # Two layers: raw vs. typed
37//!
38//! - Reach for [`TypedTableFunctionBuilder`] first.
39//!   It hides the bind/init/scan trampolines behind safe Rust closures, gives every
40//!   execution a fresh typed scan state built from what `bind` produced, and catches panics via `catch_unwind`.
41//!   See the [`typed`] module for the full API and an end-to-end example.
42//! - Drop down to [`TableFunctionBuilder`] when you need raw control:
43//!   projection pushdown (the typed builder does not offer it), parallel scans
44//!   (`InitInfo::set_max_threads` above 1, usually with `local_init` for per-thread state),
45//!   or any callback shape that doesn't fit the "produce state in bind, mutate it in
46//!   scan" model.
47//!
48//! # Example: Simple table function
49//!
50//! ```rust,no_run
51//! use quack_rs::table::{TableFunctionBuilder, FfiBindData, FfiInitData, BindInfo, InitInfo};
52//! use quack_rs::types::TypeId;
53//! use libduckdb_sys::{duckdb_bind_info, duckdb_init_info, duckdb_function_info,
54//!                     duckdb_data_chunk, duckdb_data_chunk_set_size};
55//!
56//! struct Config { count: u64 }
57//! struct State  { row:   u64 }
58//!
59//! unsafe extern "C" fn bind(info: duckdb_bind_info) {
60//!     unsafe {
61//!         BindInfo::new(info)
62//!             .add_result_column("n", TypeId::BigInt)
63//!             .set_cardinality(3, true);
64//!         FfiBindData::<Config>::set(info, Config { count: 3 });
65//!     }
66//! }
67//!
68//! unsafe extern "C" fn init(info: duckdb_init_info) {
69//!     unsafe { FfiInitData::<State>::set(info, State { row: 0 }); }
70//! }
71//!
72//! unsafe extern "C" fn scan(info: duckdb_function_info, output: duckdb_data_chunk) {
73//!     unsafe {
74//!         let cfg   = FfiBindData::<Config>::get_from_function(info);
75//!         let state = FfiInitData::<State>::get_mut(info);
76//!         if let (Some(cfg), Some(state)) = (cfg, state) {
77//!             if state.row >= cfg.count {
78//!                 duckdb_data_chunk_set_size(output, 0);
79//!                 return;
80//!             }
81//!             // write data into `output`…
82//!             state.row += 1;
83//!             duckdb_data_chunk_set_size(output, 1);
84//!         }
85//!     }
86//! }
87//!
88//! // fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
89//! //     unsafe {
90//! //         TableFunctionBuilder::new("generate_n")
91//! //             .bind(bind)
92//! //             .init(init)
93//! //             .scan(scan)
94//! //             .register(con)
95//! //     }
96//! // }
97//! ```
98
99pub mod bind_data;
100pub mod builder;
101pub(crate) mod collision;
102pub(crate) mod cstr;
103pub mod info;
104pub mod init_data;
105pub(crate) mod type_check;
106pub mod typed;
107
108pub use bind_data::FfiBindData;
109pub use builder::{BindFn, InitFn, ScanFn, TableFunctionBuilder, TableFunctionHandle};
110pub use info::{BindInfo, FunctionInfo, InitInfo};
111pub use init_data::{FfiInitData, FfiLocalInitData};
112pub use typed::TypedTableFunctionBuilder;