Crate duckfn 

duckfn：用普通 Rust 编写 DuckDB 扩展。

本 crate 提供一组过程宏（#[duck_scalar_function]、#[duck_aggregate_function]、 #[duck_table_function]、#[duck_copy_function]、#[duck_copy_from_function]、 #[duck_cast_function]、#[duck_sql_macro]、#[duck_replacement_scan]、 #[duck_custom_register]、#[derive(DuckStruct)]、#[derive(DuckEnum)]、duckfn_entrypoint!、 duck_sql_macro_files!）以及配套的适配层和值类型工具，把普通的 Rust 函数/结构体/枚举直接变成 可注册到 DuckDB 的标量函数、聚合函数、表函数、COPY TO / COPY FROM 格式、cast 函数、SQL 宏， 以及可映射到 LIST / MAP / ARRAY / STRUCT / ENUM 的值类型。

duckfn: write DuckDB extensions in plain Rust.

This crate ships a set of procedural macros (#[duck_scalar_function], #[duck_aggregate_function], #[duck_table_function], #[duck_copy_function], #[duck_copy_from_function], #[duck_cast_function], #[duck_sql_macro], #[duck_replacement_scan], #[duck_custom_register], #[derive(DuckStruct)], #[derive(DuckEnum)], duckfn_entrypoint!, duck_sql_macro_files!) together with the runtime adapter layer and value-type helpers that turn ordinary Rust functions, structs and enums into DuckDB scalar/aggregate/table/copy formats, casts, SQL macros and LIST / MAP / ARRAY / STRUCT / ENUM value types.

Macros

duck_sql_macro_files

一次注册多个 SQL 脚本文件（快捷方式）。

duckfn_entrypoint

Generate DuckDB extension entry point.

inventory_submit

Enter an element into the plugin registry corresponding to its type.

Structs

AggregateFunctionGuard

聚合函数句柄的 RAII 包装：持有 duckdb_aggregate_function，drop 时自动销毁。

AggregateFunctionSetGuard

聚合函数集句柄的 RAII 包装：drop 时自动销毁函数集。

BindInfo

Helper wrapper around duckdb_bind_info for use inside bind callbacks.

Connection

Wraps the duckdb_connection and duckdb_database provided to your extension at load time.

DataChunk

A non-owning wrapper around a duckdb_data_chunk.

DuckAggregateOverloadItem

聚合函数集重载项：#[duck_aggregate_function(overloads_name = "xxx")] 时由宏提交。

DuckBlob

DuckDB BLOB（任意字节串）。

DuckDate

DuckDB DATE（自纪元起的天数）。

DuckDecimal

定点小数 DECIMAL(WIDTH, SCALE)：用 i128 存未缩放整数。

DuckDynamicRow

动态行：一行的各列值，顺序与 DuckResultSchema 一致。

DuckDynamicState

动态表函数的 scan 状态：bind 阶段算出的 schema + 行迭代器。

DuckDynamicTable

动态结果集：bind 阶段算出的 schema + 行迭代器。

DuckExtraInfo

函数级附加数据：一个擦除指针的安全外壳。

DuckFunctionDocItem

一条函数的文档元数据，由 #[duck_*] 宏通过 inventory::submit! 提交。

DuckFunctionItem

一条待注册项，由 #[duck_*] 宏（以及 duck_sql_macro_files!）通过 inventory::submit! 在编译期提交。

DuckLazy

本行内的延迟读取凭证：逻辑类型与 T 完全相同，读取只记录位置，取值时才解析。

DuckLazySlot

聚合状态里的「DuckLazy<T> 槽」：只解析一次，之后所有行、所有合并都复用它。

DuckResultSchema

动态结果集 schema：有序的 (列名, 列类型) 列表。

DuckScalarOverloadItem

标量函数集重载项：#[duck_scalar_function(overloads_name = "xxx")] 时由宏提交。

DuckTime

DuckDB TIME（自午夜起的微秒数）。

DuckTimeTz

DuckDB TIME WITH TIME ZONE。

DuckTimestamp

DuckDB TIMESTAMP（微秒精度，无时区）。

DuckTimestampMs

DuckDB TIMESTAMP_MS（毫秒精度）。

DuckTimestampNs

DuckDB TIMESTAMP_NS（纳秒精度）。

DuckTimestampS

DuckDB TIMESTAMP_S（秒精度）。

DuckTimestampTz

DuckDB TIMESTAMP WITH TIME ZONE（微秒精度，UTC）。

DuckUuid

DuckDB UUID（128 位）。

DuckValueReader

一行值的读取器：同时持有 quack-rs 的高层 VectorReader 与 DuckDB 的裸向量。

DuckValueWriter

一批值的写入器：同时持有 quack-rs 的高层 VectorWriter 与 DuckDB 的裸向量。

DuckfnAggregateFunctionSetBuilder

聚合函数集 builder：把若干签名（重载）合并成一个同名函数集再注册。

FunctionDescription

合并后的函数文档：同一个函数名的多条提交（重载或函数集的各个签名）在这里合成一条。

LogicalType

An RAII wrapper around a duckdb_logical_type handle.

Value

An owned, RAII-managed DuckDB value.

Enums

DuckDynamicValue

运行时动态值：携带数据、不携带类型；类型由 DuckTypeDesc 给出。

DuckTypeDesc

运行时列类型描述：Send 友好的递归逻辑类型。

TypeConflict

CREATE TYPE 遇到同名类型时的处理方式。

TypeId

Identifies a DuckDB column type.

Traits

AggregateFunctionAdapter

把「参数结构体 -> 聚合状态」的有状态 Rust 类型注册成 DuckDB 聚合函数。

BuilderWithParams

为各类函数 builder 提供统一的「追加一个参数」与「批量设置参数」能力。

CastFunctionAdapter

把「源类型 -> 目标类型」的逐值转换注册成 DuckDB 的 cast 函数。

DuckAggregateState

聚合状态的简化接口：用「自合并 + 自身求值」描述一个聚合函数。

DuckBindArgs

表函数参数抽象：描述 bind 参数表，并从 BindInfo 里解析出参数值。

DuckColumns

「一行数据」的列集合抽象：描述若干列的名字、逻辑类型，以及按行读取/批量写入的方式。

DuckExtraInfoSource

能取回函数级附加数据的回调信息（duckdb_*_get_extra_info 的薄封装）。

DuckStructTrait

「具名结构体 ↔ STRUCT」的底层接口：由 #[derive(DuckStruct)] 生成实现。

DuckValueType

Rust 类型与 DuckDB 逻辑类型之间的映射：既负责声明 DuckDB 类型，也负责从向量读、往向量写。

DynamicTableFunctionAdapter

把「参数结构体 -> 动态结果集」的 Rust 函数注册成输出 schema 在 bind 阶段才确定的表函数。

ReplacementScanAdapter

把「DuckDB 不认识的表名（通常是文件路径）」重定向到某个表函数。

ScalarFunctionAdapter

把「参数结构体 -> 输出值」的纯 Rust 函数注册成 DuckDB 标量函数。

TableFunctionAdapter

把「参数结构体 -> 行迭代器」的纯 Rust 函数注册成 DuckDB 表函数。

Functions

assert_impl_duck_value_type

用来给宏校验 DuckValueType 是否被类型实现。

config_bind_params

把一组 DuckBindArgs 的参数表（位置参数 / 命名参数）登记到 builder 上。

declared_function_descriptions

收集源码里声明的全部函数文档，按函数名排序并合并。

duck_aggregate_unwind

处理aggregate函数的panic：执行 f，panic 时转成查询错误写回 info。

duck_error

由任意字符串构造一个 quack-rs 错误。

duck_scalar_unwind

处理scalar函数的panic：执行 f，panic 时转成查询错误写回 info。

duck_value_is_null

判断一个 Value 是否为 SQL NULL —— 只调 Value::is_null() 是不够的。

enum_internal_type_for

ENUM 下标在向量里的物理宽度：DuckDB 按成员个数挑 UTINYINT / USMALLINT / UINTEGER。

erased_extra_info^⚠

读取附加数据外壳；没挂（指针为 null）时返回 None。

extra_info_ref^⚠

读取附加数据并直接转成 T；没挂或类型不符时返回 None。

flush_queued_type_ddl

把 queue_named_type_ddl / queue_enum_type_ddl 收集到的 DDL 一次性打印出来（队列为空则什么都不做）。

logical_type_sql

把一个 LogicalType 渲染成可用于 DDL 的 SQL 类型文本。

named_type_ddl

named_type_ddl_with 的默认形式：CREATE TYPE IF NOT EXISTS ...（幂等，不覆盖同名类型）。

named_type_ddl_with

生成「创建命名类型」的 SQL 语句。

panic_to_duck_error

把 catch_unwind 捕获到的 panic payload 转成 ExtensionError。

panic_to_string

将panic转换成字符串

print_sql_preview

把一段不会执行的 SQL 连同前后提示一起打印到 stderr（单个语句的即时版本）。

queue_enum_type_ddl

queue_enum_type_ddl_with 的默认形式：排队一条 CREATE TYPE IF NOT EXISTS ...。

queue_enum_type_ddl_with

按给定冲突策略渲染 ENUM 的 CREATE TYPE DDL 并收进队列：queue_named_type_ddl_with 的 ENUM 便捷版本。

queue_named_type_ddl

queue_named_type_ddl_with 的默认形式：排队一条 CREATE TYPE IF NOT EXISTS ...。

queue_named_type_ddl_with

按给定冲突策略渲染 CREATE TYPE 的 DDL 并收进队列（不执行、也不立刻打印）。

read_enum_index

从向量的下标数组里读一个 ENUM 下标。

register_all_aggregate_overload

按 name 分组注册所有聚合函数集重载。

register_all_duckfn

注册本扩展收集到的全部 DuckDB 函数（扩展初始化入口）。

register_all_scalar_overload

按 name 分组注册所有标量函数集重载。

register_enum_type

register_enum_type_with 的默认形式：CREATE TYPE IF NOT EXISTS ...（幂等）。

register_enum_type_with

在 catalog 里按给定冲突策略创建一个 ENUM 类型。

register_named_type

register_named_type_with 的默认形式：CREATE TYPE IF NOT EXISTS ...（幂等）。

register_named_type_with

在 catalog 里按给定冲突策略创建一个命名类型。

register_sql_macro_str

在连接 c 上执行一段 SQL（通常是一条或多条 CREATE OR REPLACE MACRO）。

vec_option_to_ref

把 Vec<Option<T>> 转成 Vec<Option<&T>>，用于按引用批量写入向量。

write_enum_index

往向量的下标数组里写一个 ENUM 下标。

Type Aliases

DuckArray

[T; N] 的别名，与 DuckList / DuckMap 命名一致。

DuckDynamicIterator

动态行迭代器：与静态表函数的 DuckFullIterator 同形（可发送、逐行可错可为空）。

DuckFirst

DuckFirst<T>：#[duck_aggregate_function(auto_collect = true)] 里「每查询一个常量」参数的 书写标记 —— 它在类型位置上就是一个恒等别名（值类型就是 T），只用来让宏认出「这一列不是要 收集的整列，而是逐行不变、只需解析一次的标量配置」。

DuckFullIterator

表函数的数据源：一个可发送的迭代器，逐行产出「可能失败、可能为空」的结果。

DuckFullIteratorResult

DuckFullIterator 的构造结果：构建迭代器本身也可能失败（例如参数非法）。

DuckList

Vec<T> 的别名，与 DuckArray / DuckMap 命名一致。

DuckMap

IndexMap<K, V> 的别名，与 DuckList / DuckArray 命名一致。

DuckNamedColumnType

(列名, 逻辑类型构造函数)

DuckOptionResult

「可能为空的结果」类型别名，Ok(None) 表示 SQL NULL。

DuckRegisterFn

注册回调的函数指针类型：接收一个 DuckDB 连接，返回可能失败的结果。

DuckResult

本 crate 的结果类型别名：错误统一为 quack-rs 的 ExtensionError。

Attribute Macros

duck_aggregate_function

把普通 Rust 函数注册成 DuckDB 聚合函数。

duck_cast_function

把 fn(源值) -> 目标值 注册成 DuckDB 的 cast 函数，覆盖 CAST(源 AS 目标)。

duck_copy_from_function

把「按批取行」的 Rust 函数注册成 DuckDB 的 COPY 读取格式，为 COPY ... FROM 提供自定义文件格式。

duck_copy_function

把「按批写行」的 Rust 函数注册成 DuckDB 的 COPY 函数，为 COPY ... TO 提供自定义文件格式。

duck_custom_register

手动注册入口：把 fn(&Connection) -> DuckResult<()> 交给扩展初始化时调用。

duck_replacement_scan

把 SELECT * FROM 'data.myformat' 这类「未知表名/文件路径」重定向到某个表函数。

duck_scalar_function

把普通 Rust 函数注册成 DuckDB 标量函数。

duck_sql_macro

注册一个 SQL 宏：函数返回 SQL 文本（或 builder），扩展初始化时执行/注册。

duck_table_function

把返回迭代器的 Rust 函数注册成 DuckDB 表函数。

Derive Macros

DuckEnum

把「只有单元变体的 Rust enum」映射成 DuckDB ENUM。

DuckStruct

把一个具名结构体映射成 DuckDB STRUCT（嵌套 LIST / MAP / ARRAY / STRUCT 均支持）。