大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载这篇技术指南围绕 Apache DataFusion 官方基准测试设计规范.ai/skills/add-benchmarks/SKILL.md展开系统讲解在为 DataFusion 设计或新增 benchmark 时必须遵循的两大设计原则、SQL 基准测试的三条集成准则并结合仓库内的 SQL benchmark 框架benchmarks/sql_benchmarks/README.md与bench.sh脚本给出可复制的实战步骤。读完本文你将掌握如何用 SQL 优先思路设计面向特定算子的基准测试、如何挑选关键工作负载轴输入规模、过滤选择性等并标注查询、如何将新查询/新套件无缝接入 DataFusion 官方 benchmark 流程以及底层.benchmark指令、.suite元数据与环境变量的工作机制。为什么要有一套基准测试设计规范DataFusion 是一个数据量庞大的 SQL 查询引擎其优化器与执行算子join、aggregation、window、sort 等的改动极其频繁。如果没有统一的基准测试规范社区贡献的 benchmark 很容易出现两种问题一是测了内部工具函数而不是用户真正触发的执行路径导致优化方向与实际端到端收益脱节二是测试负载设计不合理无法反映真实工作负载的变化规律使比较结果失去参考价值。因此仓库在.ai/skills/add-benchmarks/SKILL.md中沉淀了两条核心设计原则与三条 SQL 基准测试集成准则下面逐一展开。设计原则一尽可能使用最高层接口SQL 优先第一条原则是Use the highest-level interface优先使用 SQL 这种最高层接口同时让被测算子之外的其余工作在基准测试中尽量廉价。具体来说测函数的求值路径而不是孤立地测内部工具函数。例如要评估某个表达式的优化收益应当通过一条真实 SQL 查询触发它的求值路径而不是在 Rust 里直接调用内部工具函数做微基准。从端到端运行时评估优化收益。SQL 级别的基准更容易维护也能直接回答这项优化到底让整个查询快了多久。避免把时间花在只占总运行时很小一部分的代码上。如果某个优化点对应的代码只占整体运行时的 5%即使优化 50% 也毫无意义——高层的 SQL 基准能帮你快速识别这类无效优化。SQL 还是 Rust 微基准的抉择标准规范给出了一个非常实用的判断流程——先尝试用 SQL 实现该 benchmark如果确实还是 Rust 微基准更合适再使用 Criterion。这也与仓库中两套并行的基准体系对应SQL 基准位于benchmarks/sql_benchmarks/由.benchmark文本文件驱动无需重新编译引擎即可增删查询Rust 微基准位于各 crate 的benches/目录如datafusion/core/benches/、datafusion/physical-expr/benches/使用 Criterion 统计。源码佐证nlj 套件如何践行SQL 优先以嵌套循环连接Nested-Loop Join套件benchmarks/sql_benchmarks/nlj/为例其q01.benchmark文件benchmarks/sql_benchmarks/nlj/benchmarks/q01.benchmark完整展示了 SQL 优先的写法name Q01 group nlj expect_plan NestedLoopJoinExec run -- Q1: INNER 10K x 10K | LOW 0.1% SELECT * FROM range(10000) AS t1 JOIN range(10000) AS t2 ON (t1.value t2.value) % 1000 0;这里有两个值得注意的细节数据源用range()而非 Parquet 扫描range()是纯内存生成序列扫描开销可忽略从而让测量的热点集中在 NestedLoopJoinExec 本身expect_plan NestedLoopJoinExec指令在基准运行前检查物理计划中确实包含NestedLoopJoinExec防止优化器把计划改写成哈希连接而测错了算子。设计原则二变化关键工作负载轴Vary the key workload axes第二条原则要求基准测试覆盖关键工作负载轴key axes的变化。规范以 join 基准为例给出最常见的两个轴两侧的输入规模input sizejoin 过滤选择性join-filter selectivity。选定轴之后选择能代表真实使用场景的典型组合即可不必做全组合full combinatorial coverage覆盖。添加基准查询时只需在每条查询的 SQL 注释里标注每个轴对应的决策。规范给出的示例-- Q1: Small left input, large right input; 0.1% of pairs match. SELECT * FROM generate_series(1, 100) AS l JOIN generate_series(1, 100000) AS r ON (l.value r.value) % 1000 0; -- Q2: Medium inputs on both sides; no filter. SELECT * FROM generate_series(1, 1000) AS l CROSS JOIN generate_series(1, 1000) AS r;从仓库现有套件可以看到这种思想的落地nlj套件的 17 条查询覆盖了INNER 10K x 10K | LOW 0.1%、不同输入规模与匹配比例的组合可在benchmarks/sql_benchmarks/nlj/benchmarks/下逐一查看null_aware_join套件则按 NULL 比例、相关/非相关维度拆分为 Q01-Q08 等用例详见benchmarks/sql_benchmarks/README.md中的套件说明表。SQL 基准测试的三条集成准则对于新增的 SQL benchmark规范提出了三条必须遵守的实践准则下面逐一结合仓库源码展开。准则一让其他算子保持廉价Keep other operators cheap当一条 SQL 基准瞄准某个特定算子时其他算子所做的工作要尽量轻量。规范明确推荐使用generate_series()之类的数据源而不是 Parquet 扫描否则扫描开销会主导测量结果掩盖目标算子的真实表现。可参考nlj套件的实现——它的数据全部来自range()/generate_series()因此在bench.sh中对应注释为nlj uses range() function, no data generation needed。准则二集成到顶层基准脚本 bench.sh新基准必须能通过bench.sh完成数据准备与运行。规范给出的标准操作流程从benchmarks目录执行# Generate any required dataset. ./bench.sh data new_bench # Run the benchmark. ./bench.sh run new_benchbench.sh是 DataFusion 开发者使用的总调度脚本支持data生成/下载数据、run运行指定基准、compare/compare_detail比较不同分支的基准结果三类命令。以run_tpch为例benchmarks/bench.sh中定义它通过env注入BENCH_NAME、BENCH_SIZE、DATA_DIR、TPCH_FILE_TYPE、SIMULATE_LATENCY等环境变量后调用cargo bench --bench sqldebug_run env BENCH_NAMEtpch \ BENCH_RESULTS_FILE$(sql_results_file tpch_sf${SCALE_FACTOR}_${FORMAT}) \ BENCH_SIZE${SCALE_FACTOR} \ DATA_DIR${DATA_DIR} \ PREFER_HASH_JOIN${PREFER_HASH_JOIN} \ TPCH_FILE_TYPE${FORMAT} \ SIMULATE_LATENCY${SIMULATE_LATENCY} \ ${QUERY:BENCH_QUERY${QUERY}} \ bash -c $SQL_CARGO_COMMAND从脚本结构可以看出每个基准对应一个run_name()函数数据生成则对应data_name()函数data与run两个命令通过case分发到对应函数。新增基准时在bench.sh中补充对应的 data/run 分支即可完成集成。准则三保持查询运行时间切合实际Keep query runtimes practical规范要求将负载调到每条查询每次执行大约数秒的量级。这样既能降低计时噪声的相对影响又不会让整个套件跑起来过于耗时。这与仓库中各套件的负载设计一致——例如null_aware_join的非相关查询使用NAJ_LARGE_ROWS默认1000000行相关查询使用NAJ_ROWS默认10000行都是为控制每次执行耗时而在真实性与可运行性之间做出的权衡。深入理解 SQL benchmark 框架的工作机制为了让新增基准符合准则二你需要理解benchmarks/sql_benchmarks/README.md所描述的框架机制。SQL benchmark 框架刻意保持简单基准由.benchmark文本文件和 SQL 查询驱动新增或修改基准无需触碰引擎核心代码、也无需重新编译。benchmark_runner 的运行入口首选运行方式是benchmark_runner二进制它从sql_benchmarks目录发现套件并把套件专属选项与通用选项一并暴露为命令行参数。套件名必须位于所有选项之前# 列出所有可用套件 cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- --list # 查看 tpch 套件的帮助含套件专属选项 cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --help # 运行 tpch 第 15 号查询输出 CSV cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --query 15 --format csv # dry-run仅校验命令并打印解析结果JSON cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- clickbench --partitioning partitioned --dry-run # 结果持久化 / 校验 cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --query 1 --result-mode persist cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --query 1 --result-mode validate关键点补充--result-mode有三种取值persist保存查询结果到 CSV、validate与已保存结果比对、none默认两者都不做同时兼容BENCH_PERSIST_RESULTS/BENCH_VALIDATE环境变量显式命令行参数优先。--dry-run只打印解析后的套件、过滤器、运行模式、通用选项、套件专属值与路径替换不加载基准、不建会话、不读数据、不执行 SQL。--path/-p可覆盖声明了DATA_DIR路径替换的套件的数据目录未声明该替换的套件会拒绝该选项。取值优先级为命令行 环境变量 套件元数据默认值。套件元数据.suite文件每个可发现的套件都对应一个suite/suite.suiteTOML 元数据文件。以benchmarks/sql_benchmarks/h2o/h2o.suite为例description H2O group-by, join, and window SQL benchmarks query_pattern q{QUERY_ID_PADDED}.benchmark [path_replacements] DATA_DIR ../../data [[options]] name size env H2O_BENCH_SIZE default small values [small, medium, big] help Selects the H2O dataset size. [[options]] name format short f env H2O_FILE_TYPE default csv values [csv, parquet] help Selects the H2O data format.顶层字段字段是否必填说明description是非空描述显示在--list与套件帮助中query_pattern否基准文件名模式必须恰好包含一个{QUERY_ID}或{QUERY_ID_PADDED}占位符默认q{QUERY_ID_PADDED}.benchmarkpath_replacements否替换名到路径的映射相对路径以套件目录为基准解析DATA_DIR启用--path/-poptions否套件专属选项表数组见下examples否commanddescription对追加到套件帮助中每个[[options]]表字段字段是否必填说明name是长选项名不含--仅限小写 ASCII 字母、数字与连字符short否单个 ASCII 字母或数字不含-env是提供选项值所读取的环境变量default是命令行与环境变量均未提供时使用的值values否可接受取值省略则允许任意值包含...表示列出的值 任意其他值否则为封闭列表help是套件帮助中显示的非空文本注意选项名、短名、环境变量键在套件内必须唯一选项的环境变量键不能与path_replacements中的键重复套件选项不能占用 runner 全局选项名help、query、subgroup、iterations、partitions、batch-size、mem-pool-type、memory-limit、sort-spill-reservation-bytes、debug、simulate-latency、criterion、list、output、save-baseline、path、result-mode、dry-run等。.benchmark文件与指令系统每个单独基准由一个name.benchmark文件表示内含一系列指令directives告诉工具如何加载数据、执行初始化、运行断言、运行基准、可选地持久化/校验结果、以及最后的清理。指令一览完整定义见benchmarks/sql_benchmarks/README.md指令作用name基准名称用于 Criterion 显示名同时以BENCH_NAME提供给文件内替换group分组名称用于把多个基准归组subgroup子分组名称用于过滤到某个特定子分组如subgroup windowload初始化阶段执行的 SQL可指向文件也可直接写一条 SQL 语句后必须跟空行initload之后、基准执行之前执行同样支持文件或内联 SQL后必须跟空行run基准执行阶段可含多条语句但一个文件只能有一个run持久化/校验时只用其中最后一条SELECT/WITH语句cleanup全部指令之后执行用于清理如DROP TABLEexpect_plan检查物理计划中包含给定字符串按EXPLAIN渲染形式如expect_plan NestedLoopJoinExec每次基准只检查一次不计入测量区assert在init与run之间执行校验系统状态格式为assert 列数I SQL ----分隔的期望结果制表符或管道分隔result_query校验阶段运行验证不同于run的附加结果格式同assertresult声明期望结果文件管道分隔、带头部的 CSV校验时与run最后一条SELECT/WITH的结果比对template包含另一个基准文件支持KEYvalue参数传递include与template类似但不支持参数echo向 stdout 输出字符串便于调试变量替换benchmark 文件支持两种替换形式——字符串替换带可选默认值${ENV_VAR}与${ENV_VAR:-default}以及基于真值的 if/else 替换${ENV_VAR:-default|true value|false value}其中只有值true大小写不敏感进入 true 分支其他任何值进入 false 分支值缺失时用default选择分支。注释以#或--开头。以 h2o 套件的实际文件为例benchmarks/sql_benchmarks/h2o/benchmarks/groupby/q01.benchmarksubgroup groupby name Q01 group h2o echo Loading ${H2O_BENCH_SIZE:-small} groupby ${H2O_FILE_TYPE:-csv} h2o data load sql_benchmarks/h2o/init/load_groupby_${H2O_BENCH_SIZE:-small}_${H2O_FILE_TYPE:-csv}.sql assert I SELECT COUNT(*) 0 FROM x ---- true run SELECT id1, SUM(v1) AS v1 FROM x GROUP BY id1; result sql_benchmarks/h2o/results/groupby/${H2O_BENCH_SIZE:-small}/q01.csv这个文件完整展示了subgroup、name、group、echo、load、assert、run、result指令的组合用法以及${VAR:-default}默认值替换的实战样式。模板机制大量基准通过模板消除.benchmark文件间的重复。仓库中实际存在的模板包括benchmarks/sql_benchmarks/h2o/window_sorted.benchmark.template、benchmarks/sql_benchmarks/parquet_row_filter_skip/parquet_row_filter_skip.benchmark.template、benchmarks/sql_benchmarks/predicate_eval/predicate_eval.benchmark.template、benchmarks/sql_benchmarks/projection_subquery/projection_subquery.benchmark.template与benchmarks/sql_benchmarks/spill_views/spill_views.benchmark.template。模板内使用template指令引用并可用QUERY_NUMBER1、QUERY_NUMBER_PADDED01这样的KEYvalue行传参。常用环境变量速查SQL 基准工具支持以下通用环境变量部分环境变量说明BENCH_NAME要运行的套件名对应sql_benchmarks下的目录名如imdbBENCH_SUBGROUP套件内的子分组如 h2o 的windowBENCH_QUERY指定运行的查询编号BENCH_PERSIST_RESULTStrue/false是否将结果持久化为 CSVBENCH_VALIDATEtrue/false是否将结果与已保存结果比对两者均为 true 时以 persist 为准DATA_DIRSQL 基准加载数据的根目录默认benchmarks/dataSIMULATE_LATENCY模拟对象存储延迟20-200ms用于模拟 S3 等远程存储MEM_POOL_TYPE内存池类型fair或greedyMEMORY_LIMIT内存上限如100M、1.5G未指定则按预定义内存限制运行否则不限内存套件专属变量示例BENCH_SIZETPC-H/TPC-DS 的 scale factor默认1、TPCH_FILE_TYPEcsv/parquet/mem默认parquet、H2O_FILE_TYPEcsv/parquet默认csv、H2O_BENCH_SIZEsmall/medium/big默认small、PRED_ROWSpredicate_eval 与 parquet_row_filter_skip 的合成数据行数、RG_SIZEParquet 行组大小、PSQ_ROWS、SPILL_VIEWS_LIMIT_REPEATED/SPILL_VIEWS_LIMIT_DISTINCT等。完整列表见benchmarks/sql_benchmarks/README.md的 Benchmark configuration 一节。实战如何扩展或新增基准套件在已有套件中新增查询按规范与 README 的步骤在对应套件的queries/文件夹中新建qXX.sql如benchmarks/sql_benchmarks/h2o/init/对应目录结构新建qXX.benchmark引用适当的模板clickbench.benchmark.template、h2o.benchmark.template等并传入QUERY_NUMBER/QUERY_NUMBER_PADDED或直接内联run指令可选若数据集不同在套件的 load 脚本中追加对应加载项可选手工创建结果 CSV供校验阶段比对。添加全新的基准套件在benchmarks/sql_benchmarks/下创建以套件命名的新目录在目录内为每个单独基准创建name.benchmark按上文指令表填充基准内容参考其他套件的写法保持风格统一无需更新任何 Rust 文件即可运行新套件——这正是该框架刻意设计的免重编译特性。再配合bench.sh在data命令的 case 中增加data_name()分支如需生成数据、在run命令的 case 中增加run_name()分支通过env注入BENCH_NAME等变量后调用cargo bench --bench sql并在 usage 帮助文本中登记新基准名称。小结为 DataFusion 设计与添加基准测试核心可以归结为四句话用 SQL 作为最高层接口、让被测算子之外的开销尽量廉价识别并变化关键工作负载轴、用注释标注每条查询的轴决策通过bench.sh data/run完成数据准备与执行保证每条查询数秒级的实际运行时间最后利用.benchmark指令、.suite元数据与模板机制做到新增查询/套件零 Rust 代码改动。遵循这套规范既能让基准更易维护、更贴近端到端真实收益也让社区在对比不同优化方案时有可信的度量基础。延伸阅读完整的框架文档与全部指令定义见 benchmarks/sql_benchmarks/README.md调度脚本逻辑见 benchmarks/bench.sh官方设计规范原文见 .ai/skills/add-benchmarks/SKILL.md。赞分享大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载相关推荐Apache DataFusion 基准测试实战指南bench.sh、dfbench 与 SQL 基准套件全解析Apache DataFusion 基准测试实战指南bench.sh、dfbench 与 SQL 基准套件全解析 Apache DataFusion 在 be大数据数据分析后端使用 Jaeger 与 Criterion 运行 Proof of SQL 基准测试sxt-proof-of-sql 完整实战指南使用 Jaeger 与 Criterion 运行 Proof of SQL 基准测试sxt proof of sql 完整实战指南 本指南以 crates/p区块链密码学数据库后端RisingWave 批处理执行器微基准测试指南基于 Criterion 的基准编写与运行实践RisingWave 批处理执行器微基准测试指南基于 Criterion 的基准编写与运行实践 本文以 RisingWave 仓库中 src/batch/ex数据库流处理后端数据工程上一篇TiKV 协处理器插件示例编写指南从 dylib 构建到插件注册下一篇Easy Vibe Stage 1 完整项目实战让你的 AI 产品从原型走向可交付作品创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Apache DataFusion 基准测试设计指南：从 SQL 用例到 Criterion 微基准的完整实践
大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载这篇技术指南围绕 Apache DataFusion 官方基准测试设计规范.ai/skills/add-benchmarks/SKILL.md展开系统讲解在为 DataFusion 设计或新增 benchmark 时必须遵循的两大设计原则、SQL 基准测试的三条集成准则并结合仓库内的 SQL benchmark 框架benchmarks/sql_benchmarks/README.md与bench.sh脚本给出可复制的实战步骤。读完本文你将掌握如何用 SQL 优先思路设计面向特定算子的基准测试、如何挑选关键工作负载轴输入规模、过滤选择性等并标注查询、如何将新查询/新套件无缝接入 DataFusion 官方 benchmark 流程以及底层.benchmark指令、.suite元数据与环境变量的工作机制。为什么要有一套基准测试设计规范DataFusion 是一个数据量庞大的 SQL 查询引擎其优化器与执行算子join、aggregation、window、sort 等的改动极其频繁。如果没有统一的基准测试规范社区贡献的 benchmark 很容易出现两种问题一是测了内部工具函数而不是用户真正触发的执行路径导致优化方向与实际端到端收益脱节二是测试负载设计不合理无法反映真实工作负载的变化规律使比较结果失去参考价值。因此仓库在.ai/skills/add-benchmarks/SKILL.md中沉淀了两条核心设计原则与三条 SQL 基准测试集成准则下面逐一展开。设计原则一尽可能使用最高层接口SQL 优先第一条原则是Use the highest-level interface优先使用 SQL 这种最高层接口同时让被测算子之外的其余工作在基准测试中尽量廉价。具体来说测函数的求值路径而不是孤立地测内部工具函数。例如要评估某个表达式的优化收益应当通过一条真实 SQL 查询触发它的求值路径而不是在 Rust 里直接调用内部工具函数做微基准。从端到端运行时评估优化收益。SQL 级别的基准更容易维护也能直接回答这项优化到底让整个查询快了多久。避免把时间花在只占总运行时很小一部分的代码上。如果某个优化点对应的代码只占整体运行时的 5%即使优化 50% 也毫无意义——高层的 SQL 基准能帮你快速识别这类无效优化。SQL 还是 Rust 微基准的抉择标准规范给出了一个非常实用的判断流程——先尝试用 SQL 实现该 benchmark如果确实还是 Rust 微基准更合适再使用 Criterion。这也与仓库中两套并行的基准体系对应SQL 基准位于benchmarks/sql_benchmarks/由.benchmark文本文件驱动无需重新编译引擎即可增删查询Rust 微基准位于各 crate 的benches/目录如datafusion/core/benches/、datafusion/physical-expr/benches/使用 Criterion 统计。源码佐证nlj 套件如何践行SQL 优先以嵌套循环连接Nested-Loop Join套件benchmarks/sql_benchmarks/nlj/为例其q01.benchmark文件benchmarks/sql_benchmarks/nlj/benchmarks/q01.benchmark完整展示了 SQL 优先的写法name Q01 group nlj expect_plan NestedLoopJoinExec run -- Q1: INNER 10K x 10K | LOW 0.1% SELECT * FROM range(10000) AS t1 JOIN range(10000) AS t2 ON (t1.value t2.value) % 1000 0;这里有两个值得注意的细节数据源用range()而非 Parquet 扫描range()是纯内存生成序列扫描开销可忽略从而让测量的热点集中在 NestedLoopJoinExec 本身expect_plan NestedLoopJoinExec指令在基准运行前检查物理计划中确实包含NestedLoopJoinExec防止优化器把计划改写成哈希连接而测错了算子。设计原则二变化关键工作负载轴Vary the key workload axes第二条原则要求基准测试覆盖关键工作负载轴key axes的变化。规范以 join 基准为例给出最常见的两个轴两侧的输入规模input sizejoin 过滤选择性join-filter selectivity。选定轴之后选择能代表真实使用场景的典型组合即可不必做全组合full combinatorial coverage覆盖。添加基准查询时只需在每条查询的 SQL 注释里标注每个轴对应的决策。规范给出的示例-- Q1: Small left input, large right input; 0.1% of pairs match. SELECT * FROM generate_series(1, 100) AS l JOIN generate_series(1, 100000) AS r ON (l.value r.value) % 1000 0; -- Q2: Medium inputs on both sides; no filter. SELECT * FROM generate_series(1, 1000) AS l CROSS JOIN generate_series(1, 1000) AS r;从仓库现有套件可以看到这种思想的落地nlj套件的 17 条查询覆盖了INNER 10K x 10K | LOW 0.1%、不同输入规模与匹配比例的组合可在benchmarks/sql_benchmarks/nlj/benchmarks/下逐一查看null_aware_join套件则按 NULL 比例、相关/非相关维度拆分为 Q01-Q08 等用例详见benchmarks/sql_benchmarks/README.md中的套件说明表。SQL 基准测试的三条集成准则对于新增的 SQL benchmark规范提出了三条必须遵守的实践准则下面逐一结合仓库源码展开。准则一让其他算子保持廉价Keep other operators cheap当一条 SQL 基准瞄准某个特定算子时其他算子所做的工作要尽量轻量。规范明确推荐使用generate_series()之类的数据源而不是 Parquet 扫描否则扫描开销会主导测量结果掩盖目标算子的真实表现。可参考nlj套件的实现——它的数据全部来自range()/generate_series()因此在bench.sh中对应注释为nlj uses range() function, no data generation needed。准则二集成到顶层基准脚本 bench.sh新基准必须能通过bench.sh完成数据准备与运行。规范给出的标准操作流程从benchmarks目录执行# Generate any required dataset. ./bench.sh data new_bench # Run the benchmark. ./bench.sh run new_benchbench.sh是 DataFusion 开发者使用的总调度脚本支持data生成/下载数据、run运行指定基准、compare/compare_detail比较不同分支的基准结果三类命令。以run_tpch为例benchmarks/bench.sh中定义它通过env注入BENCH_NAME、BENCH_SIZE、DATA_DIR、TPCH_FILE_TYPE、SIMULATE_LATENCY等环境变量后调用cargo bench --bench sqldebug_run env BENCH_NAMEtpch \ BENCH_RESULTS_FILE$(sql_results_file tpch_sf${SCALE_FACTOR}_${FORMAT}) \ BENCH_SIZE${SCALE_FACTOR} \ DATA_DIR${DATA_DIR} \ PREFER_HASH_JOIN${PREFER_HASH_JOIN} \ TPCH_FILE_TYPE${FORMAT} \ SIMULATE_LATENCY${SIMULATE_LATENCY} \ ${QUERY:BENCH_QUERY${QUERY}} \ bash -c $SQL_CARGO_COMMAND从脚本结构可以看出每个基准对应一个run_name()函数数据生成则对应data_name()函数data与run两个命令通过case分发到对应函数。新增基准时在bench.sh中补充对应的 data/run 分支即可完成集成。准则三保持查询运行时间切合实际Keep query runtimes practical规范要求将负载调到每条查询每次执行大约数秒的量级。这样既能降低计时噪声的相对影响又不会让整个套件跑起来过于耗时。这与仓库中各套件的负载设计一致——例如null_aware_join的非相关查询使用NAJ_LARGE_ROWS默认1000000行相关查询使用NAJ_ROWS默认10000行都是为控制每次执行耗时而在真实性与可运行性之间做出的权衡。深入理解 SQL benchmark 框架的工作机制为了让新增基准符合准则二你需要理解benchmarks/sql_benchmarks/README.md所描述的框架机制。SQL benchmark 框架刻意保持简单基准由.benchmark文本文件和 SQL 查询驱动新增或修改基准无需触碰引擎核心代码、也无需重新编译。benchmark_runner 的运行入口首选运行方式是benchmark_runner二进制它从sql_benchmarks目录发现套件并把套件专属选项与通用选项一并暴露为命令行参数。套件名必须位于所有选项之前# 列出所有可用套件 cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- --list # 查看 tpch 套件的帮助含套件专属选项 cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --help # 运行 tpch 第 15 号查询输出 CSV cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --query 15 --format csv # dry-run仅校验命令并打印解析结果JSON cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- clickbench --partitioning partitioned --dry-run # 结果持久化 / 校验 cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --query 1 --result-mode persist cargo run -p datafusion-benchmarks --release --bin benchmark_runner -- tpch --query 1 --result-mode validate关键点补充--result-mode有三种取值persist保存查询结果到 CSV、validate与已保存结果比对、none默认两者都不做同时兼容BENCH_PERSIST_RESULTS/BENCH_VALIDATE环境变量显式命令行参数优先。--dry-run只打印解析后的套件、过滤器、运行模式、通用选项、套件专属值与路径替换不加载基准、不建会话、不读数据、不执行 SQL。--path/-p可覆盖声明了DATA_DIR路径替换的套件的数据目录未声明该替换的套件会拒绝该选项。取值优先级为命令行 环境变量 套件元数据默认值。套件元数据.suite文件每个可发现的套件都对应一个suite/suite.suiteTOML 元数据文件。以benchmarks/sql_benchmarks/h2o/h2o.suite为例description H2O group-by, join, and window SQL benchmarks query_pattern q{QUERY_ID_PADDED}.benchmark [path_replacements] DATA_DIR ../../data [[options]] name size env H2O_BENCH_SIZE default small values [small, medium, big] help Selects the H2O dataset size. [[options]] name format short f env H2O_FILE_TYPE default csv values [csv, parquet] help Selects the H2O data format.顶层字段字段是否必填说明description是非空描述显示在--list与套件帮助中query_pattern否基准文件名模式必须恰好包含一个{QUERY_ID}或{QUERY_ID_PADDED}占位符默认q{QUERY_ID_PADDED}.benchmarkpath_replacements否替换名到路径的映射相对路径以套件目录为基准解析DATA_DIR启用--path/-poptions否套件专属选项表数组见下examples否commanddescription对追加到套件帮助中每个[[options]]表字段字段是否必填说明name是长选项名不含--仅限小写 ASCII 字母、数字与连字符short否单个 ASCII 字母或数字不含-env是提供选项值所读取的环境变量default是命令行与环境变量均未提供时使用的值values否可接受取值省略则允许任意值包含...表示列出的值 任意其他值否则为封闭列表help是套件帮助中显示的非空文本注意选项名、短名、环境变量键在套件内必须唯一选项的环境变量键不能与path_replacements中的键重复套件选项不能占用 runner 全局选项名help、query、subgroup、iterations、partitions、batch-size、mem-pool-type、memory-limit、sort-spill-reservation-bytes、debug、simulate-latency、criterion、list、output、save-baseline、path、result-mode、dry-run等。.benchmark文件与指令系统每个单独基准由一个name.benchmark文件表示内含一系列指令directives告诉工具如何加载数据、执行初始化、运行断言、运行基准、可选地持久化/校验结果、以及最后的清理。指令一览完整定义见benchmarks/sql_benchmarks/README.md指令作用name基准名称用于 Criterion 显示名同时以BENCH_NAME提供给文件内替换group分组名称用于把多个基准归组subgroup子分组名称用于过滤到某个特定子分组如subgroup windowload初始化阶段执行的 SQL可指向文件也可直接写一条 SQL 语句后必须跟空行initload之后、基准执行之前执行同样支持文件或内联 SQL后必须跟空行run基准执行阶段可含多条语句但一个文件只能有一个run持久化/校验时只用其中最后一条SELECT/WITH语句cleanup全部指令之后执行用于清理如DROP TABLEexpect_plan检查物理计划中包含给定字符串按EXPLAIN渲染形式如expect_plan NestedLoopJoinExec每次基准只检查一次不计入测量区assert在init与run之间执行校验系统状态格式为assert 列数I SQL ----分隔的期望结果制表符或管道分隔result_query校验阶段运行验证不同于run的附加结果格式同assertresult声明期望结果文件管道分隔、带头部的 CSV校验时与run最后一条SELECT/WITH的结果比对template包含另一个基准文件支持KEYvalue参数传递include与template类似但不支持参数echo向 stdout 输出字符串便于调试变量替换benchmark 文件支持两种替换形式——字符串替换带可选默认值${ENV_VAR}与${ENV_VAR:-default}以及基于真值的 if/else 替换${ENV_VAR:-default|true value|false value}其中只有值true大小写不敏感进入 true 分支其他任何值进入 false 分支值缺失时用default选择分支。注释以#或--开头。以 h2o 套件的实际文件为例benchmarks/sql_benchmarks/h2o/benchmarks/groupby/q01.benchmarksubgroup groupby name Q01 group h2o echo Loading ${H2O_BENCH_SIZE:-small} groupby ${H2O_FILE_TYPE:-csv} h2o data load sql_benchmarks/h2o/init/load_groupby_${H2O_BENCH_SIZE:-small}_${H2O_FILE_TYPE:-csv}.sql assert I SELECT COUNT(*) 0 FROM x ---- true run SELECT id1, SUM(v1) AS v1 FROM x GROUP BY id1; result sql_benchmarks/h2o/results/groupby/${H2O_BENCH_SIZE:-small}/q01.csv这个文件完整展示了subgroup、name、group、echo、load、assert、run、result指令的组合用法以及${VAR:-default}默认值替换的实战样式。模板机制大量基准通过模板消除.benchmark文件间的重复。仓库中实际存在的模板包括benchmarks/sql_benchmarks/h2o/window_sorted.benchmark.template、benchmarks/sql_benchmarks/parquet_row_filter_skip/parquet_row_filter_skip.benchmark.template、benchmarks/sql_benchmarks/predicate_eval/predicate_eval.benchmark.template、benchmarks/sql_benchmarks/projection_subquery/projection_subquery.benchmark.template与benchmarks/sql_benchmarks/spill_views/spill_views.benchmark.template。模板内使用template指令引用并可用QUERY_NUMBER1、QUERY_NUMBER_PADDED01这样的KEYvalue行传参。常用环境变量速查SQL 基准工具支持以下通用环境变量部分环境变量说明BENCH_NAME要运行的套件名对应sql_benchmarks下的目录名如imdbBENCH_SUBGROUP套件内的子分组如 h2o 的windowBENCH_QUERY指定运行的查询编号BENCH_PERSIST_RESULTStrue/false是否将结果持久化为 CSVBENCH_VALIDATEtrue/false是否将结果与已保存结果比对两者均为 true 时以 persist 为准DATA_DIRSQL 基准加载数据的根目录默认benchmarks/dataSIMULATE_LATENCY模拟对象存储延迟20-200ms用于模拟 S3 等远程存储MEM_POOL_TYPE内存池类型fair或greedyMEMORY_LIMIT内存上限如100M、1.5G未指定则按预定义内存限制运行否则不限内存套件专属变量示例BENCH_SIZETPC-H/TPC-DS 的 scale factor默认1、TPCH_FILE_TYPEcsv/parquet/mem默认parquet、H2O_FILE_TYPEcsv/parquet默认csv、H2O_BENCH_SIZEsmall/medium/big默认small、PRED_ROWSpredicate_eval 与 parquet_row_filter_skip 的合成数据行数、RG_SIZEParquet 行组大小、PSQ_ROWS、SPILL_VIEWS_LIMIT_REPEATED/SPILL_VIEWS_LIMIT_DISTINCT等。完整列表见benchmarks/sql_benchmarks/README.md的 Benchmark configuration 一节。实战如何扩展或新增基准套件在已有套件中新增查询按规范与 README 的步骤在对应套件的queries/文件夹中新建qXX.sql如benchmarks/sql_benchmarks/h2o/init/对应目录结构新建qXX.benchmark引用适当的模板clickbench.benchmark.template、h2o.benchmark.template等并传入QUERY_NUMBER/QUERY_NUMBER_PADDED或直接内联run指令可选若数据集不同在套件的 load 脚本中追加对应加载项可选手工创建结果 CSV供校验阶段比对。添加全新的基准套件在benchmarks/sql_benchmarks/下创建以套件命名的新目录在目录内为每个单独基准创建name.benchmark按上文指令表填充基准内容参考其他套件的写法保持风格统一无需更新任何 Rust 文件即可运行新套件——这正是该框架刻意设计的免重编译特性。再配合bench.sh在data命令的 case 中增加data_name()分支如需生成数据、在run命令的 case 中增加run_name()分支通过env注入BENCH_NAME等变量后调用cargo bench --bench sql并在 usage 帮助文本中登记新基准名称。小结为 DataFusion 设计与添加基准测试核心可以归结为四句话用 SQL 作为最高层接口、让被测算子之外的开销尽量廉价识别并变化关键工作负载轴、用注释标注每条查询的轴决策通过bench.sh data/run完成数据准备与执行保证每条查询数秒级的实际运行时间最后利用.benchmark指令、.suite元数据与模板机制做到新增查询/套件零 Rust 代码改动。遵循这套规范既能让基准更易维护、更贴近端到端真实收益也让社区在对比不同优化方案时有可信的度量基础。延伸阅读完整的框架文档与全部指令定义见 benchmarks/sql_benchmarks/README.md调度脚本逻辑见 benchmarks/bench.sh官方设计规范原文见 .ai/skills/add-benchmarks/SKILL.md。赞分享大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载相关推荐Apache DataFusion 基准测试实战指南bench.sh、dfbench 与 SQL 基准套件全解析Apache DataFusion 基准测试实战指南bench.sh、dfbench 与 SQL 基准套件全解析 Apache DataFusion 在 be大数据数据分析后端使用 Jaeger 与 Criterion 运行 Proof of SQL 基准测试sxt-proof-of-sql 完整实战指南使用 Jaeger 与 Criterion 运行 Proof of SQL 基准测试sxt proof of sql 完整实战指南 本指南以 crates/p区块链密码学数据库后端RisingWave 批处理执行器微基准测试指南基于 Criterion 的基准编写与运行实践RisingWave 批处理执行器微基准测试指南基于 Criterion 的基准编写与运行实践 本文以 RisingWave 仓库中 src/batch/ex数据库流处理后端数据工程上一篇TiKV 协处理器插件示例编写指南从 dylib 构建到插件注册下一篇Easy Vibe Stage 1 完整项目实战让你的 AI 产品从原型走向可交付作品创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考