(datafusion) branch main updated: docs: Add SKILL.md for designing benchmark (#25285)

[gi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git


The following commit(s) were added to refs/heads/main by this push:
     new 56361282fc docs: Add SKILL.md for designing benchmark (#25285)
56361282fc is described below

commit 56361282fcf19c473d2ff23802b796e72a6febd9
Author: Yongting You <20...@gmail.com>
AuthorDate: Thu Sep 17 12:47:52 2026 +0000

    docs: Add SKILL.md for designing benchmark (#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.
    -->
---
 .ai/skills/add-benchmarks/SKILL.md | 84 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/.ai/skills/add-benchmarks/SKILL.md b/.ai/skills/add-benchmarks/SKILL.md
new file mode 100644
index 0000000000..d25ec6a057
--- /dev/null
+++ b/.ai/skills/add-benchmarks/SKILL.md
@@ -0,0 +1,84 @@
+---
+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
+
+### Use the highest-level interface
+
+Use the highest-level interface possible, preferably SQL, while keeping the work
+around the operator being measured as cheap as possible. 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.
+
+Practical criteria for choosing SQL or Rust benchmarks: Try implementing the benchmark in SQL first. If a Rust microbenchmark still seems like a better fit, use Criterion.
+
+### 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. **Keep other operators cheap.**
+
+   When a SQL benchmark 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.
\ No newline at end of file


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org