Apache DataFusion Substrait 测试数据目录全解析：testdata 结构与扩展实战指南

大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载导读本文围绕 Apache DataFusion 仓库中 datafusion/substrait/tests/testdata 目录下的测试数据展开系统讲解 Substrait producer/consumer 测试所依赖的 CSV、Parquet 与计划文件的结构、用途与新增方式。读完本文你将掌握 DataFusion 与 Substrait 互转测试的完整数据组织方式并能在自己的测试工程中正确引用、生成与注册这类测试数据。一、testdata 目录在 Substrait 测试体系中的定位Apache DataFusion 的 Substrait 支持位于 datafusion/substrait crate它提供了一套基于 Substrait 协议一种基于 protobuf 的跨语言关系代数序列化格式的producer生产者与consumer消费者producer 负责把 DataFusion 的逻辑计划LogicalPlan与物理计划ExecutionPlan序列化为 Substrait 计划consumer 负责把 Substrait 计划反序列化为 DataFusion 计划。其核心能力在 datafusion/substrait/src/lib.rs 的 crate 文档中有明确说明可用于让 DataFusion 执行其他系统如 Apache Calcite生成的 Substrait 计划、把 DataFusion 计划交由其他系统执行、跨 FFI 边界如 Python 与 Rust 之间传递查询计划、以及在节点之间传递查询计划。tests/testdata目录正是这一机制的测试数据载体。目录的 Readme.md 明确指出该目录存放的是 Substrait crate 的测试数据且crate 目前仍处于起步init阶段许多功能尚未实现因此这里的测试数据刻意保持简单——围绕 logical plan 与 physical plan 两套 producer/consumer 的最小可用场景设计而非像 parquet-testing 子模块那样覆盖海量真实数据形态。从源码结构看测试体系由三部分组成见 tests组成路径作用集成测试入口tests/substrait_integration.rs聚合cases目录下所有测试用例并运行测试用例tests/cases包含逻辑计划往返、物理计划往返、TPCH 消费、聚合、窗口等用例测试数据tests/testdata存放 CSV / Parquet 示例文件与 Substrait JSON 计划文件二、四类示例数据文件清单与用途testdata根目录下目前包含四类基础数据文件原始文件可点击查看文件说明empty.csv一个空 CSV 文件文件内容为空用于验证空表场景下的计划序列化与消费empty.parquet一个只有元数据metadata的空 Parquet 文件不包含任何数据行data.csv一个简单 CSV 文件6 列、2 行数据覆盖多种基础类型data.parquet由data.csv通过 Pythonpandas生成的 Parquet 文件其中 CSV 与 Parquet 的搭配是有意为之同一份逻辑上相同的数据分别以文本CSV与列存Parquet两种格式存在从而可以分别验证DataFusion 的 CSV / Parquet 数据源在 SubstraitReadRel中的表达ReadRel反序列化回 DataFusion 表扫描计划时 schema 是否保持一致空文件empty 系列在 producer 端是否会被正确处理避免出现空 schema 或空 batch 的序列化崩溃。三、示例数据内容详解data.csv 与 data.parquetdata.csv的实际内容完整继承自 data.csva,b,c,d,e,f 1,2.0,2020-01-01,false,4294967295,a 3,4.5,2020-01-01,true,2147483648,b可以看到其设计刻意覆盖了多种基础数据类型a整数列1、3b浮点列2.0、4.5c日期列2020-01-01两行相同日期便于验证谓词过滤d布尔列false、truee大整数列4294967295、2147483648均超出 32 位有符号整数范围可用于验证类型推断f字符串列带引号的a、b。data.parquet由该 CSV 通过pandas生成原始文档给出的参考命令如下import pandas as pd df pandas.read_csv(data.csv) df.to_parquet(data.parquet)注意原文示例中pandas.read_csv的写法是pd.read_csv的笔误实际使用时请以pd.read_csv(data.csv)为准即先import pandas as pd。需要特别说明的是用pandas生成 Parquet 只是该文件的历史来源仓库内部测试实际通过 DataFusion 自身的 Parquet 数据源读取它pandas并非 DataFusion 的依赖仅作为生成测试数据的外部工具。四、Substrait 计划文件test_plans 与 tpch_substrait_plans除基础数据文件外testdata目录还包含两类 Substrait 计划 JSON 文件它们是 consumer 测试的核心输入。4.1 根目录计划文件与 test_plans根目录下的 contains_plan.substrait.json 是一个典型的 Substrait 计划示例其结构展示了 Substrait JSON 计划的三大构成要素extensionUris/extensions函数扩展注册表例如contains:str_str字符串函数被锚定到functions_string.yaml扩展 URIbaseSchemanamedTable定义读取表的列名、类型与空值约束如NULLABILITY_REQUIRED并指名表名如nationrelations关系树由root→project→filter→read逐层嵌套emit.outputMapping决定输出列的投影。test_plans 目录则存放了大量专项计划文件覆盖了 Substrait 支持的各种关系与表达式形态例如简单查询simple_select.substrait.json、select_count_from_select_1.substrait.json集合运算union_distinct.substrait.json、intersect.substrait.json、intersect_multiset.json、minus_primary.json聚合与分组aggregate_groupings子目录、multilayer_aggregate.substrait.json、aggregate_sorted_no_project.substrait.json窗口select_window.substrait.json、double_window.substrait.json、nested_window_expression.substrait.json连接multiple_joins.json、join_with_expression_key.json、mixed_join_equal_and_indistinct.json表达式scalar_fn_to_built_in_binary_expr_xor.substrait.json、nested_list_expressions.substrait.json、higher_order_function.json边界场景empty相关、duplicate_name_in_union.substrait.json、non_nullable_lists.substrait.json等。4.2 tpch_substrait_plans官方互操作测试集tpch_substrait_plans 目录收录了 TPC-H 全部 22 条查询query_01_plan.json至query_22_plan.json的 Substrait 计划文件。其 README.md 说明这些 JSON 文件源自 substrait-io/consumer-testing 项目的 TPCH consumer 集成测试集用于验证 DataFusion 作为 Substraitconsumer时能否正确读取第三方生态生成的计划。对应测试实现在 tests/cases/consumer_integration.rs测试读取 JSON 计划 → 解析为 protobufPlan→ 通过from_substrait_plan转为 DataFusion 逻辑计划 → 生成物理计划 → 用 insta 快照断言计划结构与预期一致。例如tpch_test_01断言 Q1 被还原为Projection → Sort → Aggregate → Projection → Filter → TableScan(LINEITEM)的结构。五、测试数据是如何被消费的源码级调用链理解 testdata 的实际用法需要顺着测试工具函数走一遍完整调用链。核心工具代码在 tests/utils.rs读取计划read_json(path)用serde_json::from_reader把.substrait.json文件反序列化为substrait::proto::Plan注册 schemaadd_plan_schemas_to_ctx创建DefaultSubstraitConsumer并通过TestSchemaCollector递归遍历计划中的所有Rel提取NamedTable的表名与baseSchema将其转为 DataFusion 的TableReferenceBare / Partial / Full 三级命名空间最后以EmptyTable注册进SessionContext——这样消费计划时即使没有真实数据文件也能完成 schema 校验与计划还原消费计划from_substrait_plan(ctx.state(), proto)见 src/logical_plan/consumer/plan.rs把 SubstraitPlan转回 DataFusionLogicalPlan验证ctx.execute_logical_plan(plan)执行并将结果与快照比对。而 producer 方向对应 src/logical_plan/producer/plan.rs 的to_substrait_plan把LogicalPlan包装为RelRoot收集扩展函数后生成带版本号version_with_producer(datafusion)的 SubstraitPlan。两侧配合即可实现完整往返round-trip测试见 tests/cases/roundtrip_logical_plan.rs 与 tests/cases/roundtrip_physical_plan.rs。对于 CSV/Parquet 文件数据本身物理计划往返测试 roundtrip_physical_plan.rs 展示了data.parquet的注册方式let ctx SessionContext::new(); let explicit_options ParquetReadOptions::default(); ctx.register_parquet(data, tests/testdata/data.parquet, explicit_options) .await?;注册后即可对data表构造 DataFrame、生成物理计划并经producer::to_substrait_rel序列化、consumer::from_substrait_rel还原最终断言两棵物理计划的 display 文本完全一致。六、新增测试数据的完整步骤当需要为某个新算子或新表达式补充测试数据时Readme.md 给出了最小操作路径结合仓库测试惯例可归纳为四步步骤一在 testdata 目录创建数据文件。在 datafusion/substrait/tests/testdata 下新建 CSV 或 Parquet 文件命名与用途一致如xxx.csv/xxx.parquet。如果需要 Parquet 版本可参照上文用pandas从 CSV 生成。步骤二在测试源码中引用该文件。以 DataFusion Parquet 数据源为例在tests/cases下的用例文件或tests/utils.rs中注册表let ctx SessionContext::new(); let explicit_options ParquetReadOptions::default(); ctx.register_parquet(data, tests/testdata/data.parquet, explicit_options)其中tests/testdata/...是相对于datafusion/substraitcrate 根目录的路径测试运行时的当前工作目录即为该 crate 目录因此路径可直接书写。步骤三如果需要消费 Substrait 计划则补充计划 JSON。在test_plans下新建xxx.substrait.json通过utils::test::read_json读取再经add_plan_schemas_to_ctx注册 schema 后调用from_substrait_plan还原。步骤四运行测试验证。在datafusion/substrait目录下执行cargo test若新增了 insta 快照断言首次运行会生成.snap快照文件人工确认结果正确后再通过cargo insta accept接受快照或直接按仓库 CI 中 insta 的约定提交。七、运行与验证测试命令与边界说明整个 Substrait 测试套件通过统一入口运行# 运行 substrait crate 全部测试含 testdata 相关用例 cargo test -p datafusion-substrait # 只运行消费端 TPCH 集成测试 cargo test -p datafusion-substrait -- consumer_integration需要注意的边界与前提Substrait crate 仍处于起步阶段utils.rs的collect_schemas_from_rel中对LocalFiles、ExtensionTable、IcebergTable等读取类型以及部分RelType仍以todo!()或注释占位见 tests/utils.rs并非所有 Substrait 特性都已实现同样地lib.rs 文档提醒Substrait 尚未覆盖 DataFusion 的全部计划与表达式若需要 DataFusion 专属格式的完整往返应使用datafusion-protocratetestdata 是只读的测试资产贡献者应通过“新增文件 注册引用”的方式扩展而非修改既有文件破坏现有快照断言。八、小结testdata 的设计哲学从整体上看tests/testdata体现了 Substrait 测试数据的三层设计最小数据文件层CSV/Parquet用极简数据覆盖基础类型与空文件场景为 producer 提供可序列化的输入专项计划层test_plans按算子/表达式维度组织的 Substrait JSON为 consumer 提供可反序列化的输入互操作计划层tpch_substrait_plans对接 Substrait 官方生态的 TPC-H 计划验证跨引擎兼容性。理解这套数据组织方式后无论你是要为 DataFusion 新增 Substrait 算子支持还是在自己的项目中基于datafusion-substrait做 plan 互转都可以直接复用这里的文件结构与注册模式快速搭建可验证、可回归的测试基线。进一步的实现细节可继续研读 src/logical_planproducer/consumer 双端与 src/physical_plan物理计划互转下的源码。赞分享大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载相关推荐OpenIM Server 测试数据体系完全解读testdata 目录结构、JSON 格式与 E2E 测试实践OpenIM Server 测试数据体系完全解读testdata 目录结构、JSON 格式与 E2E 测试实践 test/testdata 是 OpenIM即时通讯后端微服务WebSocketA2A 协议实战基于 Google ADK 与 Spring AI 搭建远程智能体服务端与客户端A2A 协议实战基于 Google ADK 与 Spring AI 搭建远程智能体服务端与客户端 导读 本文围绕小傅哥 AI 系列技术文档中关于 A2AA文档教程后端Tink GCP KMS 测试凭据全解析java_src/testdata/gcp 目录结构与自定义凭据配置指南Tink GCP KMS 测试凭据全解析java_src/testdata/gcp 目录结构与自定义凭据配置指南 Tink 是多语言、跨平台的开源密码学库其密码学应用安全上一篇TinaCMS MDX 删除线标记解析与序列化实战markdown-basic-marks-strikethrough 测试用例深度剖析下一篇Element UI Badge 徽标组件完全指南数字角标、最大值截断、红点提示与自定义文本实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考