address docu review comments

Author: B Vadlamani

benchmarks/src/hj.rs

@@ -302,8 +302,17 @@ const HASH_QUERIES: &[HashJoinQuery] = &[
         probe_size: "60M",
     },
     // RightSemi Join benchmarks with Int32 keys
-    // Matching ratio: 1:1 (build keys are unique, each probe matches at most 1 build row)
-    // Semi joins can short-circuit after first match, so hit rate affects performance.
+    //
+    // Fanout (average build rows matched per probe row, as measured by running
+    // the equivalent INNER JOIN under `EXPLAIN ANALYZE` and reading the
+    // `HashJoinExec` metrics): 1 for Q16-Q18. Build keys here are primary
+    // keys (`n_nationkey`, `s_suppkey`), so each probe row matches at most
+    // one build row. `prob_hit` controls what fraction of probe rows find
+    // that one match.
+    //
+    // Fanout still matters because semi joins short-circuit after the first
+    // match. Coverage of fanout > 1 (build-side duplicates) is left for a
+    // follow-up.
     //
     // Q16: RightSemi, Small build (25 rows), 100% Hit rate
     // Build Side: nation (25 rows) | Probe Side: customer (1.5M rows)
@@ -345,8 +354,17 @@ const HASH_QUERIES: &[HashJoinQuery] = &[
         probe_size: "60M_RightSemi",
     },
     // RightAnti Join benchmarks with Int32 keys
-    // Matching ratio: 1:1 (build keys are unique, each probe matches at most 1 build row)
-    // Anti joins can short-circuit after first match, so hit rate affects performance.
+    //
+    // Fanout (average build rows matched per probe row, as measured by running
+    // the equivalent INNER JOIN under `EXPLAIN ANALYZE` and reading the
+    // `HashJoinExec` metrics): 1 for Q19-Q21. Build keys here are primary
+    // keys (`n_nationkey`, `s_suppkey`), so each probe row matches at most
+    // one build row. `prob_hit` controls what fraction of probe rows find
+    // that one match (and are therefore filtered *out* by anti).
+    //
+    // Fanout still matters because anti joins short-circuit after the first
+    // match. Coverage of fanout > 1 (build-side duplicates) is left for a
+    // follow-up.
     //
     // Q19: RightAnti, Small build (25 rows), 100% Hit rate (no output)
     // Build Side: nation (25 rows) | Probe Side: customer (1.5M rows)

datafusion/physical-plan/benches/hash_join_semi_anti.rs

@@ -19,10 +19,20 @@
 //!
 //! ## Key Benchmark Axes
 //!
-//! - **Density**: The ratio of distinct key values to the key range span.
-//!   For example, keys [0, 2, 4, 6, 8] have density = 5/9 ≈ 55% (5 distinct values
-//!   in a range of 9). Density affects hash table memory layout and cache behavior.
-//!   Lower density means keys are more spread out, leading to more cache misses.
+//! - **Density**: How tightly distinct keys pack into their numeric range.
+//!   `density = num_distinct_keys / (max_key - min_key + 1)`.
+//!   Examples for 5 distinct keys:
+//!     - `[0, 1, 2, 3, 4]`      → 5/5  = 100% (fully packed)
+//!     - `[0, 2, 4, 6, 8]`      → 5/9  ≈  55% (every 2nd slot)
+//!     - `[0, 10, 20, 30, 40]`  → 5/41 ≈  12% (every 10th slot)
+//!
+//!   Why it matters for this workload: future potential semi/anti-join
+//!   fast paths could exploit densely packed build keys to outperform the
+//!   general hash-table path, which is largely insensitive to density.
+//!   Varying density across benchmarks helps surface those potential gains
+//!   under different key distributions. Density describes only the
+//!   build-side key layout; the per-probe match count is tracked
+//!   separately as fanout.
 //!
 //! - **Hit Rate**: The percentage of probe rows that find a match in the build side.
 //!   This controls how often the join produces output rows.