常见操作指南

如何更新 CI 测试中使用的 Rust 版本

提交一个 PR，更新仓库根目录下的 rust-toolchain 文件。

添加新函数

实现

函数类型	实现位置	需要实现的 Trait	使用的宏	示例
标量函数（Scalar）	functions	`ScalarUDFImpl`	`make_udf_function!()` 和 `export_functions!()`	`advanced_udf.rs`
嵌套函数（Nested）	functions-nested	`ScalarUDFImpl`	`make_udf_expr_and_func!()`
聚合函数（Aggregate）	functions-aggregate	`AggregateUDFImpl` 和 `Accumulator`	`make_udaf_expr_and_func!()`	`advanced_udaf.rs`
窗口函数（Window）	functions-window	`WindowUDFImpl` 和 `PartitionEvaluator`	`define_udwf_and_expr!()`	`advanced_udwf.rs`
表函数（Table）	functions-table	`TableFunctionImpl` 和 `TableProvider`	`create_udtf_function!()`	`simple_udtf.rs`

这些宏用于简化一些样板代码，例如确保同时创建一个 DataFrame API 兼容的函数
确保新函数通过子项目的 mod.rs 或 lib.rs 正确导出
函数最好通过 #[user_doc(...)] 属性提供文档，这样其文档就能被纳入 SQL 参考文档中（见下文小节）
标量函数会按功能族进一步划分为不同的模块（如字符串、数学、日期时间）。函数应添加到相应的模块中；如果需要创建新模块，还应添加一个新的 Rust feature，以便 DataFusion 用户按需有条件地编译这些模块
聚合函数可以选择实现 GroupsAccumulator 以获得更好的性能

Spark 兼容函数位于独立的 crate 中，但除此之外遵循相同的步骤，不过所有函数类型（如标量、嵌套、聚合）都集中放在同一位置。

测试

优先添加 sqllogictest 集成测试，即通过 SQL 对已知数据调用该函数并返回预期结果。参见现有的测试文件，看是否有合适的文件可以添加测试用例，如果没有则新建一个文件。有关如何编写这些测试的详细信息，请参阅 sqllogictest 文档。确保在这些测试中考虑边界情况和 null 输入的情况。

如果某种行为无法通过 sqllogictest 测试（例如测试 simplify()、需要与优化器隔离进行测试、难以通过 sqllogictest 构造精确的输入），则可以将测试作为 Rust 单元测试添加到实现模块中，但应尽可能保持测试精简。

文档

运行文档更新脚本 ./dev/update_function_docs.sh，它会更新此处相关的 markdown 文档（参见标量、聚合和窗口函数的文档）

运行脚本后你不应手动修改 markdown 文档，因为这些手动更改会在下次执行时被覆盖
参见引入该行为的 GitHub issue

如何以图形方式显示计划

LogicalPlan 节点表示的查询计划可以通过 Graphviz 进行图形化渲染。

为此，只需将 display_graphviz 函数的输出保存到文件中即可：

// Create plan somehow...
let mut output = File::create("/tmp/plan.dot")?;
write!(output, "{}", plan.display_graphviz());

然后，使用 dot 命令行工具将其渲染为可显示的文件。例如，以下命令会创建 /tmp/plan.pdf 文件：

dot -Tpdf < /tmp/plan.dot > /tmp/plan.pdf

如何格式化 `.md` 文档

我们使用 prettier 来格式化 .md 文件。

你可以通过 npm i -g prettier 将其全局安装，也可以使用 npx 将其作为独立二进制文件运行。使用 npx 需要一个可用的 node 环境。建议升级到最新版本的 prettier（在 npm 命令中添加 --upgrade）。

$ prettier --version
2.3.0

确认 prettier 版本后，即可格式化所有 .md 文件：

prettier -w {datafusion,datafusion-cli,datafusion-examples,dev,docs}/**/*.md

如何格式化 `.toml` 文件

我们使用 taplo 来格式化 .toml 文件。

通过 cargo 安装：

cargo install taplo-cli --locked

其他安装方式请参阅 taplo 安装文档。

$ taplo --version
taplo 0.9.0

在确认了 taplo 的版本之后，你就可以格式化所有的 .toml 文件了：

taplo fmt

如何更新 protobuf/gen 依赖

对于 proto 和 proto-common 这两个 crate，prost/tonic 代码是通过运行各自对应的 ./regen.sh 脚本生成的，这些脚本进而调用位于 ./gen 目录下的 Rust 可执行文件。

在修改了 protobuf 定义或更改了 ./gen 的依赖之后，就需要执行此操作，并且需要已正确安装 protoc（详见安装说明）。

# From repository root
# proto-common
./datafusion/proto-common/regen.sh
# proto
./datafusion/proto/regen.sh

操作指南