Skip to main content

Module replacement_scan

Module replacement_scan 

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

ReplacementScanBuilder
Builder / registration helper for DuckDB replacement scans.
ReplacementScanInfo
Ergonomic wrapper around duckdb_replacement_scan_info.

Type Aliases§

ReplacementScanFn
The replacement scan callback signature.