Catalogs

On this page

Presenting a worker as a database: schemas, tables, views, macros.

struct At

source

pub struct At {
  pub unit: String,
  pub value: String,
}

Description

A time-travel coordinate for a read.

struct AttachOptions

source

pub struct AttachOptions {
  pub options: Option<Bytes>,
  pub data_version_spec: Option<String>,
  pub implementation_version: Option<String>,
}

Description

How to attach.

struct AttachedCatalog

source

pub struct AttachedCatalog {
  handle: Bytes,
  info: CatalogAttachResult,
  transaction: Option<Bytes>,
}

Description

A live attach handle.

The attach_opaque_data blob is the worker’s session token: every later call echoes it back, and the worker uses it to find the catalog. Holding it in a value type — rather than borrowing the client — keeps the API free of lifetime tangles, since the handle really is just bytes.

Methods

method default_schema

source

pub fn default_schema(&self) -> &str

The schema a bare table name resolves in.

method handle

source

pub fn handle(&self) -> &Bytes

The worker’s session token for this attach.

method info

source

pub fn info(&self) -> &CatalogAttachResult

Everything the worker reported at attach time.

method supports_transactions

source

pub fn supports_transactions(&self) -> bool

Whether the worker offered transactions.

method transaction

source

pub fn transaction(&self) -> Option<&Bytes>

The transaction handle threaded onto reads, if one is open.

struct CatBranch

source

pub struct CatBranch {
  pub function_name: String,
  pub scan_arguments: Vec<u8>,
  pub branch_filter: Option<String>,
  pub writable: bool,
  pub source_catalog: Option<String>,
  pub source_schema: Option<String>,
  pub source_table: Option<String>,
}

Description

One physical branch of a multi-branch table.

A function branch sets function_name (+ scan_arguments); a catalog-table branch leaves function_name empty and sets source_catalog/source_schema/source_table to scan a companion-catalog base table.

struct CatTable

source

pub struct CatTable {
  pub name: String,
  pub columns: SchemaRef,
  pub scan_function: String,
  pub scan_arguments: Vec<u8>,
  pub comment: Option<String>,
  pub cardinality: Option<i64>,
  pub not_null: Vec<i32>,
  pub primary_key: Vec<Vec<i32>>,
  pub unique: Vec<Vec<i32>>,
  pub check: Vec<String>,
  pub tags: Vec<(String, String)>,
  pub foreign_keys: Vec<ForeignKey>,
  pub inline_scan: bool,
  pub branches: Option<Vec<CatBranch>>,
  pub required_extensions: Vec<String>,
  pub statistics: Vec<crate::statistics::CatColStat>,
  pub time_travel: Vec<TimeTravelVersion>,
  pub required_filters: Vec<Vec<String>>,
  pub supports_time_travel: bool,
  pub scan_function_impl: Option<std::sync::Arc<dyn crate::table_function::TableFunction>>,
}

Description

A function-backed catalog table: scanned by scan_function(scan_args).

Methods

method is_current_version

source

pub fn is_current_version(&self, v: i64) -> bool

Whether v is the current (highest) time-travel version.

method new

source

pub fn new(
  name: &str,
  columns: SchemaRef,
  scan_function: &str,
  scan_arguments: Vec<u8>,
  comment: Option<String>,
  cardinality: Option<i64>,
) -> Self

Constructor with the new metadata fields defaulted empty.

method resolve_version

source

pub fn resolve_version(
  &self,
  at_unit: Option<&str>,
  at_value: Option<&str>,
) -> Result<Option<&TimeTravelVersion>>

Resolve the time-travel version for an AT clause: VERSION (exact), TIMESTAMP (highest version whose timestamp_year <= year), or the current version when no clause. Ok(None) = not a time-travel table.

method with_function

source

pub fn with_function(
  name: &str,
  columns: SchemaRef,
  function: std::sync::Arc<dyn crate::table_function::TableFunction>,
  comment: Option<String>,
  cardinality: Option<i64>,
) -> Self

Build a function-backed table from a TableFunction instance: stores the function (auto-registered by [crate::Worker::set_catalog]) and sets scan_function to its name(). This is the one-call ergonomic equivalent of the Go CatalogTable{ Function: ... } (vs. the name-based [CatTable::new], which requires a separate Worker::register_table). The scan is inlined.

struct CatalogModel

source

pub struct CatalogModel {
  pub name: String,
  pub schemas: Vec<CatSchema>,
  pub comment: Option<String>,
  pub tags: Vec<(String, String)>,
  pub source_url: Option<String>,
  pub supports_time_travel: bool,
  pub implementation_version: Option<String>,
  pub data_version_spec: Option<String>,
  pub supported_data_versions: Vec<String>,
  pub default_data_version: Option<String>,
  pub supported_implementation_versions: Vec<String>,
  pub npm_version_resolution: bool,
  pub version_schemas: std::collections::HashMap<String, Vec<CatSchema>>,
  pub attach_option_specs: Vec<Vec<u8>>,
  pub attach_options_default_batch: Option<Vec<u8>>,
  pub global_functions: Vec<String>,
  pub global_function_prefix: String,
}

Description

A declarative catalog: named schemas with views, macros, and tables.

Methods

method schemas_for

source

pub fn schemas_for(&self, version: Option<&str>) -> &[CatSchema]

The schema set visible for a given resolved data version (or the base schemas when the catalog is not version-shaped / the version is unknown).

struct ForeignKey

source

pub struct ForeignKey {
  pub columns: Vec<String>,
  pub referenced_table: String,
  pub referenced_columns: Vec<String>,
}

Description

A foreign-key constraint (referenced table in the same schema by default).

enum FunctionKind

source

pub enum FunctionKind {
  Table,
  Scalar,
  Aggregate,
}

Description

Which kind of function to list from a schema.

Wire spelling

The type parameter of catalog_schema_contents_functions is Python’s SchemaObjectType, and an enum crosses the wire as its member name, not its value — vgi_rpc/rpc/_wire.py::_convert_for_arrow is explicit about it (“Enum → .name”) and the reader is base[value], a name lookup that raises KeyError on anything else. So the spelling is TABLE_FUNCTION, never table.

The Rust reference worker accepts both — normalize_function_type in vgi::dispatch lowercases and strips a _function suffix — so a client that sends the short form works there and fails against the canonical Python worker. That leniency is why this was wrong for as long as it was.

Why buffered and table-in-out are absent

They are not listing filters. SchemaObjectType has one TABLE_FUNCTION member covering all three shapes; which shape a given function is comes back on FunctionInfo::function_type in the response.

Methods

method as_str

source

pub fn as_str(self) -> &’static str

The wire spelling: a SchemaObjectType member name.

constant MAIN_SCHEMA

source

pub const MAIN_SCHEMA: &str = “main”;

Description

The default schema name every registered function lives under.

enum MacroKind

source

pub enum MacroKind {
  Scalar,
  Table,
}

Description

Which kind of macro to list from a schema.

Same SchemaObjectType member-name spelling as [FunctionKind].

Methods

method as_str

source

pub fn as_str(self) -> &’static str

The wire spelling: a SchemaObjectType member name.

struct MissingAttachOptions

source

pub struct MissingAttachOptions {
  pub catalog_name: String,
  pub missing: Vec<String>,
}

Description

Raised when catalog_attach omits options declared required.

Carries the option names so a caller can act on them without parsing the message. The message text mirrors Python’s MissingAttachOptionsError — the extension’s integration suite matches on it.

struct SecretTypeSpec

source

pub struct SecretTypeSpec {
  pub name: String,
  pub description: String,
  pub parameters_schema: Arc<Schema>,
}

Description

A secret type the worker registers (surfaced in catalog_attach).

struct SettingSpec

source

pub struct SettingSpec {
  pub name: String,
  pub description: String,
  pub data_type: DataType,
}

Description

A DuckDB custom setting the worker registers (surfaced in catalog_attach).

struct TimeTravelVersion

source

pub struct TimeTravelVersion {
  pub version: i64,
  pub columns: SchemaRef,
  pub scan_function: String,
  pub scan_arguments: Vec<u8>,
  pub timestamp_year: Option<i32>,
}

Description

One historical version of a time-travel table.

function aggregate_function_info

source

pub fn aggregate_function_info(
  f: &dyn crate::aggregate::AggregateFunction,
) -> Result<FunctionInfo>

Description

Build the FunctionInfo for an aggregate function. Aggregates must advertise a 1-field output schema at discovery time, so resolve it via on_bind with empty params (a fixed-return aggregate ignores them).

function arc

source

pub fn arc(schema: Schema) -> Arc<Schema>

Description

Build an Arc<Schema> from a Schema (convenience).

function arg_type_to_arrow_pub

source

pub fn arg_type_to_arrow_pub(t: &str) -> DataType

Description

Public wrapper for arg_type_to_arrow (used by overload scoring).

function buffering_function_info

source

pub fn buffering_function_info(
  f: &dyn crate::buffering::TableBufferingFunction,
) -> Result<FunctionInfo>

Description

Build the FunctionInfo for a table-buffering function.

function build_arg_schema

source

pub fn build_arg_schema(specs: &[ArgSpec]) -> Schema

Description

Build the wire arg schema (FunctionInfo.arguments) from arg specs, attaching vgi_* field-metadata markers.

function build_macro_arguments_schema

source

pub fn build_macro_arguments_schema(m: &CatMacro) -> Result<Vec<u8>>

Description

Build a macro arguments_schema: one nullable Arrow field per parameter, in parameters order. A parameter’s field type is the type of its default value when one is known (else Null). The per-parameter description rides as vgi_doc field metadata (UTF-8, presence-only — the key is omitted entirely when there is no doc), the exact same mechanism functions use for per-argument docs. Returns empty IPC bytes when the macro has no parameters and no docs, so older readers are unaffected.

function default_function_info

source

pub fn default_function_info(name: &str, function_type: &str) -> FunctionInfo

Description

A FunctionInfo with all the non-essential fields set to their canonical defaults; callers override name, function_type, arguments, output_schema, and the descriptive fields.

function dict

source

pub fn dict(s: &str) -> DictString

Description

Wrap a DictString enum value (re-export convenience).

function format_range

source

pub fn format_range(
  ge: Option<f64>,
  le: Option<f64>,
  gt: Option<f64>,
  lt: Option<f64>,
) -> Option<String>

Description

Build interval notation from an argument’s numeric bounds. Inclusive bounds (ge/le) render as square brackets, exclusive bounds (gt/lt) as parentheses, and an open side as -inf/+inf. Returns None when the argument has no numeric bound at all. Mirrors _format_range in the Python reference (vgi/argument_spec.py).

function macro_arguments_schema

source

pub fn macro_arguments_schema(
  parameters: &[String],
  defaults: &[(String, i64)],
  parameter_docs: &[(String, String)],
) -> Schema

Description

Construct the macro arguments_schema from the parameter names (order is load-bearing), the typed defaults ((param, int64) — present params get an Int64 field type, others Null), and per-parameter docs (vgi_doc field metadata, presence-only).

function macro_info

source

pub fn macro_info(schema: &str, m: &CatMacro) -> crate::protocol::dtos::MacroInfo

Description

Build a MacroInfo DTO.

function macro_parameter_docs_from_schema

source

pub fn macro_parameter_docs_from_schema(schema: &Schema) -> Vec<(String, String)>

Description

Extract per-parameter descriptions from a macro arguments_schema (inverse of [macro_arguments_schema]’s vgi_doc handling). Fields without the vgi_doc key (undocumented) are omitted.

function main_schema_info

source

pub fn main_schema_info(attach_opaque_data: &[u8]) -> SchemaInfo

Description

The default SchemaInfo for the main schema.

function resolve_version_npm

source

pub fn resolve_version_npm(
  spec: Option<&str>,
  supported: &[String],
  default: &str,
  label: &str,
) -> Result<String>

Description

Resolve an npm-style version spec to a concrete supported version (exact X.Y.Z, bare X / X.Y, caret ^X.Y.Z, tilde ~X.Y.Z). Returns default when spec is None. Err when nothing matches.

function scalar_function_info

source

pub fn scalar_function_info(f: &dyn ScalarFunction) -> Result<FunctionInfo>

Description

Build the FunctionInfo for a scalar function.

function scan_function_result

source

pub fn scan_function_result(t: &CatTable) -> Result<crate::protocol::dtos::ScanFunctionResult>

Description

Build a TableInfo DTO for a function-backed catalog table, inlining the scan function so DuckDB needn’t call catalog_table_scan_function_get. The flat ScanFunctionResult batch for a function-backed table (used both for the inlined TableInfo.scan_function and the lazy catalog_table_scan_function_get RPC response).

function schema_info

source

pub fn schema_info(name: &str, comment: Option<&str>, attach_opaque_data: &[u8]) -> SchemaInfo

Description

Build a SchemaInfo for an arbitrary schema.

function serialize_attach_catalog

source

pub fn serialize_attach_catalog(
  info: &crate::protocol::dtos::AttachCatalogInfo,
) -> Result<Vec<u8>>

Description

Serialize an AttachCatalogInfo to its IPC attach_catalogs entry (companion catalog for lakehouse federation).

function serialize_attach_option_spec

source

pub fn serialize_attach_option_spec(
  name: &str,
  description: &str,
  arrow_type: &DataType,
  default: Option<&arrow_array::ArrayRef>,
  required: bool,
) -> Result<Vec<u8>>

Description

Serialize one AttachOptionSpec (discovery record for an ATTACH option). Schema {name:str, description:str, type:binary (IPC schema of a single value field), default_value:binary? (IPC 1-row batch of the default), required:bool?}.

required marks an option the caller must supply at ATTACH time, so a client can report that before attempting the attach rather than surfacing a failure that reads like an empty catalog. It is nullable and appended LAST: a peer that predates the column reads the batch by name and simply doesn’t see it, and absent and explicit-null both mean “not required”.

Passing required = true together with a default is an error — an option that falls back to a value is by definition satisfiable without the caller.

function serialize_catalog_info

source

pub fn serialize_catalog_info(model: &CatalogModel) -> Result<Vec<u8>>

Description

Serialize a [SettingSpec] to its IPC settings entry. The batch schema is {name: string, description: string, type: binary, default_value: binary?} where type is the IPC schema of a single value field of the setting’s type. Serialize one CatalogInfo discovery record to IPC bytes. The schema (field order/types) must match generated.CatalogInfoSchema exactly; the releases element struct type is emitted even when the list is empty.

function serialize_foreign_key

source

pub fn serialize_foreign_key(schema: &str, fk: &ForeignKey) -> Result<Vec<u8>>

Description

Serialize a foreign key to its IPC foreign_key_constraints entry.

function serialize_items

source

pub fn serialize_items<T: vgi_rpc::VgiArrow>(items: Vec<T>) -> Result<Vec<Bytes>>

Description

Serialize a list of catalog item structs into ItemsResult.items.

function serialize_secret_type

source

pub fn serialize_secret_type(spec: &SecretTypeSpec) -> Result<Vec<u8>>

Description

Serialize a [SecretTypeSpec] to its IPC secret_types entry.

function table_function_info

source

pub fn table_function_info(f: &dyn crate::table_function::TableFunction) -> Result<FunctionInfo>

Description

Build the FunctionInfo for a table (producer) function.

function table_in_out_function_info

source

pub fn table_in_out_function_info(
  f: &dyn crate::table_in_out::TableInOutFunction,
) -> Result<FunctionInfo>

Description

Build the FunctionInfo for a table-in-out function (a DuckDB table fn).

function validate_required_attach_options

source

pub fn validate_required_attach_options(
  catalog_name: &str,
  required_names: &[&str],
  options_ipc: Option<&[u8]>,
) -> std::result::Result<(), MissingAttachOptions>

Description

Return an error when an option declared required has no corresponding entry in the supplied catalog_attach options.

options_ipc is the serialized options batch as received: each supplied option is a column of a single-row batch, so the column names are the keys. Names compare case-insensitively, mirroring DuckDB’s handling of ATTACH option keys.

function view_info

source

pub fn view_info(schema: &str, v: &CatView) -> crate::protocol::dtos::ViewInfo

Description

Build a ViewInfo DTO.