Apache Arrow R 教程为 Arrow R 包贡献一个 lubridate 函数绑定mday 实战【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow本文基于 Apache Arrow 官方开发者指南中的 R 教程r_tutorial.rst完整复现了一次真实贡献的全过程为 Arrow R 包添加lubridate::mday()到 Arrow Cday计算核的绑定。读完本文你将掌握如何调研 R 函数与 C compute 函数的对应关系、在哪里以及如何注册 dplyr/lubridate 绑定、如何用compare_dplyr_binding编写等价性测试以及从建分支、跑测试、查风格到提交 Pull Request 的完整工作流。一、教程背景这次要解决什么问题官方教程明确了自己的定位这是一篇针对具体案例的教程不是通用步骤指南通用流程见 step_by_step 指南。本教程要解决的具体 issue 是实现一个简单绑定让 R 生态中的lubridate::mday()函数从日期对象中提取“当月第几天”在 Arrow R 的 dplyr 查询路径上可用行为与 lubridate 原函数一致issue 编号 ARROW-14816。教程开篇给出了两条前置约定绑定代码位于 R 包的表达式相关文件教程写作时为expression.R从当前仓库源码结构看该职责后来迁移到了 dplyr-funcs-simple.R这一点在第五节会展开构建 R 包的具体步骤与操作系统强相关教程本身不重复展开而是指向 building 指南。二、环境准备Fork、克隆与配置 upstream教程假定 Git 已安装否则参见 set_up 指南。将 Apache Arrow 仓库 fork 到你的账号后克隆自己的 fork并把上游主仓库加为upstream$ git clone https://github.com/your username/arrow.git $ cd arrow $ git remote add upstream https://github.com/apache/arrow这样本地就同时拥有两个远端origin你的 fork用于推送与upstreamapache/arrow用于同步最新代码。后续所有分支同步与 PR 推送都依赖这一结构。三、选定 issuemday() 绑定教程指出如果没有可认领的 issue应参考指南中的 finding_issues 章节。本例选定 issue 后工作可以正式开始。四、在更新后的 main 上创建新分支开始动手前先从上游 main 同步出干净基线再按 issue 编号创建分支$ git checkout main $ git fetch upstream $ git pull --ff-only upstream main $ git checkout -b ARROW-14816注意--ff-only保证 main 只快进、不产生多余的 merge commit分支名直接使用 issue 编号方便追踪。五、调研两侧函数lubridate 的 mday() 与 Arrow C 的 day()这是本教程最有方法论价值的部分加绑定前必须分别弄清 R 侧函数与 C compute 函数的签名、输入/输出类型与可选参数确认二者语义等价后才动手。5.1 在 R 控制台考察 lubridate::mday()查阅 lubridate 文档可知mday()接受一个 date 对象返回“当月第几天”的数值。教程建议在 R 控制台实际运行确认行为 library(lubridate) mday(as.Date(2000-12-31)) [1] 31 mday(ymd(080306)) [1] 65.2 考察 Arrow C 的 day 计算函数从 Arrow C compute 文档可知day是一元函数只接受一个数据输入输入必须是 Temporal 类型——包括 Date 类型Date32/Date64、Time 类型Time32/Time64、Timestamp、Duration、Interval返回整数/数值类型。可以在 R 控制台用call_function直接调用 Arrow C 函数验证 call_function(day, Scalar$create(lubridate::ymd(2000-12-31))) Scalar 31对比结论两侧函数处理与返回的数据类型等价lubridate 的mday()没有额外参数Arrow C 的day()也没有对应的选项类。因此只需把mday()加入表达式映射表把它连到 C 的day函数即可无需自定义转换逻辑。5.3 绑定放在哪里从 expression.R 到 .unary_function_map教程写作时2022 年初映射位于 r/R/expression.R 中当时的修改方式是往映射列表里加一行教程原文给出的示例片段# second is defined in dplyr-functions.R # wday is defined in dplyr-functions.R mday day, yday day_of_year, year year,而在当前仓库源码中这类“单参数、直接映射、无需非默认选项”的一元函数映射已经被集中整理到 dplyr-funcs-simple.R 的.unary_function_map中且键名改为带命名空间限定的形式# r/R/dplyr-funcs-simple.R .unary_function_map - list( ... # date and time functions lubridate::day day, lubridate::hour hour, ... lubridate::mday day, lubridate::yday day_of_year, lubridate::year year, lubridate::leap_year is_leap_year )也就是说mday绑定已经作为正式代码合入。从源码结构看绑定的注册机制是dplyr-funcs.R 中的register_binding()负责把 R 函数名登记到 Arrow 求值环境dplyr-funcs-simple.R 中的register_bindings_array_function_map()会为.unary_function_map里的每个条目生成一个闭包function(...) Expression$create(operator, ...)即在mutate()/filter()中调用mday(x)时最终被翻译成一个Expression$create(day, x)的 compute 表达式交由 C compute 引擎Acero执行。这个“R 函数名 → compute kernel 名”的一行映射就是整个绑定的核心。若映射的 R 函数带有额外参数、需要选项对象或需要组合多个 kernel如trunc、second、wday则不能进入这个“simple”表需要定义在dplyr-funcs-*.R等更复杂的映射文件里——这是文件头部注释明确写下的规则。六、添加测试用 compare_dplyr_binding 验证与 lubridate 的行为等价教程建议在 test-dplyr-funcs-datetime.Ryday()/day()的同类测试所在地中添加两组测试分别覆盖 timestamp 与 date 两种输入test_that(extract mday from timestamp, { compare_dplyr_binding( .input %% mutate(x mday(datetime)) %% collect(), test_df ) }) test_that(extract mday from date, { compare_dplyr_binding( .input %% mutate(x mday(date)) %% collect(), test_df ) })如果函数带有额外选项或边界情况还需要补充更多用例。当前仓库中这两组测试确实存在于 test-dplyr-funcs-datetime.R 的 “extract mday from timestamp”约 L766与 “extract mday from date”约 L1002证明该 PR 已被合入。这个测试能成立的根基是测试辅助函数compare_dplyr_binding它定义在 helper-expectation.R其工作机制值得每个贡献者理解用rlang::enquo()把传入的管道表达式“引用”起来使同一表达式可以被求值两次第一次求值时把.input绑定为普通 tibble/data.frame走原生 dplyr 路径得到期望输出第二次求值时把.input绑定为arrow_table(tbl)Arrow Table走 Arrow compute 路径用expect_warning(..., warning)控制是否允许 Arrow 路径产生警告warning TRUE是特殊值专门匹配 “Pulling data into R” 这种回退警告默认NA表示不允许任何警告最后用expect_equal比较两条路径的结果。换言之这条测试断言的是“同一个 dplyr 管道跑在 data.frame 上和跑在 Arrow Table 上结果必须一致”——这正是绑定正确性的黄金标准。同文件里还有compare_dplyr_error()比较两侧报错信息是否一致与compare_expression()比较 R 向量与 Arrow Array/ChunkedArray 的输出复杂绑定可以按需选用。七、运行测试并解读输出在 R 包目录下按过滤器运行测试devtools::test(filterdatetime)教程给出了真实的运行输出示例节选ℹ Loading arrow See arrow_info() for available features ℹ Testing arrow See arrow_info() for available features ✔ | F W S OK | Context ✖ | 1 230 | dplyr-funcs-datetime [1.4s] ──────────────────────────────────────────────────── Failure (test-dplyr-funcs-datetime.R:187:3): strftime %%(...) did not throw the expected error. Backtrace: 1. testthat::expect_error(...) test-dplyr-funcs-datetime.R:187:2 2. testthat:::expect_condition_matching(...) ──────────────────────────────────────────────────── Duration: 1.4 s [ FAIL 1 | WARN 0 | SKIP 0 | PASS 230 ]这里的处理思路对贡献者很实用出现一个strftime的失败但它与本次改动无关新增的是 mday 测试且已通过。教程的建议是确认该失败与自己的改动无关后可以继续推进同时可以在社区渠道询问是否其他人也遇到同样失败——有可能是需要重新构建 C 库导致的。不要为了“凑绿”去改动与自己 PR 无关的测试。八、检查代码风格make styleR 侧代码遵循 tidyverse 风格。教程中使用的命令是$ make style教程写作时的输出使用 styler 对 git 变更的r/下.R文件逐个排版R -s -e setwd(..); if (requireNamespace(styler)) styler::style_file(...) Styling 2 files: r/R/expression.R ✔ r/tests/testthat/test-dplyr-funcs-datetime.R ℹ ──────────────────────────────────────────── Status Count Legend ✔ 1 File unchanged. ℹ 1 File changed. ✖ 0 Styling threw an error. Please review the changes carefully!其中ℹ表示文件被自动改过需要人工复核。从当前仓库源码看r/Makefile 中的style目标现在已改为基于 pre-commit 实现style: pre-commit run --show-diff-on-failure --coloralways r因此在新分支上贡献时应以仓库当前 pre-commit 配置为准执行make styleℹ File changed提示自动改动的文件仍需仔细检查后再提交。九、提交、推送与创建 Pull Request9.1 复核变更git status 与 git diff先确认只改动了目标文件$ git status On branch ARROW-14816 Changes not staged for commit: modified: R/expression.R modified: tests/testthat/test-dplyr-funcs-datetime.R教程中git diff的完整输出即本次贡献的全部内容——一行映射加两组测试共 19 行新增diff --git a/r/R/expression.R b/r/R/expression.R --- a/r/R/expression.R b/r/R/expression.R -70,6 70,7 quarter quarter, # second is defined in dplyr-functions.R # wday is defined in dplyr-functions.R mday day, yday day_of_year, year year, diff --git a/r/tests/testthat/test-dplyr-funcs-datetime.R b/r/tests/testthat/test-dplyr-funcs-datetime.R --- a/r/tests/testthat/test-dplyr-funcs-datetime.R b/r/tests/testthat/test-dplyr-funcs-datetime.R -444,6 444,15 test_that(extract wday from timestamp, { test_that(extract mday from timestamp, { compare_dplyr_binding( .input %% mutate(x mday(datetime)) %% collect(), test_df ) }) ... test_that(extract mday from date, { compare_dplyr_binding( .input %% mutate(x mday(date)) %% collect(), test_df ) })9.2 提交并查看历史$ git commit -am Adding a binding and a test for mday() lubridate [ARROW-14816 ed37d3a3b] Adding a binding and a test for mday() lubridate 2 files changed, 19 insertions() $ git log commit ed37d3a3b3eef76b696532f10562fea85f809fab (HEAD - ARROW-14816) Author: Alenka Frim frim.alenkagmail.com Date: Fri Jan 21 09:15:31 2022 0100 Adding a binding and a test for mday() lubridate9.3 视情况 rebase 后推送如果分支创建得较早推送前应先 rebase 到最新的 upstream main避免合并冲突$ git pull upstream main --rebase $ git push origin ARROW-14816推送后 GitHub 会提示创建 PR见文首的通知栏截图进入 Arrow 仓库页面主仓库或 fork 均可点击Compare pull request。9.4 PR 标题与描述规范教程强调标题必须与 issue 对齐格式为 issue 编号 方括号语言标签 描述ARROW-14816: [R] Implement bindings for lubridate::mday()并特意指出标题末尾补了标点。教程还附了一条时代注记写作时 Arrow 使用 Jira 跟踪 issue前缀为ARROW-14816目前项目已改用 GitHub issues相应地前缀会是GH-14816——这正是当前贡献者应采用的格式。提交前还应填写描述向审阅者说清 PR 的目标。点击Create pull request后PR 会关联到 issue 并触发 CI收到 review 后在本地修正、评论、解决对话流程详见 pr_lifecycle 指南。教程原文附带的这条 PR 就是本次绑定的真实记录。十、小结一次“一行代码”的贡献背后的完整工程链路环节关键点仓库依据需求确认issue 驱动分支名 issue 编号r_tutorial.rst函数调研R 侧mday()与 Cday语义/类型等价无额外选项r_tutorial.rst注册绑定一行映射lubridate::mday day进入一元函数表dplyr-funcs-simple.R、dplyr-funcs.R等价性测试compare_dplyr_binding双路径求值对比helper-expectation.R、test-dplyr-funcs-datetime.R风格检查make style当前为 pre-commit 实现r/MakefilePR 规范标题GH-编号: [R] ... 描述r_tutorial.rst这套流程的可复用模式是查文档 → 控制台双向验证 → 找到或新增映射/绑定 → 用 compare_辅助函数写等价性测试 → 风格检查 → 规范化 PR*。对于参数更复杂的 R 函数则需离开 simple 映射表在dplyr-funcs-*.R中编写带选项对象的自定义绑定并结合 dplyr-funcs-doc.R 中维护的 lubridate 支持清单同步更新文档。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考