尧图网页设计 
Apache Arrow 格式规范变更流程指南跨语言兼容、讨论投票与参考实现要求【免费下载链接】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 的核心价值在于通用列式格式 多语言工具箱同一份数据可以零拷贝地在 C、Java、Rust、Go 等语言之间自由交换。要让这种跨语言互操作长期成立格式规范位于仓库 format/ 目录的 Flatbuffers / Protocol Buffers 协议定义文件以及 docs/source/format/ 下的规范文档的任何改动都必须遵循严格的治理流程。本文基于 docs/source/format/Changing.rst 展开完整梳理修改 Arrow 格式规范必须经历的公开讨论、共识投票、双参考实现与集成测试、版本号递增四大环节并结合仓库中的协议定义、集成测试文档与示例数据说明每一步背后为什么必须这样做。一、为什么格式变更如此谨慎跨语言兼容是底线Changing.rst开篇即点明核心原则Cross-language compatibility is important in Apache Arrow.Arrow 不是单一语言的库而是由 C、Java、Rustarrow-rs、Go 等多个独立实现共同维护的一套格式契约。格式文件Flatbuffers 定义File.fbs、Message.fbs、Schema.fbs、Tensor.fbs、SparseTensor.fbs以及 Flight RPC 的Flight.proto、FlightSql.proto是这套契约的宪法。任何一处的字段新增、类型扩展或语义调整都会同时影响所有语言实现以及所有读写旧数据的下游系统。因此对格式的修改被施加了两条硬性要求必须在公开邮件列表上讨论并投票——确保变更经过社区共识而非某个实现单方面拍板必须至少有两个参考实现以及配套的集成测试——确保变更在多种语言中行为一致、真正可互通。这两条要求不要求按顺序执行。Changing.rst特别指出在大多数情况下先有一个草案级别的参考实现对设计讨论非常有帮助。换句话说先写代码验证可行性再回到邮件列表讨论是完全被鼓励的做法。此外还有一个强制附带项必须同步更新 docs/source/format/ 下的对应文档。格式改了而文档没跟上跨语言实现者将无从实现。二、讨论与投票流程[DISCUSS]与[VOTE]1. 公开讨论[DISCUSS]前缀任何格式变更的讨论都应在 Apache Arrow 的公开邮件列表 devarrow.apache.org 上进行任何人都可以参与。发起讨论的邮件主题必须以[DISCUSS]作为前缀。Changing.rst也如实说明实践中社区有时会使用[Discuss]、DISCUSS:等类似变体但[DISCUSS]是推荐的标准写法。文档给出的两个真实讨论示例主题格式可作参照[Discuss][Format] Add 32-bit and 64-bit Decimals——关于扩展 Decimal 位宽的讨论最终落地为格式版本 1.5 中的 Decimal32/Decimal64详见本文第五节[DISCUSS][Format] Starting to do some concrete work on the new StringView columnar data type——关于新增 StringView 列式数据类型的讨论最终落地为格式版本 1.4 中的 BinaryView/Utf8View。2. 共识投票[VOTE]前缀讨论的目的是达成共识。当[DISCUSS]线程中社区意见收敛后即可发起正式的投票线程确认共识。与讨论线程类似投票线程的主题必须以[VOTE]作为前缀。这一机制与 Apache 软件基金会的通用投票流程一脉相承可以理解为 Apache 治理模式在格式规范上的具体落地讨论是开放的、低门槛的而投票是正式的、可追踪的共识确认动作。三、至少两个参考实现为什么Python 不算一个投票通过只是意愿达成接下来必须用代码证明变更可行。要求是至少要有两个参考实现以及配套的集成测试用以确认格式变更在跨语言场景下兼容且一致。Changing.rst特别澄清了一个容易误解的点参考实现必须是完整的 Arrow 实现。例如✅ C 库是合格的参考实现❌ Python 库不合格——因为 pyarrow 本质上是 C 库的包装层用它验证等于用同一个实现测自己。当前被认可的候选实现包括候选实现说明C 实现仓库 cpp/ 目录功能最全的参考实现之一Java 实现独立于 C 的完整实现Rustarrow-rs实现独立的 Rust 生态实现Go 实现独立的 Go 实现需要注意的是这份清单不是封闭的社区可以通过讨论和投票把更多实现加入名单。同时可以用 docs/source/format/../status 来判断哪些实现是完整的——只有功能覆盖完整的实现才有资格作为格式参考实现。集成测试如何证明两个实现真的一致参考实现的要求与仓库中的集成测试体系直接挂钩。Integration.rst 详细描述了这一机制测试数据集使用一种专门为 Arrow 集成测试设计的 JSON 格式integration_json_examples/simple.json 是仓库内的示例文件每个实现提供 JSON 与 Arrow 内存表示之间的转换入口并能以目标格式IPC / Flight / C Data Interface暴露数据每种格式都针对所有生产者, 消费者实现组合进行测试生产者读 JSON → 转内存 Arrow → 以被测格式写出消费者以该格式读入 → 转回内存 Arrow → 再读同一份 JSON → 校验两份数据完全一致。以 IPC 格式为例C 作为生产者读 JSON 并写出 Arrow IPC 文件Java 作为消费者读同一 JSON 并读入该 IPC 文件最后比对两个内存数据集是否相等。以 C Data Interface 为例测试框架在堆上分配ArrowArray结构Go 进程内入口将 JSON 中的一个 record batch 导出到该结构C# 进程内入口导入并比对必要时还会断言内存占用未增长即导出没有泄漏。手动跑集成测试的命令出自 Integration.rst$ pip install -e dev/archery[integration] $ archery integration --help只测 C 的 IPC 集成archery integration --run-ipc --with-cpp1加上 Java需先构建 Java 端 jar 并设置环境变量VERSION14.0.0-SNAPSHOT export ARROW_JAVA_INTEGRATION_JAR$JAVA_DIR/tools/target/arrow-tools-$VERSION-jar-with-dependencies.jar archery integration --run-ipc --with-cpp1 --with-java1运行全部测试含 Flight 与 C Data Interfacearchery integration --with-all --run-flight --run-ipc --run-c-data注意C 参与集成测试需要以-DARROW_BUILD_INTEGRATIONON构建见 Integration.rst。这些命令的实现位于仓库 dev/archery/数据生成逻辑见其中datagen.py。集成测试覆盖的场景相当全面同样引自 Integration.rst原始类型、Null、Decimal128/256、各类时间单位、IntervalMonthDayNano 单独成例、Map含非规范 Map、嵌套类型List/Struct/大偏移 List、Union、自定义元数据、重复字段名 Schema、字典类型有符号/无符号索引、嵌套字典、Run-End Encoded、BinaryView/StringView、ListView/LargeListView、扩展类型等此外还有基于旧版本 0.14.1 / 0.17.1 格式的向后兼容 gold 文件测试、大小端自动转换测试、LZ4/ZSTD 压缩测试、共享字典批次测试。这些清单恰好就是新格式特性落地时必须通过哪些验证的实操参考。四、版本号递增格式版本与库版本是两套体系格式变更通过后格式版本号必须递增。这里要区分两个概念详见 Versioning.rst格式版本Format Version描述格式本身独立于任何库的版本号库版本Library Version各语言实现的发布版本。每个库版本对应一个格式版本且多个库版本可以对应同一个格式版本。例如库版本 2.0.0 和 3.0.0 可能都跟踪格式版本 1.0.0。从 1.0.0 起库版本遵循语义化版本Semantic Versioning。格式版本的兼容性语义场景保证向后兼容只要格式主版本号不变新版本客户端库能读取旧客户端库产生的任何数据和元数据向前兼容旧客户端库要么能读新库生成的数据要么能检测出自己无法正确读取格式次版本号递增如 1.0.0 → 1.1.0表示新增了旧版本没有的特性只要不使用这些新特性如新数据类型向前兼容性即得以保持长期稳定性格式主版本号变更如 1.0.0 → 2.0.0意味着兼容性保证被破坏属于例外事件项目并不预期频繁发生一旦发生会极其谨慎地确保不损害生产应用1.0.0 之前不提供向前/向后兼容保证但尽力保证新客户端能读取 0.8.0 起的序列化数据1.0.0 以来的格式演进每一次变更的双实现 投票产物Versioning.rst 记录了 1.0.0 之后新增的五个次版本零个主版本变更每一条都是讨论 → 投票 → 双实现 集成测试流程的产出物格式版本新增内容1.1256 位 Decimal 类型1.2MonthDayNano 间隔类型1.3Run-End Encoded 布局Columnar.rst 中run-end-encoded-layout锚点1.4变长二进制视图布局及 BinaryView/Utf8View 类型ListView 与 LargeListView 类型变长缓冲variadic buffers见 Message.fbs 中variadicBufferCounts字段1.5将 Decimal 位宽扩展至允许 32 位与 64 位类型可以看到Message.fbs 中RecordBatch表的variadicBufferCounts字段、CompressionType枚举LZ4_FRAME / ZSTD、BodyCompression表以及MessageHeader联合Schema、DictionaryBatch、RecordBatch、Tensor、SparseTensor等结构正是格式版本演进在协议定义文件上留下的痕迹DictionaryBatch的isDelta字段则支撑了集成测试中共享字典批次这类用例。这些.fbs/.proto文件与 docs/source/format/ 文档共同构成足以让任何人从零实现一套 Arrow的完整规范——这正是Changing.rst要求格式变更必须配套更新两者的原因。五、一套可复制的完整变更流程实操视角综合以上四个环节向 Arrow 格式规范提交一项变更的完整路径如下可选但推荐先写草案实现在 C 或 Java 等参考实现中做出一个可运行的草稿用真实代码检验设计为讨论提供素材发起公开讨论在 devarrow.apache.org 以[DISCUSS]前缀开新线程说明变更动机、设计与影响面任何人都可参与达成共识后发起投票以[VOTE]前缀开投票线程确认社区达成共识落地至少两个参考实现在两个完整 Arrow 实现如 C 与 Java中实现该变更并通过archery integration系列命令跑通对应集成测试必要时补充 gold 文件测试可用archery integration --with-cpp 1 --write-gold-files目录生成递增格式版本号按 Versioning.rst 的规则递增格式次版本号并如实记录新增特性同步更新文档更新 docs/source/format/ 下的规范文档布局、元数据、IPC 等保证协议定义与文档描述一致。这套流程的每一项约束——公开讨论、共识投票、双参考实现、集成测试、版本递增、文档同步——都是为同一个目标服务的让 Apache Arrow 的跨语言兼容性在格式持续演进的过程中始终成立。对于希望为 Arrow 贡献新数据类型或新特性的开发者而言Changing.rst就是必须首先读懂的游戏规则。【免费下载链接】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），仅供参考 Apache Arrow 格式规范变更流程指南：跨语言兼容、讨论投票与参考实现要求
Apache Arrow 格式规范变更流程指南跨语言兼容、讨论投票与参考实现要求【免费下载链接】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 的核心价值在于通用列式格式 多语言工具箱同一份数据可以零拷贝地在 C、Java、Rust、Go 等语言之间自由交换。要让这种跨语言互操作长期成立格式规范位于仓库 format/ 目录的 Flatbuffers / Protocol Buffers 协议定义文件以及 docs/source/format/ 下的规范文档的任何改动都必须遵循严格的治理流程。本文基于 docs/source/format/Changing.rst 展开完整梳理修改 Arrow 格式规范必须经历的公开讨论、共识投票、双参考实现与集成测试、版本号递增四大环节并结合仓库中的协议定义、集成测试文档与示例数据说明每一步背后为什么必须这样做。一、为什么格式变更如此谨慎跨语言兼容是底线Changing.rst开篇即点明核心原则Cross-language compatibility is important in Apache Arrow.Arrow 不是单一语言的库而是由 C、Java、Rustarrow-rs、Go 等多个独立实现共同维护的一套格式契约。格式文件Flatbuffers 定义File.fbs、Message.fbs、Schema.fbs、Tensor.fbs、SparseTensor.fbs以及 Flight RPC 的Flight.proto、FlightSql.proto是这套契约的宪法。任何一处的字段新增、类型扩展或语义调整都会同时影响所有语言实现以及所有读写旧数据的下游系统。因此对格式的修改被施加了两条硬性要求必须在公开邮件列表上讨论并投票——确保变更经过社区共识而非某个实现单方面拍板必须至少有两个参考实现以及配套的集成测试——确保变更在多种语言中行为一致、真正可互通。这两条要求不要求按顺序执行。Changing.rst特别指出在大多数情况下先有一个草案级别的参考实现对设计讨论非常有帮助。换句话说先写代码验证可行性再回到邮件列表讨论是完全被鼓励的做法。此外还有一个强制附带项必须同步更新 docs/source/format/ 下的对应文档。格式改了而文档没跟上跨语言实现者将无从实现。二、讨论与投票流程[DISCUSS]与[VOTE]1. 公开讨论[DISCUSS]前缀任何格式变更的讨论都应在 Apache Arrow 的公开邮件列表 devarrow.apache.org 上进行任何人都可以参与。发起讨论的邮件主题必须以[DISCUSS]作为前缀。Changing.rst也如实说明实践中社区有时会使用[Discuss]、DISCUSS:等类似变体但[DISCUSS]是推荐的标准写法。文档给出的两个真实讨论示例主题格式可作参照[Discuss][Format] Add 32-bit and 64-bit Decimals——关于扩展 Decimal 位宽的讨论最终落地为格式版本 1.5 中的 Decimal32/Decimal64详见本文第五节[DISCUSS][Format] Starting to do some concrete work on the new StringView columnar data type——关于新增 StringView 列式数据类型的讨论最终落地为格式版本 1.4 中的 BinaryView/Utf8View。2. 共识投票[VOTE]前缀讨论的目的是达成共识。当[DISCUSS]线程中社区意见收敛后即可发起正式的投票线程确认共识。与讨论线程类似投票线程的主题必须以[VOTE]作为前缀。这一机制与 Apache 软件基金会的通用投票流程一脉相承可以理解为 Apache 治理模式在格式规范上的具体落地讨论是开放的、低门槛的而投票是正式的、可追踪的共识确认动作。三、至少两个参考实现为什么Python 不算一个投票通过只是意愿达成接下来必须用代码证明变更可行。要求是至少要有两个参考实现以及配套的集成测试用以确认格式变更在跨语言场景下兼容且一致。Changing.rst特别澄清了一个容易误解的点参考实现必须是完整的 Arrow 实现。例如✅ C 库是合格的参考实现❌ Python 库不合格——因为 pyarrow 本质上是 C 库的包装层用它验证等于用同一个实现测自己。当前被认可的候选实现包括候选实现说明C 实现仓库 cpp/ 目录功能最全的参考实现之一Java 实现独立于 C 的完整实现Rustarrow-rs实现独立的 Rust 生态实现Go 实现独立的 Go 实现需要注意的是这份清单不是封闭的社区可以通过讨论和投票把更多实现加入名单。同时可以用 docs/source/format/../status 来判断哪些实现是完整的——只有功能覆盖完整的实现才有资格作为格式参考实现。集成测试如何证明两个实现真的一致参考实现的要求与仓库中的集成测试体系直接挂钩。Integration.rst 详细描述了这一机制测试数据集使用一种专门为 Arrow 集成测试设计的 JSON 格式integration_json_examples/simple.json 是仓库内的示例文件每个实现提供 JSON 与 Arrow 内存表示之间的转换入口并能以目标格式IPC / Flight / C Data Interface暴露数据每种格式都针对所有生产者, 消费者实现组合进行测试生产者读 JSON → 转内存 Arrow → 以被测格式写出消费者以该格式读入 → 转回内存 Arrow → 再读同一份 JSON → 校验两份数据完全一致。以 IPC 格式为例C 作为生产者读 JSON 并写出 Arrow IPC 文件Java 作为消费者读同一 JSON 并读入该 IPC 文件最后比对两个内存数据集是否相等。以 C Data Interface 为例测试框架在堆上分配ArrowArray结构Go 进程内入口将 JSON 中的一个 record batch 导出到该结构C# 进程内入口导入并比对必要时还会断言内存占用未增长即导出没有泄漏。手动跑集成测试的命令出自 Integration.rst$ pip install -e dev/archery[integration] $ archery integration --help只测 C 的 IPC 集成archery integration --run-ipc --with-cpp1加上 Java需先构建 Java 端 jar 并设置环境变量VERSION14.0.0-SNAPSHOT export ARROW_JAVA_INTEGRATION_JAR$JAVA_DIR/tools/target/arrow-tools-$VERSION-jar-with-dependencies.jar archery integration --run-ipc --with-cpp1 --with-java1运行全部测试含 Flight 与 C Data Interfacearchery integration --with-all --run-flight --run-ipc --run-c-data注意C 参与集成测试需要以-DARROW_BUILD_INTEGRATIONON构建见 Integration.rst。这些命令的实现位于仓库 dev/archery/数据生成逻辑见其中datagen.py。集成测试覆盖的场景相当全面同样引自 Integration.rst原始类型、Null、Decimal128/256、各类时间单位、IntervalMonthDayNano 单独成例、Map含非规范 Map、嵌套类型List/Struct/大偏移 List、Union、自定义元数据、重复字段名 Schema、字典类型有符号/无符号索引、嵌套字典、Run-End Encoded、BinaryView/StringView、ListView/LargeListView、扩展类型等此外还有基于旧版本 0.14.1 / 0.17.1 格式的向后兼容 gold 文件测试、大小端自动转换测试、LZ4/ZSTD 压缩测试、共享字典批次测试。这些清单恰好就是新格式特性落地时必须通过哪些验证的实操参考。四、版本号递增格式版本与库版本是两套体系格式变更通过后格式版本号必须递增。这里要区分两个概念详见 Versioning.rst格式版本Format Version描述格式本身独立于任何库的版本号库版本Library Version各语言实现的发布版本。每个库版本对应一个格式版本且多个库版本可以对应同一个格式版本。例如库版本 2.0.0 和 3.0.0 可能都跟踪格式版本 1.0.0。从 1.0.0 起库版本遵循语义化版本Semantic Versioning。格式版本的兼容性语义场景保证向后兼容只要格式主版本号不变新版本客户端库能读取旧客户端库产生的任何数据和元数据向前兼容旧客户端库要么能读新库生成的数据要么能检测出自己无法正确读取格式次版本号递增如 1.0.0 → 1.1.0表示新增了旧版本没有的特性只要不使用这些新特性如新数据类型向前兼容性即得以保持长期稳定性格式主版本号变更如 1.0.0 → 2.0.0意味着兼容性保证被破坏属于例外事件项目并不预期频繁发生一旦发生会极其谨慎地确保不损害生产应用1.0.0 之前不提供向前/向后兼容保证但尽力保证新客户端能读取 0.8.0 起的序列化数据1.0.0 以来的格式演进每一次变更的双实现 投票产物Versioning.rst 记录了 1.0.0 之后新增的五个次版本零个主版本变更每一条都是讨论 → 投票 → 双实现 集成测试流程的产出物格式版本新增内容1.1256 位 Decimal 类型1.2MonthDayNano 间隔类型1.3Run-End Encoded 布局Columnar.rst 中run-end-encoded-layout锚点1.4变长二进制视图布局及 BinaryView/Utf8View 类型ListView 与 LargeListView 类型变长缓冲variadic buffers见 Message.fbs 中variadicBufferCounts字段1.5将 Decimal 位宽扩展至允许 32 位与 64 位类型可以看到Message.fbs 中RecordBatch表的variadicBufferCounts字段、CompressionType枚举LZ4_FRAME / ZSTD、BodyCompression表以及MessageHeader联合Schema、DictionaryBatch、RecordBatch、Tensor、SparseTensor等结构正是格式版本演进在协议定义文件上留下的痕迹DictionaryBatch的isDelta字段则支撑了集成测试中共享字典批次这类用例。这些.fbs/.proto文件与 docs/source/format/ 文档共同构成足以让任何人从零实现一套 Arrow的完整规范——这正是Changing.rst要求格式变更必须配套更新两者的原因。五、一套可复制的完整变更流程实操视角综合以上四个环节向 Arrow 格式规范提交一项变更的完整路径如下可选但推荐先写草案实现在 C 或 Java 等参考实现中做出一个可运行的草稿用真实代码检验设计为讨论提供素材发起公开讨论在 devarrow.apache.org 以[DISCUSS]前缀开新线程说明变更动机、设计与影响面任何人都可参与达成共识后发起投票以[VOTE]前缀开投票线程确认社区达成共识落地至少两个参考实现在两个完整 Arrow 实现如 C 与 Java中实现该变更并通过archery integration系列命令跑通对应集成测试必要时补充 gold 文件测试可用archery integration --with-cpp 1 --write-gold-files目录生成递增格式版本号按 Versioning.rst 的规则递增格式次版本号并如实记录新增特性同步更新文档更新 docs/source/format/ 下的规范文档布局、元数据、IPC 等保证协议定义与文档描述一致。这套流程的每一项约束——公开讨论、共识投票、双参考实现、集成测试、版本递增、文档同步——都是为同一个目标服务的让 Apache Arrow 的跨语言兼容性在格式持续演进的过程中始终成立。对于希望为 Arrow 贡献新数据类型或新特性的开发者而言Changing.rst就是必须首先读懂的游戏规则。【免费下载链接】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），仅供参考