Expand description
Builder for registering DuckDB replacement scans.
Replacement scans enable the SELECT * FROM 'my_file.xyz' pattern.
When DuckDB encounters an unrecognized table reference (including a string
literal like 'data.parquet'), it calls all registered replacement scan
callbacks in registration order, giving each a chance to redirect the scan
to a known table function.
§How replacement scans work
SELECT * FROM 'data.myformat'
↓
`DuckDB` does not know 'data.myformat' as a table
↓
Calls each registered replacement scan callback with:
- info: duckdb_replacement_scan_info (use to redirect or error)
- table_name: *const c_char (the unrecognized identifier, e.g. "data.myformat")
- data: *mut c_void (your extra_data, if any)
↓
Callback either:
- Redirects: duckdb_replacement_scan_set_function_name + add_parameter
- Ignores: returns without calling any scan API (`DuckDB` tries the next callback)
- Errors: duckdb_replacement_scan_set_error§The callback sees only the table name
table_name is the last part of the reference, with any catalog or schema
stripped: SELECT * FROM nosuchschema."s.xyz" and
SELECT * FROM memory.main."s.xyz" both reach the callback as s.xyz,
and a redirect answers either. A callback that must honour a schema cannot
tell it from here.
§Example: Route all .xyz files to a custom table function
use quack_rs::replacement_scan::{ReplacementScanBuilder, ReplacementScanInfo};
use libduckdb_sys::duckdb_replacement_scan_info;
use std::os::raw::c_char;
unsafe extern "C" fn my_scan(
info: duckdb_replacement_scan_info,
table_name: *const c_char,
_data: *mut std::os::raw::c_void,
) {
let name = unsafe { std::ffi::CStr::from_ptr(table_name).to_string_lossy() };
if !name.ends_with(".xyz") {
return; // not ours — let `DuckDB` try other callbacks
}
// Redirect to our table function and pass the filename as a parameter.
unsafe {
ReplacementScanInfo::new(info)
.set_function("read_xyz")
.add_varchar_parameter(name.as_ref());
}
}
// fn register(db: libduckdb_sys::duckdb_database) {
// unsafe { ReplacementScanBuilder::register(db, my_scan, std::ptr::null_mut(), None); }
// }Structs§
- Replacement
Scan Builder - Builder / registration helper for
DuckDBreplacement scans. - Replacement
Scan Info - Ergonomic wrapper around
duckdb_replacement_scan_info.
Type Aliases§
- Replacement
Scan Fn - The replacement scan callback signature.