Skip to main content

Module cast

Module cast 

Source
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 DuckDB cast functions.