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;