Skip to content

Apache DataFusion SQL Query Engine

chore: Add existence (semi / anti ) benchmarks for hashjoinexec (#21821)

Bhargava Vadlamani4f45193c8ca2
diff --git a/benchmarks/src/hj.rs b/benchmarks/src/hj.rs
index 301fe0d599..8cd1b8b4b7 100644
--- a/benchmarks/src/hj.rs
+++ b/benchmarks/src/hj.rs
@@ -25,8 +25,6 @@ use std::path::PathBuf;
use futures::StreamExt;
-// TODO: Add existence joins
-
/// Run the Hash Join benchmark
///
/// This micro-benchmark focuses on the performance characteristics of Hash Joins.
@@ -303,6 +301,110 @@ const HASH_QUERIES: &[HashJoinQuery] = &[
build_size: "100K_(20%_dups)",
probe_size: "60M",
},
+ // RightSemi Join benchmarks with Int32 keys
+ //
+ // 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)
+ HashJoinQuery {
+ sql: r###"SELECT c.k
+ FROM (SELECT CAST(n_nationkey AS INT) as k FROM nation) n
+ RIGHT SEMI JOIN (SELECT CAST(c_nationkey AS INT) as k FROM customer) c
+ ON n.k = c.k"###,
+ density: 1.0,
+ prob_hit: 1.0,
+ build_size: "25",
+ probe_size: "1.5M_RightSemi",
+ },
+ // Q17: RightSemi, Medium build (100K rows), 100% Hit rate
+ // Build Side: supplier (100K rows) | Probe Side: lineitem (60M rows)
+ HashJoinQuery {
+ sql: r###"SELECT l.k
+ FROM (SELECT CAST(s_suppkey AS INT) as k FROM supplier) s
+ RIGHT SEMI JOIN (SELECT CAST(l_suppkey AS INT) as k FROM lineitem) l
+ ON s.k = l.k"###,
+ density: 1.0,
+ prob_hit: 1.0,
+ build_size: "100K",
+ probe_size: "60M_RightSemi",
+ },
+ // Q18: RightSemi, Medium build (100K rows), 10% Hit rate
+ // Build Side: supplier (100K rows) | Probe Side: lineitem (60M rows)
+ HashJoinQuery {
+ sql: r###"SELECT l.k
+ FROM (SELECT CAST(s_suppkey AS INT) as k FROM supplier) s
+ RIGHT SEMI JOIN (
+ SELECT CAST(CASE WHEN l_suppkey % 10 = 0 THEN l_suppkey ELSE l_suppkey + 1000000 END AS INT) as k
+ FROM lineitem
+ ) l
+ ON s.k = l.k"###,
+ density: 1.0,
+ prob_hit: 0.1,
+ build_size: "100K",
+ probe_size: "60M_RightSemi",
+ },
+ // RightAnti Join benchmarks with Int32 keys
+ //
+ // 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)
+ HashJoinQuery {
+ sql: r###"SELECT c.k
+ FROM (SELECT CAST(n_nationkey AS INT) as k FROM nation) n
+ RIGHT ANTI JOIN (SELECT CAST(c_nationkey AS INT) as k FROM customer) c
+ ON n.k = c.k"###,
+ density: 1.0,
+ prob_hit: 1.0,
+ build_size: "25",
+ probe_size: "1.5M_RightAnti",
+ },
+ // Q20: RightAnti, Medium build (100K rows), 100% Hit rate (no output)
+ // Build Side: supplier (100K rows) | Probe Side: lineitem (60M rows)
+ HashJoinQuery {
+ sql: r###"SELECT l.k
+ FROM (SELECT CAST(s_suppkey AS INT) as k FROM supplier) s
+ RIGHT ANTI JOIN (SELECT CAST(l_suppkey AS INT) as k FROM lineitem) l
+ ON s.k = l.k"###,
+ density: 1.0,
+ prob_hit: 1.0,
+ build_size: "100K",
+ probe_size: "60M_RightAnti",
+ },
+ // Q21: RightAnti, Medium build (100K rows), 10% Hit rate (90% output)
+ // Build Side: supplier (100K rows) | Probe Side: lineitem (60M rows)
+ HashJoinQuery {
+ sql: r###"SELECT l.k
+ FROM (SELECT CAST(s_suppkey AS INT) as k FROM supplier) s
+ RIGHT ANTI JOIN (
+ SELECT CAST(CASE WHEN l_suppkey % 10 = 0 THEN l_suppkey ELSE l_suppkey + 1000000 END AS INT) as k
+ FROM lineitem
+ ) l
+ ON s.k = l.k"###,
+ density: 1.0,
+ prob_hit: 0.1,
+ build_size: "100K",
+ probe_size: "60M_RightAnti",
+ },
];
impl RunOpt {
@@ -323,7 +425,9 @@ impl RunOpt {
None => 1..=HASH_QUERIES.len(),
};
- let config = self.common.config()?;
+ let mut config = self.common.config()?;
+ // Disable join reordering to ensure the optimizer doesn't swap join sides
+ config.options_mut().optimizer.join_reordering = false;
let rt = self.common.build_runtime()?;
let ctx = SessionContext::new_with_config_rt(config, rt);
diff --git a/datafusion/physical-plan/Cargo.toml b/datafusion/physical-plan/Cargo.toml
index c671026277..465fc86cfb 100644
--- a/datafusion/physical-plan/Cargo.toml
+++ b/datafusion/physical-plan/Cargo.toml
@@ -113,6 +113,11 @@ harness = false
name = "aggregate_vectorized"
required-features = ["test_utils"]
+[[bench]]
+harness = false
+name = "hash_join_semi_anti"
+required-features = ["test_utils"]
+
[[bench]]
harness = false
name = "dictionary_group_values"
diff --git a/datafusion/physical-plan/benches/hash_join_semi_anti.rs b/datafusion/physical-plan/benches/hash_join_semi_anti.rs
new file mode 100644
index 0000000000..193230c1d4
--- /dev/null
+++ b/datafusion/physical-plan/benches/hash_join_semi_anti.rs
@@ -0,0 +1,367 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Criterion benchmarks for Hash Join with RightSemi/RightAnti joins with Int32 keys.
+//!
+//! ## Key Benchmark Axes
+//!
+//! - **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.
+//!
+//! Semi/anti joins can short-circuit after finding the first match, so these
+//! benchmarks help evaluate optimization strategies for existence checks.
+
+use std::sync::Arc;
+
+use arrow::array::{Int32Array, RecordBatch, StringArray};
+use arrow::datatypes::{DataType, Field, Schema, SchemaRef};
+use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main};
+use datafusion_common::{JoinType, NullEquality};
+use datafusion_execution::TaskContext;
+use datafusion_physical_expr::expressions::col;
+use datafusion_physical_plan::collect;
+use datafusion_physical_plan::joins::{HashJoinExec, PartitionMode, utils::JoinOn};
+use datafusion_physical_plan::test::TestMemoryExec;
+use tokio::runtime::Runtime;
+
+/// Build RecordBatches with Int32 keys.
+///
+/// Schema: (key: Int32, data: Int32, payload: Utf8)
+///
+/// `key_mod` controls distinct key count: key = row_index % key_mod.
+/// `key_offset` shifts keys to control hit rate.
+fn build_batches(
+ num_rows: usize,
+ key_mod: usize,
+ key_offset: i32,
+ schema: &SchemaRef,
+) -> Vec<RecordBatch> {
+ let keys: Vec<i32> = (0..num_rows)
+ .map(|i| ((i % key_mod) as i32) + key_offset)
+ .collect();
+ let data: Vec<i32> = (0..num_rows).map(|i| i as i32).collect();
+ let payload: Vec<String> = data.iter().map(|d| format!("val_{d}")).collect();
+
+ let batch = RecordBatch::try_new(
+ Arc::clone(schema),
+ vec![
+ Arc::new(Int32Array::from(keys)),
+ Arc::new(Int32Array::from(data)),
+ Arc::new(StringArray::from(payload)),
+ ],
+ )
+ .unwrap();
+
+ let batch_size = 8192;
+ let mut batches = Vec::new();
+ let mut offset = 0;
+ while offset < batch.num_rows() {
+ let len = (batch.num_rows() - offset).min(batch_size);
+ batches.push(batch.slice(offset, len));
+ offset += len;
+ }
+ batches
+}
+
+fn make_exec(
+ batches: &[RecordBatch],
+ schema: &SchemaRef,
+) -> Arc<dyn datafusion_physical_plan::ExecutionPlan> {
+ TestMemoryExec::try_new_exec(&[batches.to_vec()], Arc::clone(schema), None).unwrap()
+}
+
+fn schema() -> SchemaRef {
+ Arc::new(Schema::new(vec![
+ Field::new("key", DataType::Int32, false),
+ Field::new("data", DataType::Int32, false),
+ Field::new("payload", DataType::Utf8, false),
+ ]))
+}
+
+fn do_hash_join(
+ left: Arc<dyn datafusion_physical_plan::ExecutionPlan>,
+ right: Arc<dyn datafusion_physical_plan::ExecutionPlan>,
+ join_type: JoinType,
+ rt: &Runtime,
+) -> usize {
+ let on: JoinOn = vec![(
+ col("key", &left.schema()).unwrap(),
+ col("key", &right.schema()).unwrap(),
+ )];
+ let join = HashJoinExec::try_new(
+ left,
+ right,
+ on,
+ None,
+ &join_type,
+ None,
+ PartitionMode::CollectLeft,
+ NullEquality::NullEqualsNothing,
+ false,
+ )
+ .unwrap();
+
+ let task_ctx = Arc::new(TaskContext::default());
+ rt.block_on(async {
+ let batches = collect(Arc::new(join), task_ctx).await.unwrap();
+ batches.iter().map(|b| b.num_rows()).sum()
+ })
+}
+
+/// Build batches with sparse keys (key = row_index % key_mod * multiplier + key_offset).
+/// The `multiplier` controls density: 1 = 100%, 2 = 50%, 10 = 10%.
+fn build_batches_sparse(
+ num_rows: usize,
+ key_mod: usize,
+ key_offset: i32,
+ multiplier: i32,
+ schema: &SchemaRef,
+) -> Vec<RecordBatch> {
+ let keys: Vec<i32> = (0..num_rows)
+ .map(|i| ((i % key_mod) as i32) * multiplier + key_offset)
+ .collect();
+ let data: Vec<i32> = (0..num_rows).map(|i| i as i32).collect();
+ let payload: Vec<String> = data.iter().map(|d| format!("val_{d}")).collect();
+
+ let batch = RecordBatch::try_new(
+ Arc::clone(schema),
+ vec![
+ Arc::new(Int32Array::from(keys)),
+ Arc::new(Int32Array::from(data)),
+ Arc::new(StringArray::from(payload)),
+ ],
+ )
+ .unwrap();
+
+ let batch_size = 8192;
+ let mut batches = Vec::new();
+ let mut offset = 0;
+ while offset < batch.num_rows() {
+ let len = (batch.num_rows() - offset).min(batch_size);
+ batches.push(batch.slice(offset, len));
+ offset += len;
+ }
+ batches
+}
+
+fn bench_hash_join_semi_anti(c: &mut Criterion) {
+ let rt = Runtime::new().unwrap();
+ let s = schema();
+
+ let mut group = c.benchmark_group("hash_join_semi_anti");
+
+ // Build side: 100K rows, Probe side: 1M rows
+ // Matching ratio: 1:1 (build keys are unique, each probe matches at most 1 build row)
+ let build_rows = 100_000;
+ let probe_rows = 1_000_000;
+
+ // =========================================================================
+ // RightSemi Join benchmarks
+ // =========================================================================
+
+ // RightSemi - 100% Density, 100% hit rate
+ // Keys: 0..100K contiguous, all probe rows find a match
+ {
+ let left_batches = build_batches(build_rows, build_rows, 0, &s);
+ let right_batches = build_batches(probe_rows, build_rows, 0, &s);
+ group.bench_function(BenchmarkId::new("right_semi_d100_h100", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightSemi, &rt)
+ })
+ });
+ }
+
+ // RightSemi - 100% Density, 10% hit rate
+ // Keys: 0..100K contiguous, only 10% of probe rows find a match
+ {
+ let left_batches = build_batches(build_rows, build_rows, 0, &s);
+ let right_batches = build_batches(probe_rows, build_rows * 10, 0, &s);
+ group.bench_function(BenchmarkId::new("right_semi_d100_h10", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightSemi, &rt)
+ })
+ });
+ }
+
+ // RightSemi - 50% Density, 100% hit rate
+ // Keys: 0, 2, 4, ... (sparse, multiplier=2), all probe rows find a match
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 2, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows, 0, 2, &s);
+ group.bench_function(BenchmarkId::new("right_semi_d50_h100", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightSemi, &rt)
+ })
+ });
+ }
+
+ // RightSemi - 50% Density, 10% hit rate
+ // Keys: 0, 2, 4, ... (sparse), only 10% of probe rows find a match
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 2, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows * 10, 0, 2, &s);
+ group.bench_function(BenchmarkId::new("right_semi_d50_h10", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightSemi, &rt)
+ })
+ });
+ }
+
+ // RightSemi - 10% Density, 100% hit rate
+ // Keys: 0, 10, 20, ... (very sparse, multiplier=10), all probe rows find a match
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 10, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows, 0, 10, &s);
+ group.bench_function(BenchmarkId::new("right_semi_d10_h100", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightSemi, &rt)
+ })
+ });
+ }
+
+ // RightSemi - 10% Density, 10% hit rate
+ // Keys: 0, 10, 20, ... (very sparse), only 10% of probe rows find a match
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 10, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows * 10, 0, 10, &s);
+ group.bench_function(BenchmarkId::new("right_semi_d10_h10", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightSemi, &rt)
+ })
+ });
+ }
+
+ // =========================================================================
+ // RightAnti Join benchmarks
+ // =========================================================================
+
+ // RightAnti - 100% Density, 100% hit rate (no output)
+ // Keys: 0..100K contiguous, all probe rows find a match -> no output
+ {
+ let left_batches = build_batches(build_rows, build_rows, 0, &s);
+ let right_batches = build_batches(probe_rows, build_rows, 0, &s);
+ group.bench_function(BenchmarkId::new("right_anti_d100_h100", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightAnti, &rt)
+ })
+ });
+ }
+
+ // RightAnti - 100% Density, 10% hit rate (90% output)
+ // Keys: 0..100K contiguous, only 10% of probe rows find a match -> 90% output
+ {
+ let left_batches = build_batches(build_rows, build_rows, 0, &s);
+ let right_batches = build_batches(probe_rows, build_rows * 10, 0, &s);
+ group.bench_function(BenchmarkId::new("right_anti_d100_h10", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightAnti, &rt)
+ })
+ });
+ }
+
+ // RightAnti - 50% Density, 100% hit rate (no output)
+ // Keys: 0, 2, 4, ... (sparse), all probe rows find a match -> no output
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 2, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows, 0, 2, &s);
+ group.bench_function(BenchmarkId::new("right_anti_d50_h100", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightAnti, &rt)
+ })
+ });
+ }
+
+ // RightAnti - 50% Density, 10% hit rate (90% output)
+ // Keys: 0, 2, 4, ... (sparse), only 10% of probe rows find a match -> 90% output
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 2, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows * 10, 0, 2, &s);
+ group.bench_function(BenchmarkId::new("right_anti_d50_h10", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightAnti, &rt)
+ })
+ });
+ }
+
+ // RightAnti - 10% Density, 100% hit rate (no output)
+ // Keys: 0, 10, 20, ... (very sparse), all probe rows find a match -> no output
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 10, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows, 0, 10, &s);
+ group.bench_function(BenchmarkId::new("right_anti_d10_h100", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightAnti, &rt)
+ })
+ });
+ }
+
+ // RightAnti - 10% Density, 10% hit rate (90% output)
+ // Keys: 0, 10, 20, ... (very sparse), only 10% of probe rows find a match -> 90% output
+ {
+ let left_batches = build_batches_sparse(build_rows, build_rows, 0, 10, &s);
+ let right_batches = build_batches_sparse(probe_rows, build_rows * 10, 0, 10, &s);
+ group.bench_function(BenchmarkId::new("right_anti_d10_h10", probe_rows), |b| {
+ b.iter(|| {
+ let left = make_exec(&left_batches, &s);
+ let right = make_exec(&right_batches, &s);
+ do_hash_join(left, right, JoinType::RightAnti, &rt)
+ })
+ });
+ }
+
+ group.finish();
+}
+
+criterion_group!(benches, bench_hash_join_semi_anti);
+criterion_main!(benches);