Skip to content

Apache DataFusion SQL Query Engine

fix: emit deferred unmatched rows when memory-limited NestedLoopJoin exhausts its left side (#24746)

Liang-Chi Hsieh16cce96b42b1
diff --git a/datafusion/core/tests/memory_limit/mod.rs b/datafusion/core/tests/memory_limit/mod.rs
index f01ed4160f..02856ebb5a 100644
--- a/datafusion/core/tests/memory_limit/mod.rs
+++ b/datafusion/core/tests/memory_limit/mod.rs
@@ -22,6 +22,7 @@ use std::sync::{Arc, LazyLock};
#[cfg(feature = "extended_tests")]
mod memory_limit_validation;
+mod nlj_spill_unmatched;
mod repartition_mem_limit;
mod union_nullable_spill;
mod view_spill_compaction;
diff --git a/datafusion/core/tests/memory_limit/nlj_spill_unmatched.rs b/datafusion/core/tests/memory_limit/nlj_spill_unmatched.rs
new file mode 100644
index 0000000000..7e0a4c3013
--- /dev/null
+++ b/datafusion/core/tests/memory_limit/nlj_spill_unmatched.rs
@@ -0,0 +1,147 @@
+// 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.
+
+//! Memory-limited `NestedLoopJoinExec` must not drop unmatched rows.
+//!
+//! When the join spills, per-right-batch match bitmaps are accumulated across
+//! left chunks and their emission is deferred until every chunk has been
+//! probed. The load that follows the final chunk finds no left batches left,
+//! and that exit used to end the stream immediately — discarding the
+//! accumulated bitmaps, so rows that no chunk ever matched were never emitted.
+
+use std::sync::Arc;
+
+use arrow::array::{Int32Array, RecordBatch};
+use arrow::datatypes::{DataType, Field, Schema};
+use datafusion::prelude::*;
+use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+
+/// Deterministic table whose join keys repeat, so most rows match and only a
+/// few remain unmatched.
+fn table(rows: usize, value_column: &str, seed: u64) -> RecordBatch {
+ let mut state = seed;
+ let mut next = || {
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ state >> 33
+ };
+ let schema = Arc::new(Schema::new(vec![
+ Field::new("k", DataType::Int32, true),
+ Field::new(value_column, DataType::Int32, true),
+ ]));
+ let keys: Vec<Option<i32>> = (0..rows).map(|_| Some((next() % 10) as i32)).collect();
+ let values: Vec<Option<i32>> =
+ (0..rows).map(|_| Some((next() % 60) as i32)).collect();
+ RecordBatch::try_new(
+ schema,
+ vec![
+ Arc::new(Int32Array::from(keys)),
+ Arc::new(Int32Array::from(values)),
+ ],
+ )
+ .unwrap()
+}
+
+/// Run `sql`, optionally under a memory limit, returning the sorted rows.
+async fn run(sql: &str, memory_limit: Option<usize>) -> Vec<String> {
+ let config = SessionConfig::new()
+ .with_target_partitions(1)
+ .with_batch_size(16);
+ let runtime = match memory_limit {
+ Some(bytes) => RuntimeEnvBuilder::new()
+ .with_memory_limit(bytes, 1.0)
+ .build_arc()
+ .unwrap(),
+ None => RuntimeEnvBuilder::new().build_arc().unwrap(),
+ };
+ let ctx = SessionContext::new_with_config_rt(config, runtime);
+ ctx.register_batch("l", table(200, "v", 11)).unwrap();
+ ctx.register_batch("r", table(90, "w", 16)).unwrap();
+
+ let batches = ctx.sql(sql).await.unwrap().collect().await.unwrap();
+ let mut rows = vec![];
+ for batch in &batches {
+ for row in 0..batch.num_rows() {
+ let cells: Vec<String> = (0..batch.num_columns())
+ .map(|col| {
+ datafusion_common::ScalarValue::try_from_array(batch.column(col), row)
+ .unwrap()
+ .to_string()
+ })
+ .collect();
+ rows.push(cells.join("|"));
+ }
+ }
+ rows.sort();
+ rows
+}
+
+/// A non-equi `LEFT JOIN` is planned as a `NestedLoopJoinExec`; the optimizer
+/// swaps the inputs, so the rows needing unmatched emission end up on the
+/// join's probe side. Spilling must not lose them.
+#[tokio::test]
+async fn left_join_keeps_unmatched_rows_when_spilling() {
+ let sql = "SELECT l.k, r.w FROM l LEFT JOIN r ON l.v > r.w";
+
+ let ample = run(sql, None).await;
+ let limited = run(sql, Some(64)).await;
+
+ assert_eq!(
+ limited,
+ ample,
+ "memory-limited execution returned {} rows instead of {}",
+ limited.len(),
+ ample.len()
+ );
+}
+
+/// `LEFT ANTI` returns only unmatched rows, so losing them empties the result.
+#[tokio::test]
+async fn left_anti_join_keeps_unmatched_rows_when_spilling() {
+ let sql = "SELECT l.k, l.v FROM l \
+ WHERE NOT EXISTS (SELECT 1 FROM r WHERE l.v > r.w)";
+
+ let ample = run(sql, None).await;
+ let limited = run(sql, Some(64)).await;
+
+ assert!(!ample.is_empty(), "expected the query to match some rows");
+ assert_eq!(
+ limited,
+ ample,
+ "memory-limited execution returned {} rows instead of {}",
+ limited.len(),
+ ample.len()
+ );
+}
+
+/// `FULL JOIN` needs unmatched emission on both sides.
+#[tokio::test]
+async fn full_join_keeps_unmatched_rows_when_spilling() {
+ let sql = "SELECT l.k, r.w FROM l FULL JOIN r ON l.v > r.w";
+
+ let ample = run(sql, None).await;
+ let limited = run(sql, Some(64)).await;
+
+ assert_eq!(
+ limited,
+ ample,
+ "memory-limited execution returned {} rows instead of {}",
+ limited.len(),
+ ample.len()
+ );
+}
diff --git a/datafusion/physical-plan/src/joins/nested_loop_join.rs b/datafusion/physical-plan/src/joins/nested_loop_join.rs
index 6d9780a8fc..bb91735369 100644
--- a/datafusion/physical-plan/src/joins/nested_loop_join.rs
+++ b/datafusion/physical-plan/src/joins/nested_loop_join.rs
@@ -1961,9 +1961,23 @@ impl NestedLoopJoinStream {
}
if active.pending_batches.is_empty() {
- // No data at all — go directly to Done
self.left_exhausted = true;
- self.state = NLJState::Done;
+ // Reached both when the left side was empty from the start and when
+ // the previous chunk consumed the last of it, so this load finds
+ // nothing left. In the latter case earlier chunks have already
+ // merged their per-batch bitmaps into `global_right_bitmaps`, and
+ // those unmatched probe-side rows are still waiting to be emitted.
+ // Going straight to `Done` would discard them, silently dropping
+ // rows. `EmitGlobalRightUnmatched` replays the spilled right side
+ // and emits them; with no bitmaps accumulated it reports nothing
+ // unmatched and finishes immediately, so a genuinely empty left
+ // side behaves as before.
+ self.state = if self.should_track_unmatched_right {
+ self.right_data = None;
+ NLJState::EmitGlobalRightUnmatched
+ } else {
+ NLJState::Done
+ };
return ControlFlow::Continue(());
}