DuckDB扩展开发实战指南：从标量函数到并行表函数
原文地址：https://query-farm.github.io/duckdb-developer-day-1-extension-workshop/
本文基于DuckDB扩展开发工作坊内容整理，系统介绍如何为DuckDB数据库引擎开发自定义扩展，涵盖标量函数、表函数的实现以及性能优化技巧。
SQL查询生命周期与扩展切入点
在DuckDB中，SQL查询的执行分为多个阶段，扩展可以在每个阶段介入：
- 解析（Parse）：SQL语句转换为抽象语法树（AST）
- 绑定（Bind）：解析名称和类型，处理ANY类型和参数折叠
- 优化（Optimize）：重写执行计划，可插入自定义优化器
- 全局初始化（Init Global）：一次性设置，共享状态
- 本地初始化（Init Local）：每个线程的本地状态初始化
- 执行（Execute）：运行操作符并产生结果
开发环境搭建
首先克隆工作坊仓库开始实践：
gitclone --recursive https://github.com/Query-farm/workshop-1.git扩展项目的基本结构包括：
- 源代码（
src/目录） - 测试用例（
test/目录） - 构建配置（CMakeLists.txt等）
- 文档（
docs/目录）
标量函数开发实战
标量函数接受输入并产生单个输出值。以计算复活节日期的easter()函数为例：
函数实现原理
DuckDB采用向量化执行模型，不是逐行处理数据，而是批量处理：
voidEasterScalarFunc(DataChunk&args,ExpressionState&state,Vector&result){auto&year_vector=args.data[0];UnaryExecutor::Execute<int64_t,date_t>(year_vector,result,args.size(),[&](int64_tyear){// 计算复活节日期的算法（省略）returnduckdb::Date::FromDate(year,month,day);});}向量执行器简化开发
DuckDB提供了多种执行器简化向量化处理：
- UnaryExecutor：单输入→单输出（f(x)→y）
- BinaryExecutor：双输入→单输出（f(x,y)→z）
- GenericExecutor：多输入→单输出（f(a,b,c,…)→r）
这些执行器自动处理选择向量过滤、常量向量优化和NULL值传播，开发者只需编写处理基本类型的简单lambda函数。
函数注册与文档
为函数添加详细文档至关重要：
staticvoidLoadInternal(ExtensionLoader&loader){ScalarFunctioneaster_func("easter",{LogicalType::BIGINT},LogicalType::DATE,EasterScalarFunc);CreateScalarFunctionInfoeaster_info(easter_func);FunctionDescription easter_desc;easter_desc.description="使用匿名公历算法计算给定年份复活节星期日的日期。""适用于1583年至4098年（公历时代）之间的年份。";easter_desc.examples={"easter(2025)"};easter_desc.categories={"date"};easter_desc.parameter_names={"year"};easter_info.descriptions.push_back(easter_desc);loader.RegisterFunction(easter_info);}添加文档后，可通过系统表查询函数信息：
SELECT*FROMduckdb_functions()WHEREfunction_name='easter';测试验证
通过测试文件确保扩展功能正确：
# 测试示例requireworkshop query ISELECTeaster(2026);----2026-04-05表函数开发进阶
表函数与标量函数类似，但能产生多行数据。我们以实现并行化的incremental_sequence()函数为例：
基本表函数实现
表函数通过返回空数据块（cardinality为0）表示执行完成：
voidIncrementalSequenceFunc(ClientContext&context,TableFunctionInput&data,DataChunk&output){auto&bind_data=data.bind_data->Cast<IncrementalSequenceBindData>();auto&global_state=data.global_state->Cast<IncrementalSequenceGlobalState>();if(global_state.current_value>bind_data.end_value){output.SetCardinality(0);// 执行完成return;}int64_tremaining=bind_data.end_value-global_state.current_value;idx_trow_count=MinValue<idx_t>(remaining,STANDARD_VECTOR_SIZE);output.SetCardinality(row_count);output.data[0].Sequence(global_state.current_value,1,row_count);global_state.current_value+=row_count;}并行化优化
通过任务队列实现多线程并行处理：
structIncrementalSequenceGlobalState:public GlobalTableFunctionState{std::queue<WorkItem>work_queue;// 任务队列std::mutex queue_mutex;// 队列锁std::atomic<idx_t>total_rows_returned{0};// 原子计数器constint64_ttotal_rows;// 总行数idx_tMaxThreads()constoverride{returnGlobalTableFunctionState::MAX_THREADS;// 最大线程数}boolGetWorkItem(WorkItem&item){std::lock_guard<std::mutex>lock(queue_mutex);if(work_queue.empty())returnfalse;item=work_queue.front();work_queue.pop();returntrue;}};性能提升效果
并行化带来显著的性能提升：
- 1线程：8.72秒
- 2线程：4.58秒（1.9倍加速）
- 4线程：2.42秒（3.6倍加速）
- 8线程：1.75秒（4.9倍加速）
统计信息优化查询
为结果列提供统计信息帮助优化器跳过不必要的工作：
unique_ptr<BaseStatistics>IncrementalSequenceStatistics(ClientContext&context,constFunctionData*bind_data_ptr,column_tcolumn_index){auto&bind_data=bind_data_ptr->Cast<IncrementalSequenceBindData>();if(column_index==0){// value列autor=NumericStats::CreateEmpty(LogicalType::BIGINT);NumericStats::SetMin(r,bind_data.start_value);// 最小值NumericStats::SetMax(r,bind_data.end_value);// 最大值r.SetHasNoNull();// 无NULL值returnr.ToUnique();}// ... 其他列统计}统计信息使得以下查询能够快速返回空结果：
EXPLAINSELECT*FROMincremental_sequence(100,200)WHEREvalue=50;-- 输出：EMPTY_RESULT（基于统计信息直接跳过）扩展发布流程
将扩展提交到DuckDB社区扩展仓库非常简单，只需提交Pull Request并包含必要的元数据：
extension:name:workshopversion:'2026012501'description:计算复活节日期和多线程增量序列language:C++license:Apache-2.0maintainers:-rustyconover总结与最佳实践
- 向量化优先：始终使用向量化执行器，避免逐行处理
- 充分文档：为每个函数提供详细描述、示例和分类
- 并行化设计：对计算密集型表函数实现多线程支持
- 统计信息：提供准确的列统计信息以优化查询性能
- 健壮测试：编写全面的测试用例确保扩展可靠性
- 调试友好：使用调试构建并配合lldb进行问题排查
DuckDB扩展开发虽然需要深入理解系统内部机制，但通过合理的架构设计和API利用，可以创建出高性能、功能丰富的数据库扩展，为整个社区贡献力量。
本文基于Query.Farm工作坊内容整理，更多资源请访问：query.farm
)
