Expand description
Builder for registering DuckDB custom cast functions.
Cast functions let an extension define how to convert values from one type to
another, covering both explicit CAST(x AS T) and implicit coercions that
DuckDB may insert automatically.
§How cast functions work
SELECT my_value::MyTargetType
↓
DuckDB looks up registered casts from source type → target type
↓
Calls your cast callback with:
- info: duckdb_function_info (use for extra data / error reporting)
- count: idx_t (number of rows in this chunk)
- input: duckdb_vector (source values)
- output: duckdb_vector (destination — write results here)
↓
Returns true when every row converted (see "TRY CAST vs normal CAST")§TRY CAST vs normal CAST
CastFunctionInfo::cast_mode reports CastMode::Try whenever DuckDB
asks for errors to be collected rather than thrown — for TRY_CAST(x AS T),
and also for the casts DuckDB applies to single values internally, such
as converting a table function’s argument to its declared parameter type
(Value::CastAs). In this mode, call CastFunctionInfo::set_row_error
for each row that fails to convert: it records the message and sets
that row to NULL.
Return false whenever a row failed, in either mode. In a normal
CAST, false fails the query with the message you set. In a TRY_CAST,
DuckDB ignores the return value
(src/execution/expression_executor/execute_cast.cpp), so the rows you
nulled are the answer — returning false does not null anything for
you. In an internal value cast, false is the only signal: DuckDB throws
Failed to cast value: <your message>, whereas true hands back a NULL
silently. See CastFn for details; cast_callback!
nulls every row for you only when the body panics.
§A cast replaces DuckDB’s own for that pair
Registering a cast for a source/target pair DuckDB already converts —
VARCHAR → INTEGER, say — replaces the built-in conversion for the whole
database: every connection, TRY_CAST, and the implicit casts DuckDB
inserts, such as the one an INSERT of a string into an INTEGER column
performs.
The first registration for a pair wins. Registering a cast for a pair
that an extension has already registered — this one or another — succeeds
and does nothing: DuckDB files casts in a std::map with insert, which
never overwrites (MapCastInfo::AddEntry, cast_function_set.cpp), and
frees the new registration’s extra_info at once. Neither case is refused
or reported, and the C API offers no way to ask whether a pair is already
cast. Overriding is sometimes
the point; when it is not, register casts to or from a type the extension
owns (a named type from LogicalType::register).
tests/ffi_roundtrip/table_cast.rs pins both behaviours.
§Example: register a VARCHAR → INTEGER cast
This replaces the built-in VARCHAR → INTEGER cast (see above); it is here
to show the callback’s shape.
use quack_rs::cast::{CastFunctionBuilder, CastFunctionInfo, CastMode};
use quack_rs::types::TypeId;
use quack_rs::vector::{VectorReader, VectorWriter};
use libduckdb_sys::{duckdb_connection, duckdb_function_info, duckdb_vector, idx_t};
unsafe extern "C" fn varchar_to_int(
info: duckdb_function_info,
count: idx_t,
input: duckdb_vector,
output: duckdb_vector,
) -> bool {
let cast_info = unsafe { CastFunctionInfo::new(info) };
let reader = unsafe { VectorReader::from_vector(input, count as usize) };
let mut writer = unsafe { VectorWriter::new(output) };
for row in 0..count as usize {
if !unsafe { reader.is_valid(row) } {
unsafe { writer.set_null(row) };
continue;
}
let s = unsafe { reader.read_str(row) };
match s.parse::<i32>() {
Ok(v) => unsafe { writer.write_i32(row, v) },
Err(e) => {
if cast_info.cast_mode() == CastMode::Try {
let msg = format!("cannot cast {:?} to INTEGER: {e}", s);
unsafe { cast_info.set_row_error(&msg, row as idx_t, output) };
unsafe { writer.set_null(row) };
} else {
let msg = format!("cannot cast {:?} to INTEGER: {e}", s);
unsafe { cast_info.set_error(&msg) };
return false;
}
}
}
}
true
}
// fn register(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
// unsafe {
// CastFunctionBuilder::new(TypeId::Varchar, TypeId::Integer)
// .function(varchar_to_int)
// .register(con)
// }
// }Re-exports§
pub use builder::CastFn;pub use builder::CastFunctionBuilder;pub use builder::CastFunctionInfo;pub use builder::CastMode;
Modules§
- builder
- Builder for registering custom
DuckDBcast functions.