You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@datafusion.apache.org by "2010YOUY01 (via GitHub)" <gi...@apache.org> on 2026/09/14 03:30:14 UTC
[PR] docs: Add SKILL.md for designing benchmark [datafusion]
2010YOUY01 opened a new pull request, #25285:
URL: https://github.com/apache/datafusion/pull/25285
## Which issue does this PR close?
<!--
We generally require a GitHub issue to be filed for all bug fixes and enhancements and this helps us generate change logs for our releases. You can link an issue to this PR using the GitHub syntax. For example `Closes #123` indicates that this PR will close issue #123.
-->
- Closes #.
## Rationale for this change
<!--
Why are you proposing this change? If this is already explained clearly in the issue then this section is not needed.
Explaining clearly why changes are proposed helps reviewers understand your changes and offer better suggestions for fixes.
Please explain the problem you are trying to solve in terms of the user-visible
behavior, rather than the implementation.
For example, "The code in `foo.rs` doesn't handle nulls" is a symptom of the
implementation. "COUNT(DISTINCT) returns wrong results when the column contains
nulls" is the user-visible problem.
-->
Here is something I had in mind when designing or reviewing benchmarks. Summarize it as a doc for future reference.
## What changes are included in this PR?
<!--
There is no need to duplicate the description in the issue here, but it is sometimes worth providing a summary of the individual changes in this PR.
-->
Add a skill for designing new benchmarks.
## What is the testing strategy for this PR?
<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code
Briefly describe how this PR is tested, and point to the specific tests you added. For example: 'This new feature is covered by the `sqllogictest` cases added in `foo.slt`'.
If this PR does not add tests, explain why. For example, if the change is already covered by existing tests, please mention it.
You should also check the `codecov` bot reply on this PR to confirm the changed code is exercised.
-->
## Are there any user-facing changes?
<!--
If there are user-facing changes then we may require documentation to be updated before approving the PR.
If there are any breaking changes to public APIs, please add the `api change` label.
-->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #25285:
URL: https://github.com/apache/datafusion/pull/25285#discussion_r4002009418
##########
.ai/skills/add-benchmarks/SKILL.md:
##########
@@ -0,0 +1,86 @@
+---
+name: add-benchmarks
+description: Guidelines for designing or extending DataFusion benchmarks.
+---
+
+# Benchmark Design
+
+Follow these guidelines when designing or adding a new benchmark.
+
+## Design principles
+
+### Benchmark at a higher level
+
+Try to move benchmarks to a higher level when possible. For example, prefer SQL
+benchmarks even for microbenchmarks of individual operators. When benchmarking a
+function, exercise its evaluation path instead of benchmarking internal utility
+functions in isolation.
+
+This makes benchmarks easier to maintain and helps assess how much an optimization
+matters to end-to-end runtime. It also helps avoid spending time optimizing code
+that accounts for only a small fraction of the total runtime.
+
+### Vary the key workload axes
+
+First identify the key axes to vary. For example, for a join benchmark:
+
+- Input size on each side.
+- Join-filter selectivity.
+- ...
+
+Then choose benchmark cases that exercise representative variations. Full
+combinatorial coverage is unnecessary; focus on typical workloads that reflect
+real use cases.
+
+When adding benchmark queries, simply tag each query with the decision made
+for every axis. For example, for a join benchmark with input sizes/filter selectivity
+to tune:
+
+```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;
+```
+
+## SQL benchmarks
+
+For implementation details, see the
+[SQL benchmark README](../../../benchmarks/sql_benchmarks/README.md).
+
+1. **Isolate the operator being measured in microbenchmarks.**
+
+ When a microbenchmark targets a specific operator, keep the work done by
+ other operators as lightweight as possible. For example, use a data source
+ such as `generate_series()` instead of a Parquet scan so scan overhead does
+ not dominate the measurement. See the [`nlj` benchmark](../../../benchmarks/sql_benchmarks/nlj/) for examples.
+
+2. **Integrate with the top-level benchmark script.**
+
+ Ensure the benchmark can be prepared and run through `bench.sh`:
+
+ ```bash
+ # Run from the benchmarks directory.
+
+ # Generate any required dataset.
+ ./bench.sh data new_bench
+
+ # Run the benchmark.
+ ./bench.sh run new_bench
+ ```
+
+3. **Keep query runtimes practical.**
+
+ Tune the workload so each query takes roughly a few seconds per execution.
+ This helps reduce the relative impact of timing noise while keeping the
+ suite practical to run.
+
+## Rust microbenchmarks
+
+TODO
Review Comment:
I don't have ideas specific to Rust microbenchmarks; maybe others do and we can add them later.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "jayzhan211 (via GitHub)" <gi...@apache.org>.
jayzhan211 commented on code in PR #25285:
URL: https://github.com/apache/datafusion/pull/25285#discussion_r4027401678
##########
.ai/skills/add-benchmarks/SKILL.md:
##########
@@ -0,0 +1,83 @@
+---
+name: add-benchmarks
+description: Guidelines for designing or extending DataFusion benchmarks.
+---
+
+# Benchmark Design
+
+Follow these guidelines when designing or adding a new benchmark.
+
+## Design principles
+
+### Benchmark at a higher level
+
+Try to move benchmarks to a higher level when possible. For example, prefer SQL
+benchmarks even for microbenchmarks of individual operators. When benchmarking a
+function, exercise its evaluation path instead of benchmarking internal utility
+functions in isolation.
+
+This makes benchmarks easier to maintain and helps assess how much an optimization
+matters to end-to-end runtime. It also helps avoid spending time optimizing code
+that accounts for only a small fraction of the total runtime.
+
+### Vary the key workload axes
+
+First identify the key axes to vary. For example, for a join benchmark:
+
+- Input size on each side.
+- Join-filter selectivity.
+- ...
+
+Then choose benchmark cases that exercise representative variations. Full
+combinatorial coverage is unnecessary; focus on typical workloads that reflect
+real use cases.
+
+When adding benchmark queries, simply tag each query with the decision made
+for every axis. For example, for a join benchmark with input sizes/filter selectivity
+to tune:
+
+```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;
+```
+
+## SQL benchmarks
+
+For implementation details, see the
+[SQL benchmark README](../../../benchmarks/sql_benchmarks/README.md).
+
+1. **Isolate the operator being measured in microbenchmarks.**
+
+ When a microbenchmark targets a specific operator, keep the work done by
Review Comment:
**Say when criterion benches are still the right tool.** The repo has about 180 criterion bench files. "Prefer SQL benchmarks even for microbenchmarks" with no exceptions will clash with reviews of PRs that touch hashing, row conversion or array kernels, where SQL setup would drown out the code being measured. One sentence would cover it, e.g.: "Use a criterion bench only when the code has no SQL-reachable path, or when per-row costs are too small to see through a query.
##########
.ai/skills/add-benchmarks/SKILL.md:
##########
@@ -0,0 +1,83 @@
+---
+name: add-benchmarks
+description: Guidelines for designing or extending DataFusion benchmarks.
+---
+
+# Benchmark Design
+
+Follow these guidelines when designing or adding a new benchmark.
+
+## Design principles
+
+### Benchmark at a higher level
+
+Try to move benchmarks to a higher level when possible. For example, prefer SQL
+benchmarks even for microbenchmarks of individual operators. When benchmarking a
+function, exercise its evaluation path instead of benchmarking internal utility
+functions in isolation.
+
+This makes benchmarks easier to maintain and helps assess how much an optimization
+matters to end-to-end runtime. It also helps avoid spending time optimizing code
+that accounts for only a small fraction of the total runtime.
+
+### Vary the key workload axes
+
+First identify the key axes to vary. For example, for a join benchmark:
+
+- Input size on each side.
+- Join-filter selectivity.
+- ...
+
+Then choose benchmark cases that exercise representative variations. Full
+combinatorial coverage is unnecessary; focus on typical workloads that reflect
+real use cases.
+
+When adding benchmark queries, simply tag each query with the decision made
+for every axis. For example, for a join benchmark with input sizes/filter selectivity
+to tune:
+
+```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;
+```
+
+## SQL benchmarks
+
+For implementation details, see the
+[SQL benchmark README](../../../benchmarks/sql_benchmarks/README.md).
+
+1. **Isolate the operator being measured in microbenchmarks.**
+
+ When a microbenchmark targets a specific operator, keep the work done by
Review Comment:
**Clear up the tension between the two main rules.** "Benchmark at a higher level" and "isolate the operator" can read as opposite advice. Suggested wording: go in through the highest-level interface (SQL), but keep everything around the operator as cheap as possible.
##########
.ai/skills/add-benchmarks/SKILL.md:
##########
@@ -0,0 +1,83 @@
+---
+name: add-benchmarks
+description: Guidelines for designing or extending DataFusion benchmarks.
+---
+
+# Benchmark Design
+
+Follow these guidelines when designing or adding a new benchmark.
+
+## Design principles
+
+### Benchmark at a higher level
+
+Try to move benchmarks to a higher level when possible. For example, prefer SQL
+benchmarks even for microbenchmarks of individual operators. When benchmarking a
+function, exercise its evaluation path instead of benchmarking internal utility
+functions in isolation.
+
+This makes benchmarks easier to maintain and helps assess how much an optimization
+matters to end-to-end runtime. It also helps avoid spending time optimizing code
+that accounts for only a small fraction of the total runtime.
+
+### Vary the key workload axes
+
+First identify the key axes to vary. For example, for a join benchmark:
+
+- Input size on each side.
+- Join-filter selectivity.
+- ...
+
+Then choose benchmark cases that exercise representative variations. Full
+combinatorial coverage is unnecessary; focus on typical workloads that reflect
+real use cases.
+
+When adding benchmark queries, simply tag each query with the decision made
+for every axis. For example, for a join benchmark with input sizes/filter selectivity
+to tune:
+
+```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;
+```
+
+## SQL benchmarks
+
+For implementation details, see the
+[SQL benchmark README](../../../benchmarks/sql_benchmarks/README.md).
+
+1. **Isolate the operator being measured in microbenchmarks.**
+
+ When a microbenchmark targets a specific operator, keep the work done by
Review Comment:
**Mention expect_plan.** Every nlj query has expect_plan NestedLoopJoinExec. It matters a lot: if an optimizer change turns the NLJ into a hash join, the benchmark keeps "passing" while measuring the wrong operator. I'd make it its own rule: assert the plan shape you mean to measure.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #25285:
URL: https://github.com/apache/datafusion/pull/25285#issuecomment-5658742043
## [Codecov](https://app.codecov.io/gh/apache/datafusion/pull/25285?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
:white_check_mark: All modified and coverable lines are covered by tests.
:white_check_mark: Project coverage is 81.90%. Comparing base ([`38d58ed`](https://app.codecov.io/gh/apache/datafusion/commit/38d58ed09db21afe0bc224607457d86d4ed62e03?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`1a2f565`](https://app.codecov.io/gh/apache/datafusion/commit/1a2f565c467b0fcf3228e26f8f215ce2746a929b?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
<details><summary>Additional details and impacted files</summary>
```diff
@@ Coverage Diff @@
## main #25285 +/- ##
==========================================
- Coverage 81.90% 81.90% -0.01%
==========================================
Files 1134 1134
Lines 425217 425217
Branches 425217 425217
==========================================
- Hits 348289 348277 -12
- Misses 56288 56296 +8
- Partials 20640 20644 +4
```
</details>
[:umbrella: View full report in Codecov by Harness](https://app.codecov.io/gh/apache/datafusion/pull/25285?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
<details><summary> :rocket: New features to boost your workflow: </summary>
- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
- :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
</details>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 merged PR #25285:
URL: https://github.com/apache/datafusion/pull/25285
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on PR #25285:
URL: https://github.com/apache/datafusion/pull/25285#issuecomment-5714601252
@jayzhan211 @Xuanwo Thank you for the review.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #25285:
URL: https://github.com/apache/datafusion/pull/25285#discussion_r4010828745
##########
.ai/skills/add-benchmarks/SKILL.md:
##########
@@ -0,0 +1,86 @@
+---
+name: add-benchmarks
+description: Guidelines for designing or extending DataFusion benchmarks.
+---
+
+# Benchmark Design
+
+Follow these guidelines when designing or adding a new benchmark.
+
+## Design principles
+
+### Benchmark at a higher level
+
+Try to move benchmarks to a higher level when possible. For example, prefer SQL
+benchmarks even for microbenchmarks of individual operators. When benchmarking a
+function, exercise its evaluation path instead of benchmarking internal utility
+functions in isolation.
+
+This makes benchmarks easier to maintain and helps assess how much an optimization
+matters to end-to-end runtime. It also helps avoid spending time optimizing code
+that accounts for only a small fraction of the total runtime.
+
+### Vary the key workload axes
+
+First identify the key axes to vary. For example, for a join benchmark:
+
+- Input size on each side.
+- Join-filter selectivity.
+- ...
+
+Then choose benchmark cases that exercise representative variations. Full
+combinatorial coverage is unnecessary; focus on typical workloads that reflect
+real use cases.
+
+When adding benchmark queries, simply tag each query with the decision made
+for every axis. For example, for a join benchmark with input sizes/filter selectivity
+to tune:
+
+```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;
+```
+
+## SQL benchmarks
+
+For implementation details, see the
+[SQL benchmark README](../../../benchmarks/sql_benchmarks/README.md).
+
+1. **Isolate the operator being measured in microbenchmarks.**
+
+ When a microbenchmark targets a specific operator, keep the work done by
+ other operators as lightweight as possible. For example, use a data source
+ such as `generate_series()` instead of a Parquet scan so scan overhead does
+ not dominate the measurement. See the [`nlj` benchmark](../../../benchmarks/sql_benchmarks/nlj/) for examples.
+
+2. **Integrate with the top-level benchmark script.**
+
+ Ensure the benchmark can be prepared and run through `bench.sh`:
+
+ ```bash
+ # Run from the benchmarks directory.
+
+ # Generate any required dataset.
+ ./bench.sh data new_bench
+
+ # Run the benchmark.
+ ./bench.sh run new_bench
+ ```
+
+3. **Keep query runtimes practical.**
+
+ Tune the workload so each query takes roughly a few seconds per execution.
+ This helps reduce the relative impact of timing noise while keeping the
+ suite practical to run.
+
+## Rust microbenchmarks
+
+TODO
Review Comment:
I agree. Removed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #25285:
URL: https://github.com/apache/datafusion/pull/25285#discussion_r4010825651
##########
.ai/skills/add-benchmarks/SKILL.md:
##########
@@ -0,0 +1,86 @@
+---
+name: add-benchmarks
+description: Guidelines for designing or extending DataFusion benchmarks.
+---
+
+# Benchmark Design
+
+Follow these guidelines when designing or adding a new benchmark.
+
+## Design principles
+
+### Benchmark at a higher level
+
+Try to move benchmarks to a higher level when possible. For example, prefer SQL
+benchmarks even for microbenchmarks of individual operators. When benchmarking a
+function, exercise its evaluation path instead of benchmarking internal utility
+functions in isolation.
+
+This makes benchmarks easier to maintain and helps assess how much an optimization
+matters to end-to-end runtime. It also helps avoid spending time optimizing code
+that accounts for only a small fraction of the total runtime.
+
+### Vary the key workload axes
+
+First identify the key axes to vary. For example, for a join benchmark:
+
+- Input size on each side.
+- Join-filter selectivity.
+- ...
+
+Then choose benchmark cases that exercise representative variations. Full
+combinatorial coverage is unnecessary; focus on typical workloads that reflect
+real use cases.
+
+When adding benchmark queries, simply tag each query with the decision made
+for every axis. For example, for a join benchmark with input sizes/filter selectivity
+to tune:
+
+```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;
+```
+
+## SQL benchmarks
+
+For implementation details, see the
+[SQL benchmark README](../../../benchmarks/sql_benchmarks/README.md).
+
+1. **Isolate the operator being measured in microbenchmarks.**
+
+ When a microbenchmark targets a specific operator, keep the work done by
+ other operators as lightweight as possible. For example, use a data source
+ such as `generate_series()` instead of a Parquet scan so scan overhead does
+ not dominate the measurement. See the [`nlj` benchmark](../../../benchmarks/sql_benchmarks/nlj/) for examples.
+
+2. **Integrate with the top-level benchmark script.**
+
+ Ensure the benchmark can be prepared and run through `bench.sh`:
+
+ ```bash
+ # Run from the benchmarks directory.
+
+ # Generate any required dataset.
+ ./bench.sh data new_bench
+
+ # Run the benchmark.
+ ./bench.sh run new_bench
+ ```
+
+3. **Keep query runtimes practical.**
+
+ Tune the workload so each query takes roughly a few seconds per execution.
+ This helps reduce the relative impact of timing noise while keeping the
+ suite practical to run.
+
+## Rust microbenchmarks
+
+TODO
Review Comment:
```suggestion
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: Add SKILL.md for designing benchmark [datafusion]
Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #25285:
URL: https://github.com/apache/datafusion/pull/25285#discussion_r4003127258
##########
.ai/skills/add-benchmarks/SKILL.md:
##########
@@ -0,0 +1,86 @@
+---
+name: add-benchmarks
+description: Guidelines for designing or extending DataFusion benchmarks.
+---
+
+# Benchmark Design
+
+Follow these guidelines when designing or adding a new benchmark.
+
+## Design principles
+
+### Benchmark at a higher level
+
+Try to move benchmarks to a higher level when possible. For example, prefer SQL
+benchmarks even for microbenchmarks of individual operators. When benchmarking a
+function, exercise its evaluation path instead of benchmarking internal utility
+functions in isolation.
+
+This makes benchmarks easier to maintain and helps assess how much an optimization
+matters to end-to-end runtime. It also helps avoid spending time optimizing code
+that accounts for only a small fraction of the total runtime.
+
+### Vary the key workload axes
+
+First identify the key axes to vary. For example, for a join benchmark:
+
+- Input size on each side.
+- Join-filter selectivity.
+- ...
+
+Then choose benchmark cases that exercise representative variations. Full
+combinatorial coverage is unnecessary; focus on typical workloads that reflect
+real use cases.
+
+When adding benchmark queries, simply tag each query with the decision made
+for every axis. For example, for a join benchmark with input sizes/filter selectivity
+to tune:
+
+```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;
+```
+
+## SQL benchmarks
+
+For implementation details, see the
+[SQL benchmark README](../../../benchmarks/sql_benchmarks/README.md).
+
+1. **Isolate the operator being measured in microbenchmarks.**
+
+ When a microbenchmark targets a specific operator, keep the work done by
+ other operators as lightweight as possible. For example, use a data source
+ such as `generate_series()` instead of a Parquet scan so scan overhead does
+ not dominate the measurement. See the [`nlj` benchmark](../../../benchmarks/sql_benchmarks/nlj/) for examples.
+
+2. **Integrate with the top-level benchmark script.**
+
+ Ensure the benchmark can be prepared and run through `bench.sh`:
+
+ ```bash
+ # Run from the benchmarks directory.
+
+ # Generate any required dataset.
+ ./bench.sh data new_bench
+
+ # Run the benchmark.
+ ./bench.sh run new_bench
+ ```
+
+3. **Keep query runtimes practical.**
+
+ Tune the workload so each query takes roughly a few seconds per execution.
+ This helps reduce the relative impact of timing noise while keeping the
+ suite practical to run.
+
+## Rust microbenchmarks
+
+TODO
Review Comment:
It is better to remove this section entirely if we do not have the content ready. Otherwise, it may confuse agents.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org