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
impl BindInfo
Sourcepub const unsafe fn new(info: duckdb_bind_info) -> Self
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.
Sourcepub fn add_result_column(&self, name: &str, type_id: TypeId) -> &Self
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, throughadd_result_column_with_type, any type containingANYorINVALID, such asLIST(ANY)).duckdb_bind_add_result_columnwould silently drop such a column, shifting the index of every column declared after it.- A composite id (
List,Struct,Decimal, …) that needs its ownLogicalTypeconstructor; useadd_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.
Sourcepub fn result_column_count(&self) -> usize
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);
}Sourcepub fn result_column_name(&self, index: usize) -> Option<String>
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.
Sourcepub unsafe fn result_column_type(&self, index: usize) -> Option<LogicalType>
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.
Sourcepub fn add_result_column_with_type(
&self,
name: &str,
logical_type: &LogicalType,
) -> &Self
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.
Sourcepub fn set_cardinality(&self, rows: u64, is_exact: bool) -> &Self
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_exact | NodeStatistics recorded, 1.x | NodeStatistics recorded, 2.0.0 |
|---|---|---|
true | NodeStatistics(rows) — an estimate only | NodeStatistics(rows, rows) — the estimate and max_cardinality = rows |
false | NodeStatistics(rows, rows) — the estimate and max_cardinality = rows | NodeStatistics(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.
Sourcepub fn set_error(&self, message: &str)
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.
Sourcepub fn parameter_count(&self) -> usize
pub fn parameter_count(&self) -> usize
Returns the number of positional parameters passed to this function call.
Sourcepub unsafe fn get_parameter(&self, index: u64) -> duckdb_value
pub unsafe fn get_parameter(&self, index: u64) -> duckdb_value
Returns the parameter value at the given positional index.
§Safety
indexmust be less thanparameter_count.- The caller is responsible for destroying the returned
duckdb_value.
Sourcepub unsafe fn get_named_parameter(&self, name: &str) -> duckdb_value
pub unsafe fn get_named_parameter(&self, name: &str) -> duckdb_value
Returns the parameter value for the given named parameter.
§Safety
namemust 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.
Sourcepub unsafe fn get_parameter_value(&self, index: u64) -> Value
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.
Sourcepub unsafe fn get_named_parameter_value(&self, name: &str) -> Value
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.
Sourcepub unsafe fn get_extra_info(&self) -> *mut c_void
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.
Sourcepub unsafe fn get_client_context(&self) -> ClientContext
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.