Apache DataFusion 函数文档化机制解析：datafusion-doc 与 `[user_doc]` 宏实战指南

大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载Apache DataFusion 是一个用 Rust 编写的可扩展查询执行框架使用 Apache Arrow 作为内存数据格式。在 DataFusion 中内置的标量函数、聚合函数和窗口函数并非散落在文档里而是通过datafusion-doc子模块提供的结构化类型与过程宏在源码中就地声明、再由工具自动生成官方 SQL 函数文档。本文将以仓库中的 datafusion/doc/README.md 为核心骨架深入datafusion-doccrate 的Documentation/DocSection/DocumentationBuilder结构、#[user_doc]声明式宏以及整套文档生成管线读完你将掌握如何为自己的 UDF 编写能被官方文档机制识别、渲染的规范文档。一、datafusion-doc 是什么UDF 文档化子模块的定位按照 datafusion/doc/README.md 的说明DataFusion 是一个用 Rust 编写的可扩展查询执行框架extensible query execution framework并将 Apache Arrow 作为内存格式in-memory format。datafusion-doc这个 crate 是 DataFusion 的一个子模块它的职责非常聚焦This crate is a submodule of DataFusion that provides structures and macros for documenting user defined functions.即提供用于记录文档化用户自定义函数UDF的数据结构与宏。这里的 UDF 涵盖三类标量函数ScalarUDFImpl、聚合函数AggregateUDFImpl和窗口函数WindowUDFImpl。从 datafusion/doc/Cargo.toml 可以看到该模块的包名为datafusion-doc、库名为datafusion_doc描述为 Documentation module for DataFusion query engine。README 还给出了一个重要的使用建议Most projects should use thedatafusioncrate directly, which re-exports this module. If you are already using thedatafusioncrate, there is no reason to use this crate directly in your project as well.也就是说datafusion-doc是 DataFusion 内部模块化拆分的产物对外并不需要用户单独依赖。在仓库内部datafusion/core/src/bin/print_functions_docs.rs 直接以use datafusion_expr::{DocSection, Documentation, aggregate_doc_sections, scalar_doc_sections, window_doc_sections, ...}的方式引用这些符号说明它们经由datafusion_expr再导出、并最终随datafusion主 crate 一并暴露给使用者。因此应用开发者只要依赖datafusion主 crate就能拿到完整的 UDF 文档化能力。二、核心数据结构Documentation / DocSection / DocumentationBuilderdatafusion-doc的全部核心类型都定义在 datafusion/doc/src/lib.rs 中由三条主线组成最终产物Documentation、分区标记DocSection、以及构建器DocumentationBuilder。2.1 Documentation一份 UDF 文档的完整描述Documentation结构体lib.rs承载了单个 UDF 的全部文档信息字段含义如下字段类型含义doc_sectionDocSection该 UDF 在文档中归属的分区例如 Math FunctionsdescriptionString函数的功能描述syntax_exampleString语法示例如ascii(str)sql_exampleOptionString一段 SQL 示例通常以 SQL 提示符查询与输出形式给出除最简单的函数外强烈建议提供argumentsOptionVec(String, String)参数列表按添加顺序展示二元组左侧为参数名、右侧为参数描述alternative_syntaxOptionVecString该函数其它可用的语法写法related_udfsOptionVecString相关函数名列表值必须与相关 UDF 的 name 完全一致值得注意的是DataFusion 官方的 SQL 函数文档正是由这些结构体自动生成的The DataFusion SQL function documentation is automatically generated from these structsUDF 的名称取自ScalarUDFImpl::name、AggregateUDFImpl::name或WindowUDFImpl::name。2.2 DocSection把函数归入正确的文档分区DocSectionlib.rs用于指定文档中的展示分区包含三个字段include是否将该分区包含进公开文档true包含false不包含label展示标签例如Math Expressionsdescription可选的分区级描述。其Default实现lib.rs返回include: true、label: Default、description: None适合那些不出现在 DataFusion 官方文档中的自定义 UDF——即默认可见但没有专属分类。2.3 DocumentationBuilder链式构建文档DocumentationBuilder采用经典的 builder 模式lib.rs通过Documentation::builder(doc_section, description, syntax_example)创建随后以链式方法补齐可选信息方法作用with_doc_section覆盖文档分区with_description覆盖功能描述with_syntax_example覆盖语法示例with_sql_example添加 SQL 示例with_argument(name, description)追加一个参数说明按添加顺序展示with_standard_argument(name, expression_type)追加一个标准表达式参数说明自动拼接固定的模板文案with_alternative_syntax(syntax)追加一种替代语法with_related_udf(name)追加一个相关函数build()构建出最终的Documentationdoc_section、description、syntax_example未设置时会 panicwith_standard_argument会生成统一风格的参数描述传入Some(String)时渲染为 String expression to operate on. Can be a constant, column, or function, and any combination of operators.传入None时则以 The 开头渲染同样的模板保证文档中大量通用参数表述一致。lib.rs自带的 doctest 展示了最小可用写法use datafusion_doc::{DocSection, Documentation}; let doc_section DocSection { include: true, label: Display Label, description: None, }; let documentation Documentation::builder(doc_section, Add one to an int32.to_owned(), add_one(2).to_owned()) .with_argument(arg_1, The int32 number to add one to) .build();三、预定义文档分区三种 UDF 各自可用的 DocSection为了让内置函数在官方文档中归类统一datafusion-doc在三个子模块中预定义了各类型 UDF 的标准分区。#[user_doc]宏见下文会按label查找并匹配这些预定义分区。3.1 标量函数分区scalar_doc_sections定义于 datafusion/doc/src/udf.rs共 12 个分区Math FunctionsConditional FunctionsString FunctionsBinary String FunctionsRegular Expression Functions自带分区描述说明 DataFusion 使用 PCRE-like 正则语法支持i、m、s、R、U等可选标志Time and Date FunctionsArray FunctionsStruct FunctionsMap FunctionsHashing FunctionsUnion Functions自带描述强调 union 数据类型即 tagged unions / variant types / enums / sum types且与 SQL 的 UNION 运算符无关Other Functions3.2 聚合函数分区aggregate_doc_sections定义于 datafusion/doc/src/udaf.rs共 3 个分区General Functions、Statistical Functions、Approximate Functions。3.3 窗口函数分区window_doc_sections定义于 datafusion/doc/src/udwf.rs共 3 个分区Aggregate Functions自带描述 All aggregate functions can be used as window functions.Ranking FunctionsAnalytical Functions四、声明式文档#[user_doc]过程宏手写DocumentationBuilder链式代码仍然繁琐因此 DataFusion 在datafusion-macros中提供了#[user_doc(...)]过程宏datafusion/macros/src/user_doc.rs把文档写成紧邻函数结构的声明式属性再由宏在编译期自动生成DocumentationBuilder调用代码。宏支持的属性项包括doc_section(label ...)、description ...、syntax_example ...、sql_example r#... #、standard_argument(name ..., prefix ...)、argument(name ..., description ...)、alternative_syntax ...、related_udf(name ...)。其中doc_section会尝试按 label 查找预定义的DocSection。以真实的内置函数coalesce为例datafusion/functions/src/core/coalesce.rs#[user_doc( doc_section(label Conditional Functions), description Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. This function is often used to substitute a default value for _null_ values., syntax_example coalesce(expression1[, ..., expression_n]), sql_example r#sql select coalesce(null, null, datafusion); ---------------------------------------- | coalesce(NULL,NULL,Utf8(datafusion)) | ---------------------------------------- | datafusion | ---------------------------------------- #, argument( name expression1, expression_n, description Expression to use if previous expressions are _null_. Can be a constant, column, or function, and any combination of arithmetic operators. Pass as many expression arguments as necessary. ) )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct CoalesceFunc { pub(super) signature: Signature, }宏的文档注释user_doc.rs说明了它展开后生成的代码形态为结构体生成fn doc(self) - Optiondatafusion_doc::Documentation方法内部用std::sync::LazyLock缓存一个Documentation::builder(...)链式调用的结果例如fn doc(self) - Optiondatafusion_doc::Documentation { static DOCUMENTATION: std::sync::LazyLockdatafusion_doc::Documentation std::sync::LazyLock::new(|| { datafusion_doc::Documentation::builder( datafusion_doc::DocSection { include: true, label: Time and Date Functions, description: None, }, Converts a value to a date (YYYY-MM-DD)..to_string(), to_date(expression[, ..., format_n]).to_string(), ) .with_sql_example(...) .with_standard_argument(expression, String.into()) .with_argument(format_n, ...) .build() }); Some(DOCUMENTATION) }也就是说#[user_doc]只是声明式语法糖最终仍落到第二节中的Documentation/DocumentationBuilder之上。生成的文档可通过ScalarUDFImpl、AggregateUDFImpl、WindowUDFImpl的documentation()方法取出见 datafusion/expr/src/udf.rs 及 datafusion/expr/src/udaf.rs、datafusion/expr/src/udwf.rs 中对应的documentation方法。五、从结构体到官方 SQL 文档完整的生成管线数据最终落地的环节是文档生成器。datafusion/core下提供了print_functions_docs二进制datafusion/core/src/bin/print_functions_docs.rs它遍历当前会话注册的全部函数按aggregate/scalar/window三种类型把每个 UDF 的Documentation渲染成 Markdown 输出到 stdout。围绕它的自动化脚本是 dev/update_function_docs.sh执行流程大致为以仓库根目录为基准默认输出目录为docs/source/user-guide/sql可通过--output-dir DIR覆盖依次生成三个页面例如聚合函数页使用命令cargo run --manifest-path datafusion/core/Cargo.toml --features docs_generation --bin print_functions_docs -- aggregate将渲染结果连同固定的文件头写入docs/source/user-guide/sql/aggregate_functions.md、scalar_functions.md、window_functions.md。生成的 Markdown 文件头部会明确标注This file was generated by the dev/update_function_docs.sh script. Do not edit it manually as changes will be overwritten.并提示应修改 UDF 的documentation()函数或脚本本身来更新文档。这些页面最终通过 docs/source/user-guide/sql/index.rst 挂入用户指南。以coalesce为例docs/source/user-guide/sql/scalar_functions.md 中对应的章节正是由#[user_doc]属性中的描述、语法示例、SQL 示例渲染而来 select coalesce(null, null, datafusion); ---------------------------------------- | coalesce(NULL,NULL,Utf8(datafusion)) | ---------------------------------------- | datafusion | ----------------------------------------由此可见源码中的#[user_doc]是唯一事实来源print_functions_docs是渲染器update_function_docs.sh负责把渲染结果落盘为官方文档。六、编写 UDF 文档的规范与约束结合lib.rs的文档注释与宏实现为 UDF 编写文档时有几条明确的规范需要遵守Markdown 格式Documentation中所有字符串都必须使用 Markdown 格式书写lib.rs明确要求包括描述中的强调、代码与链接。当前仅支持单语言文档目前只支持一种语言所有文本应使用英文。related_udfs必须同类型且名字精确相关函数的值应与对应 UDF 的name()完全一致并且必须是同一种 UDF 类型标量、聚合或窗口否则无法正确生成互链。doc_section标签需匹配预定义分区#[user_doc]宏会按label查找预定义的DocSection因此自定义分区标签时应参考第三节中列出的标准分区集合对不出现在官方文档中的自定义 UDF可使用DocSection::default()include: true、label 为Default。尽量提供sql_example除最简单的函数外官方强烈建议提供带实际输出结果的 SQL 示例这能显著提升文档的可读性与可验证性。不要手工编辑生成文件docs/source/user-guide/sql下的函数文档由脚本生成应通过修改 UDF 实现中的文档声明后重新运行 dev/update_function_docs.sh 来更新。此外Documentation还提供了一个to_doc_attribute()方法lib.rs能把已有的代码式文档结构输出为等价的#[user_doc(...)]属性文本——这是从代码构建文档迁移到属性声明文档的半自动化辅助工具文档注释中说明它可用于 UDF 文档生成方式的迁移过渡迁移完成后即可安全移除。结语datafusion-doc虽然只是 DataFusion 仓库中的一个文档子模块却完整承载了UDF 文档从声明到发布的整条链路Documentation/DocSection/DocumentationBuilder提供结构化数据模型#[user_doc]宏让文档可以伴随函数实现就地书写print_functions_docs与update_function_docs.sh则把源码中的声明自动渲染为官方 SQL 函数页面。理解了这套机制无论是为 DataFusion 贡献内置函数还是在自己的扩展中维护 UDF 文档都能做到一处声明、处处生效并保证文档与实现永远同源。赞分享大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载相关推荐Apache DataFusion 的 user_doc 过程宏为 UDF 编写结构化用户文档的完整指南Apache DataFusion 的 user_doc 过程宏为 UDF 编写结构化用户文档的完整指南 Apache DataFusion 是一个用 Rus大数据数据分析后端Apache DataFusion 表函数库解析generate_series 与 range 的源码实现与实战指南Apache DataFusion 表函数库解析generate_series 与 range 的源码实现与实战指南 Apache DataFusion 是一大数据数据分析后端Apache DataFusion窗口函数错误处理文档最佳实践Apache DataFusion窗口函数错误处理文档最佳实践 窗口函数Window Function是Apache DataFusion中处理复杂分析场大数据数据分析后端上一篇抖音批量下载完全指南单条视频到整页作品一键搞定下一篇10分钟搭建MediaMTX自动化部署流水线GitLab CI/CD与Jenkins实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考