Skip to main content

BindInfo

Struct BindInfo 

Source
pub struct BindInfo { /* private fields */ }
Expand description

Helper wrapper around duckdb_bind_info for use inside bind callbacks.

Provides ergonomic methods for the most common bind operations.

§Example

use quack_rs::table::BindInfo;
use quack_rs::types::TypeId;
use libduckdb_sys::duckdb_bind_info;

unsafe extern "C" fn my_bind(info: duckdb_bind_info) {
    unsafe {
        BindInfo::new(info)
            .add_result_column("id",   TypeId::BigInt)
            .add_result_column("name", TypeId::Varchar)
            .set_cardinality(100, true);
    }
}

Implementations§

Source§

impl BindInfo

Source

pub const unsafe fn new(info: duckdb_bind_info) -> Self

Wraps a raw duckdb_bind_info.

§Safety

info must be a valid duckdb_bind_info provided by DuckDB in a bind callback.

Source

pub fn add_result_column(&self, name: &str, type_id: TypeId) -> &Self

Declares an output column with the given name and type.

Call this once per output column in the order they will appear in the result.

If name contains an interior null byte it is truncated at that point.

§Rejected types

A type that cannot be a result column is reported as a bind error (via set_error) naming the column, and the column is not added:

  • ANY (and, through add_result_column_with_type, any type containing ANY or INVALID, such as LIST(ANY)). duckdb_bind_add_result_column would silently drop such a column, shifting the index of every column declared after it.
  • A composite id (List, Struct, Decimal, …) that needs its own LogicalType constructor; use add_result_column_with_type. (This used to panic.)

The query then fails at bind time with that message, even if the bind callback goes on to succeed.

Do not call this in the bind of a COPY … FROM reader (see CopyFunctionBuilder::copy_from, duckdb-1-5): there the target table fixes the columns, and a declared one widens every chunk the INSERT receives past the table.

Source

pub fn result_column_count(&self) -> usize

Number of result columns DuckDB already knows this table function must produce.

Zero for an ordinary table function, which is expected to declare its own columns with add_result_column. Non-zero when the function is driving a COPY … FROM: the target table’s schema is fixed before the bind callback runs, and duckdb.h is explicit that such a function “should not define its own result columns using duckdb_bind_add_result_column” and should read the expected schema from here instead.

Requires duckdb-1-5.

§Example
use quack_rs::table::BindInfo;

// A COPY ... FROM reader adapts to the table it is loading into.
for i in 0..bind.result_column_count() {
    let name = bind.result_column_name(i).unwrap_or_default();
    // SAFETY: `i` is in range.
    let ty = unsafe { bind.result_column_type(i) };
    let _ = (name, ty);
}
Source

pub fn result_column_name(&self, index: usize) -> Option<String>

Name of result column index, or None if it is out of range.

The C API returns a borrowed pointer into DuckDB’s own storage — names[col_idx].c_str() — which duckdb.h says “must not be destroyed” and which is only valid “for the duration of the bind callback or until the next call to duckdb_bind_add_result_column”. This copies it, so the returned String is not subject to either restriction (pitfall P11).

Requires duckdb-1-5.

Source

pub unsafe fn result_column_type(&self, index: usize) -> Option<LogicalType>

Type of result column index, or None if it is out of range.

Unlike result_column_name this handle is owned — duckdb_table_function_bind_get_result_column_type returns a freshly allocated LogicalType — so it is wrapped in LogicalType, which destroys it on drop.

Requires duckdb-1-5.

§Safety

Must be called during the bind callback, while self.info is live.

Source

pub fn add_result_column_with_type( &self, name: &str, logical_type: &LogicalType, ) -> &Self

Adds an output column with a pre-built LogicalType.

Use this when the column type is a complex type (LIST, STRUCT, MAP) built via LogicalType::list, LogicalType::struct_type, or LogicalType::map.

If name contains an interior null byte it is truncated at that point.

A type containing ANY or INVALID is reported as a bind error rather than added; see “Rejected types” on add_result_column.

Source

pub fn set_cardinality(&self, rows: u64, is_exact: bool) -> &Self

Sets a cardinality hint for the query optimizer.

§What is_exact actually does

duckdb.h describes is_exact as “whether or not the cardinality is exact”. DuckDB 2.0.0 implements that; every 1.x release up to and including 1.5.6 implements it the other way round (src/main/capi/table_function-c.cpp, duckdb_bind_set_cardinality):

is_exactNodeStatistics recorded, 1.xNodeStatistics recorded, 2.0.0
trueNodeStatistics(rows) — an estimate onlyNodeStatistics(rows, rows) — the estimate and max_cardinality = rows
falseNodeStatistics(rows, rows) — the estimate and max_cardinality = rowsNodeStatistics(rows) — an estimate only

The estimate drives plan costing either way (EXPLAIN shows ~rows for both). The upper bound additionally feeds the optimizer’s statistics propagation for joins and set operations (src/optimizer/statistics/operator/propagate_join.cpp), which treats it as a limit. quack-rs passes the flag through unchanged, so the same call records a bound on one engine and a plain estimate on the other. For an extension that may load into either, the only safe call is one whose rows the scan never exceeds — then a recorded bound is true whichever flag records it. A guess the scan may exceed is safe with true on 1.x and with false on 2.0.0 only: choose the flag by the engine’s version (crate::abi::engine_version) or set no hint.

§The hint is clamped to i64::MAX

DuckDB converts the hint to a signed 64-bit count when it estimates a join, and a value above i64::MAX makes any query that joins or cross-joins the function fail with INTERNAL Error: Information loss on integer cast (measured on 1.5.6 with u64::MAX, the “unknown” a careless caller passes). No table has that many rows, so a larger rows is clamped to i64::MAX instead of being passed on.

Source

pub fn set_error(&self, message: &str)

Reports an error from the bind callback.

After calling this, DuckDB will abort query parsing and report the error.

An interior null byte in message is replaced by ?. An empty message is replaced by EMPTY_ERROR_PLACEHOLDER.

Source

pub fn parameter_count(&self) -> usize

Returns the number of positional parameters passed to this function call.

Source

pub unsafe fn get_parameter(&self, index: u64) -> duckdb_value

Returns the parameter value at the given positional index.

§Safety
  • index must be less than parameter_count.
  • The caller is responsible for destroying the returned duckdb_value.
Source

pub unsafe fn get_named_parameter(&self, name: &str) -> duckdb_value

Returns the parameter value for the given named parameter.

§Safety
  • name must correspond to a named parameter declared for this function.
  • The caller is responsible for destroying the returned duckdb_value.

If name contains an interior null byte it is truncated at that point.

Source

pub unsafe fn get_parameter_value(&self, index: u64) -> Value

Returns the positional parameter at index as an owned Value.

The returned Value is RAII-managed — it will call duckdb_destroy_value on drop, so the caller does not need to manually free it.

§Safety

index must be less than parameter_count.

Source

pub unsafe fn get_named_parameter_value(&self, name: &str) -> Value

Returns the named parameter as an owned Value.

The returned Value is RAII-managed — it will call duckdb_destroy_value on drop.

§A parameter the caller did not supply

Named parameters are optional in SQL. When the query does not pass name := ..., DuckDB returns a null handle, and so does this: the returned Value has is_null == true. Test for that, or read it with a defaulting accessor such as as_i64_or, before using a plain getter.

§Safety

name must correspond to a named parameter declared for this function.

If name contains an interior null byte it is truncated at that point.

Source

pub unsafe fn get_extra_info(&self) -> *mut c_void

Returns the extra info pointer set on the table function.

§Safety

The caller must ensure the returned pointer (if non-null) is used according to its original type.

Source

pub unsafe fn get_client_context(&self) -> ClientContext

Returns the client context for this callback.

The returned ClientContext provides access to the connection’s catalog, configuration, and connection ID.

§Safety

The inner handle must be valid (requires DuckDB runtime), and the returned context must not be used after the connection running this query is closed — see ClientContext.

Source

pub const fn as_raw(&self) -> duckdb_bind_info

Returns the raw duckdb_bind_info handle.

Trait Implementations§

Source§

impl Debug for BindInfo

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.