Apache DataFusion SQL Query Engine
feat: Add memory-limited execution for NestedLoopJoinExec (#21448)
Liang-Chi Hsiehf9239a197f2c
diff --git a/datafusion/physical-plan/src/joins/nested_loop_join.rs b/datafusion/physical-plan/src/joins/nested_loop_join.rsindex cdfe3a33ec..9ca2052e93 100644--- a/datafusion/physical-plan/src/joins/nested_loop_join.rs+++ b/datafusion/physical-plan/src/joins/nested_loop_join.rs@@ -66,6 +66,7 @@ use datafusion_common::{internal_datafusion_err, internal_err, project_schema, unwrap_or_internal_err,};use datafusion_execution::TaskContext;+use datafusion_execution::disk_manager::RefCountedTempFile;use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};use datafusion_expr::JoinType;use datafusion_physical_expr::equivalence::{@@ -77,6 +78,10 @@ use futures::{Stream, StreamExt, TryStreamExt};use log::debug;use parking_lot::Mutex;+use crate::metrics::SpillMetrics;+use crate::spill::in_progress_spill_file::InProgressSpillFile;+use crate::spill::spill_manager::SpillManager;+#[expect(rustdoc::private_intra_doc_links)]/// NestedLoopJoinExec is a build-probe join operator designed for joins that/// do not have equijoin keys in their `ON` clause.@@ -160,10 +165,21 @@ use parking_lot::Mutex;/// - The design try to minimize the intermediate data size to approximately/// 1 batch, for better cache locality and memory efficiency.///-/// # TODO: Memory-limited Execution-/// If the memory budget is exceeded during left-side buffering, fallback-/// strategies such as streaming left batches and re-scanning the right side-/// may be implemented in the future.+/// # Memory-limited Execution+/// When the memory budget is exceeded during left-side buffering, the operator+/// falls back to a multi-pass strategy:+/// 1. Buffer as many left rows as fit in memory (one "chunk")+/// 2. On the first pass, the right side is both processed and spilled to disk+/// 3. For each subsequent left chunk, the right side is re-read from the spill file+///+/// The fallback is triggered automatically when the initial in-memory load+/// fails with `ResourcesExhausted` and disk spilling is available. Each+/// output partition independently re-executes the left child and manages+/// its own spill state.+///+/// Currently supports INNER, LEFT, LEFT SEMI, LEFT ANTI, and LEFT MARK+/// join types. RIGHT/FULL joins require a global right-side bitmap across+/// all left chunks, which is not yet implemented.////// Tracking issue: <https://github.com/apache/datafusion/issues/15760>///@@ -594,8 +610,22 @@ impl ExecutionPlan for NestedLoopJoinExec {);let metrics = NestedLoopJoinMetrics::new(&self.metrics, partition);+ let batch_size = context.session_config().batch_size();- // Initialization reservation for load of inner table+ // update column indices to reflect the projection+ let column_indices_after_projection = match self.projection.as_ref() {+ Some(projection) => projection+ .iter()+ .map(|i| self.column_indices[*i].clone())+ .collect(),+ None => self.column_indices.clone(),+ };++ let right_partition_count = self.right().output_partitioning().partition_count();++ // Always try to buffer all left data in memory via OnceFut.+ // If that fails with OOM, the stream will fallback to memory-limited+ // mode (if conditions allow).let load_reservation =MemoryConsumer::new(format!("NestedLoopJoinLoad[{partition}]")).register(context.memory_pool());@@ -608,21 +638,24 @@ impl ExecutionPlan for NestedLoopJoinExec {metrics.join_metrics.clone(),load_reservation,need_produce_result_in_final(self.join_type),- self.right().output_partitioning().partition_count(),+ right_partition_count,))})?;- let batch_size = context.session_config().batch_size();+ let probe_side_data = self.right.execute(partition, Arc::clone(&context))?;- let probe_side_data = self.right.execute(partition, context)?;+ // Determine if OOM fallback to memory-limited mode is possible.+ // Conditions:+ // 1. Disk manager supports temp files (needed for right-side spilling)+ // 2. Join type does not require tracking right-side matched state+ // across multiple left chunks (RIGHT/FULL joins not yet supported)+ let can_fallback = context.runtime_env().disk_manager.tmp_files_enabled()+ && !need_produce_right_in_final(self.join_type);- // update column indices to reflect the projection- let column_indices_after_projection = match self.projection.as_ref() {- Some(projection) => projection- .iter()- .map(|i| self.column_indices[*i].clone())- .collect(),- None => self.column_indices.clone(),+ let (left_plan, task_context) = if can_fallback {+ (Some(Arc::clone(&self.left)), Some(Arc::clone(&context)))+ } else {+ (None, None)};Ok(Box::pin(NestedLoopJoinStream::new(@@ -634,6 +667,8 @@ impl ExecutionPlan for NestedLoopJoinExec {column_indices_after_projection,metrics,batch_size,+ left_plan,+ task_context,)))}@@ -892,9 +927,7 @@ pub(crate) struct NestedLoopJoinStream {/// Should we go back to `BufferingLeft` state again after `EmitLeftUnmatched`/// state is over.left_exhausted: bool,- /// If we can buffer all left data in one pass- /// TODO(now): this is for the (unimplemented) memory-limited execution- #[expect(dead_code)]+ /// If we can buffer all left data in one pass (false means memory-limited multi-pass)left_buffered_in_one_pass: bool,// Probe(right) side@@ -904,6 +937,43 @@ pub(crate) struct NestedLoopJoinStream {// For right join, keep track of matched rows in `current_right_batch`// Constructed when fetching each new incoming right batch in `FetchingRight` state.current_right_batch_matched: Option<BooleanArray>,++ // ========================================================================+ // MEMORY-LIMITED EXECUTION FIELDS:+ // Used when left-side data exceeds the memory budget. In this mode,+ // left data is loaded in chunks, and the right side is spilled to disk+ // so it can be re-scanned for each left chunk.+ // ========================================================================+ /// Left input stream for incremental buffering (memory-limited mode only).+ /// None when using the standard OnceFut path.+ left_stream: Option<SendableRecordBatchStream>,+ /// Memory reservation for left-side buffering in memory-limited mode+ left_reservation: Option<MemoryReservation>,+ /// Accumulated left batches for the current chunk (memory-limited mode)+ left_pending_batches: Vec<RecordBatch>,+ /// Left-side schema (for concat_batches in memory-limited mode)+ left_schema: Option<SchemaRef>,++ /// SpillManager for right-side spilling+ spill_manager: Option<SpillManager>,+ /// In-progress spill file for writing right batches during first pass+ right_spill_in_progress: Option<InProgressSpillFile>,+ /// Completed right-side spill file (available after first pass)+ right_spill_file: Option<RefCountedTempFile>,+ /// Max right batch memory size (for read_spill_as_stream)+ right_max_batch_memory: usize,+ /// Whether this is the first right-side pass (need to spill while reading)+ is_first_right_pass: bool,++ // ========================================================================+ // FALLBACK CONTEXT:+ // Stored at execute() time so that handle_buffering_left can initiate+ // a fallback to memory-limited mode if OnceFut fails with OOM.+ // ========================================================================+ /// Left child plan for re-execution on OOM fallback+ left_plan: Option<Arc<dyn ExecutionPlan>>,+ /// TaskContext for re-execution and SpillManager creation+ task_context: Option<Arc<TaskContext>>,}pub(crate) struct NestedLoopJoinMetrics {@@ -911,6 +981,8 @@ pub(crate) struct NestedLoopJoinMetrics {pub(crate) join_metrics: BuildProbeJoinMetrics,/// Selectivity of the join: output_rows / (left_rows * right_rows)pub(crate) selectivity: RatioMetrics,+ /// Spill metrics for memory-limited execution+ pub(crate) spill_metrics: SpillMetrics,}impl NestedLoopJoinMetrics {@@ -920,6 +992,7 @@ impl NestedLoopJoinMetrics {selectivity: MetricBuilder::new(metrics).with_type(MetricType::Summary).ratio_metrics("selectivity", partition),+ spill_metrics: SpillMetrics::new(metrics, partition),}}}@@ -1079,9 +1152,9 @@ impl Stream for NestedLoopJoinStream {// 3. --> Done// It has processed all data, go to the final state and ready// to exit.- //- // TODO: For memory-limited case, go back to `BufferingLeft`- // state again.+ // 4. --> BufferingLeft (memory-limited mode only)+ // When left data was loaded in chunks and more chunks remain,+ // go back to BufferingLeft to load the next chunk.NLJState::EmitLeftUnmatched => {debug!("[NLJState] Entering: {:?}", self.state);@@ -1132,6 +1205,8 @@ impl NestedLoopJoinStream {column_indices: Vec<ColumnIndex>,metrics: NestedLoopJoinMetrics,batch_size: usize,+ left_plan: Option<Arc<dyn ExecutionPlan>>,+ task_context: Option<Arc<TaskContext>>,) -> Self {Self {output_schema: Arc::clone(&schema),@@ -1153,31 +1228,298 @@ impl NestedLoopJoinStream {left_buffered_in_one_pass: true,handled_empty_output: false,should_track_unmatched_right: need_produce_right_in_final(join_type),+ // Memory-limited fields (inactive until OOM fallback)+ left_stream: None,+ left_reservation: None,+ left_pending_batches: Vec::new(),+ left_schema: None,+ spill_manager: None,+ right_spill_in_progress: None,+ right_spill_file: None,+ right_max_batch_memory: 0,+ is_first_right_pass: true,+ // Fallback context+ left_plan,+ task_context,}}+ /// Returns true if this stream is operating in memory-limited mode+ fn is_memory_limited(&self) -> bool {+ self.left_stream.is_some() || self.left_reservation.is_some()+ }++ /// Check if we can fall back to memory-limited mode on this error.+ fn can_fallback_to_spill(&self, error: &datafusion_common::DataFusionError) -> bool {+ self.left_plan.is_some()+ && self.task_context.is_some()+ && !self.is_memory_limited() // avoid infinite loop+ && matches!(+ error.find_root(),+ datafusion_common::DataFusionError::ResourcesExhausted(_)+ )+ }++ /// Switch from the standard OnceFut path to memory-limited mode.+ ///+ /// Re-executes the left child to get a fresh stream, creates a+ /// SpillManager for right-side spilling, and sets up all the+ /// memory-limited fields. The next call to `handle_buffering_left`+ /// will dispatch to `handle_buffering_left_memory_limited`.+ fn initiate_fallback(&mut self) -> Result<()> {+ let left_plan = self+ .left_plan+ .as_ref()+ .expect("left_plan must be set for fallback");+ let context = self+ .task_context+ .as_ref()+ .expect("task_context must be set for fallback");++ // Re-execute left child to get a fresh stream+ let left_stream = left_plan.execute(0, Arc::clone(context))?;+ let left_schema = left_stream.schema();++ // Create reservation with can_spill for fair memory allocation+ let reservation = MemoryConsumer::new("NestedLoopJoinLoad[fallback]".to_string())+ .with_can_spill(true)+ .register(context.memory_pool());++ // Create SpillManager for right-side spilling+ let right_schema = self.right_data.schema();+ let spill_manager = SpillManager::new(+ context.runtime_env(),+ self.metrics.spill_metrics.clone(),+ right_schema,+ )+ .with_compression_type(context.session_config().spill_compression());++ // Populate memory-limited fields+ self.left_stream = Some(left_stream);+ self.left_schema = Some(left_schema);+ self.left_reservation = Some(reservation);+ self.left_pending_batches = Vec::new();+ self.spill_manager = Some(spill_manager);+ self.right_spill_in_progress = None;+ self.right_spill_file = None;+ self.right_max_batch_memory = 0;+ self.is_first_right_pass = true;++ // State stays BufferingLeft — next poll will enter+ // handle_buffering_left_memory_limited via is_memory_limited() check+ self.state = NLJState::BufferingLeft;++ Ok(())+ }+// ==== State handler functions ====- /// Handle BufferingLeft state - prepare left side batches+ /// Handle BufferingLeft state - prepare left side batches.+ ///+ /// In standard mode, uses OnceFut to load all left data at once.+ /// In memory-limited mode, incrementally buffers left batches until the+ /// memory budget is reached or the left stream is exhausted.fn handle_buffering_left(&mut self,cx: &mut std::task::Context<'_>,) -> ControlFlow<Poll<Option<Result<RecordBatch>>>> {- match self.left_data.get_shared(cx) {- Poll::Ready(Ok(left_data)) => {- self.buffered_left_data = Some(left_data);- // TODO: implement memory-limited case- self.left_exhausted = true;- self.state = NLJState::FetchingRight;- // Continue to next state immediately- ControlFlow::Continue(())+ if self.is_memory_limited() {+ self.handle_buffering_left_memory_limited(cx)+ } else {+ // Standard path: use OnceFut+ match self.left_data.get_shared(cx) {+ Poll::Ready(Ok(left_data)) => {+ self.buffered_left_data = Some(left_data);+ self.left_exhausted = true;+ self.state = NLJState::FetchingRight;+ ControlFlow::Continue(())+ }+ Poll::Ready(Err(e)) => {+ if self.can_fallback_to_spill(&e) {+ debug!(+ "NestedLoopJoin: OnceFut failed with OOM, \+ falling back to memory-limited mode"+ );+ match self.initiate_fallback() {+ Ok(()) => ControlFlow::Continue(()),+ Err(fallback_err) => {+ ControlFlow::Break(Poll::Ready(Some(Err(fallback_err))))+ }+ }+ } else {+ ControlFlow::Break(Poll::Ready(Some(Err(e))))+ }+ }+ Poll::Pending => ControlFlow::Break(Poll::Pending),}- Poll::Ready(Err(e)) => ControlFlow::Break(Poll::Ready(Some(Err(e)))),- Poll::Pending => ControlFlow::Break(Poll::Pending),}}- /// Handle FetchingRight state - fetch next right batch and prepare for processing+ /// Memory-limited path for handle_buffering_left.+ ///+ /// Incrementally polls the left stream and accumulates batches until:+ /// - Memory reservation fails (chunk is full, more data remains)+ /// - Left stream is exhausted (this is the last/only chunk)+ fn handle_buffering_left_memory_limited(+ &mut self,+ cx: &mut std::task::Context<'_>,+ ) -> ControlFlow<Poll<Option<Result<RecordBatch>>>> {+ let reservation = self+ .left_reservation+ .as_ref()+ .expect("left_reservation must be set in memory-limited mode");++ // Poll left stream for more batches.+ // Note: left_pending_batches may already contain a batch from the+ // previous chunk iteration (the batch that triggered the memory limit).+ loop {+ let left_stream = self+ .left_stream+ .as_mut()+ .expect("left_stream must be set in memory-limited mode");++ match left_stream.poll_next_unpin(cx) {+ Poll::Ready(Some(Ok(batch))) => {+ if batch.num_rows() == 0 {+ continue;+ }+ let batch_rows = batch.num_rows();+ let batch_size = batch.get_array_memory_size();+ let can_grow = reservation.try_grow(batch_size).is_ok();++ if !can_grow && !self.left_pending_batches.is_empty() {+ // Memory limit reached and we already have data.+ // Push this batch into pending (it's already in memory)+ // and stop buffering for this chunk.+ self.left_pending_batches.push(batch);+ self.left_exhausted = false;+ self.left_buffered_in_one_pass = false;+ break;+ } else if !can_grow {+ // No pending batches yet — we must accept this batch+ // to make progress, even if it exceeds the budget.+ reservation.grow(batch_size);+ }++ self.metrics.join_metrics.build_mem_used.add(batch_size);+ self.metrics.join_metrics.build_input_batches.add(1);+ self.metrics.join_metrics.build_input_rows.add(batch_rows);+ self.left_pending_batches.push(batch);+ }+ Poll::Ready(Some(Err(e))) => {+ return ControlFlow::Break(Poll::Ready(Some(Err(e))));+ }+ Poll::Ready(None) => {+ // Left stream exhausted+ self.left_exhausted = true;+ self.left_stream = None;+ break;+ }+ Poll::Pending => {+ if self.left_pending_batches.is_empty() {+ return ControlFlow::Break(Poll::Pending);+ }+ // We have some batches, proceed with what we have.+ // The stashed approach will handle the rest.+ // Actually we should wait for more data.+ return ControlFlow::Break(Poll::Pending);+ }+ }+ }++ // Build JoinLeftData from the accumulated batches+ let schema = self+ .left_schema+ .as_ref()+ .expect("left_schema must be set in memory-limited mode");++ if self.left_pending_batches.is_empty() {+ // No data at all — go directly to Done+ self.left_exhausted = true;+ self.state = NLJState::Done;+ return ControlFlow::Continue(());+ }++ let merged_batch = match concat_batches(schema, &self.left_pending_batches) {+ Ok(batch) => batch,+ Err(e) => {+ return ControlFlow::Break(Poll::Ready(Some(Err(e.into()))));+ }+ };+ self.left_pending_batches.clear();++ // Build visited bitmap if needed for this join type+ let with_visited = need_produce_result_in_final(self.join_type);+ let n_rows = merged_batch.num_rows();+ let visited_left_side = if with_visited {+ let buffer_size = n_rows.div_ceil(8);+ // Use infallible grow for bitmap — it's small+ reservation.grow(buffer_size);+ self.metrics.join_metrics.build_mem_used.add(buffer_size);+ let mut buffer = BooleanBufferBuilder::new(n_rows);+ buffer.append_n(n_rows, false);+ buffer+ } else {+ BooleanBufferBuilder::new(0)+ };++ // Create an empty reservation for JoinLeftData's RAII field.+ // The actual memory tracking is managed by self.left_reservation.+ let dummy_reservation = reservation.new_empty();++ let left_data = JoinLeftData::new(+ merged_batch,+ Mutex::new(visited_left_side),+ // In memory-limited mode, only 1 probe thread per chunk+ AtomicUsize::new(1),+ dummy_reservation,+ );++ self.buffered_left_data = Some(Arc::new(left_data));++ // If not the first pass, re-open the right spill file as a new stream+ if !self.is_first_right_pass {+ if let Some(spill_file) = &self.right_spill_file {+ let spill_manager = self+ .spill_manager+ .as_ref()+ .expect("spill_manager must be set in memory-limited mode");+ match spill_manager.read_spill_as_stream(+ spill_file.clone(),+ Some(self.right_max_batch_memory),+ ) {+ Ok(stream) => {+ self.right_data = stream;+ }+ Err(e) => {+ return ControlFlow::Break(Poll::Ready(Some(Err(e))));+ }+ }+ }+ } else {+ // First pass: create InProgressSpillFile for right side+ let spill_manager = self+ .spill_manager+ .as_ref()+ .expect("spill_manager must be set in memory-limited mode");+ match spill_manager.create_in_progress_file("NestedLoopJoin right spill") {+ Ok(spill_file) => {+ self.right_spill_in_progress = Some(spill_file);+ }+ Err(e) => {+ return ControlFlow::Break(Poll::Ready(Some(Err(e))));+ }+ }+ }++ self.state = NLJState::FetchingRight;+ ControlFlow::Continue(())+ }++ /// Handle FetchingRight state - fetch next right batch and prepare for processing.+ ///+ /// In memory-limited mode during the first pass, each right batch is also+ /// written to a spill file so it can be re-read on subsequent passes.fn handle_fetching_right(&mut self,cx: &mut std::task::Context<'_>,@@ -1186,20 +1528,33 @@ impl NestedLoopJoinStream {Poll::Ready(result) => match result {Some(Ok(right_batch)) => {// Update metrics- let right_batch_size = right_batch.num_rows();- self.metrics.join_metrics.input_rows.add(right_batch_size);+ let right_batch_rows = right_batch.num_rows();+ self.metrics.join_metrics.input_rows.add(right_batch_rows);self.metrics.join_metrics.input_batches.add(1);// Skip the empty batch- if right_batch_size == 0 {+ if right_batch_rows == 0 {return ControlFlow::Continue(());}+ // In memory-limited mode, spill right batch to disk on first pass+ if self.is_first_right_pass+ && let Some(spill_file) = self.right_spill_in_progress.as_mut()+ {+ if let Err(e) = spill_file.append_batch(&right_batch) {+ return ControlFlow::Break(Poll::Ready(Some(Err(e))));+ }+ // Track max batch memory for read_spill_as_stream+ self.right_max_batch_memory = self+ .right_max_batch_memory+ .max(right_batch.get_array_memory_size());+ }+self.current_right_batch = Some(right_batch);// Prepare right bitmapif self.should_track_unmatched_right {- let zeroed_buf = BooleanBuffer::new_unset(right_batch_size);+ let zeroed_buf = BooleanBuffer::new_unset(right_batch_rows);self.current_right_batch_matched =Some(BooleanArray::new(zeroed_buf, None));}@@ -1210,7 +1565,27 @@ impl NestedLoopJoinStream {}Some(Err(e)) => ControlFlow::Break(Poll::Ready(Some(Err(e)))),None => {- // Right stream exhausted+ // Right stream exhausted.+ // In memory-limited mode, finalize the spill file after first pass.+ if self.is_first_right_pass {+ if let Some(mut spill_in_progress) =+ self.right_spill_in_progress.take()+ {+ match spill_in_progress.finish() {+ Ok(Some(file)) => {+ self.right_spill_file = Some(file);+ }+ Ok(None) => {+ // No data was spilled (right side was empty)+ }+ Err(e) => {+ return ControlFlow::Break(Poll::Ready(Some(Err(e))));+ }+ }+ }+ self.is_first_right_pass = false;+ }+self.state = NLJState::EmitLeftUnmatched;ControlFlow::Continue(())}@@ -1304,7 +1679,11 @@ impl NestedLoopJoinStream {}}- /// Handle EmitLeftUnmatched state - emit unmatched left rows+ /// Handle EmitLeftUnmatched state - emit unmatched left rows.+ ///+ /// In memory-limited mode, after processing all unmatched rows for the+ /// current left chunk, transitions back to `BufferingLeft` to load the+ /// next chunk (if the left stream is not yet exhausted).fn handle_emit_left_unmatched(&mut self,) -> ControlFlow<Poll<Option<Result<RecordBatch>>>> {@@ -1318,11 +1697,30 @@ impl NestedLoopJoinStream {// State unchanged (EmitLeftUnmatched)// Continue processing until we have processed all unmatched rowsOk(true) => ControlFlow::Continue(()),- // To Done state- // We have finished processing all unmatched rows+ // We have finished processing all unmatched rows for this chunkOk(false) => match self.output_buffer.finish_buffered_batch() {Ok(()) => {- self.state = NLJState::Done;+ // Flush any completed batch before transitioning.+ // This is critical for the memory-limited path: the+ // ProbeRight results must be emitted before we discard+ // the current chunk and load the next one.+ if let Some(poll) = self.maybe_flush_ready_batch() {+ return ControlFlow::Break(poll);+ }++ if !self.left_exhausted && self.is_memory_limited() {+ // More left data to process — free current chunk and+ // go back to BufferingLeft for the next chunk+ if let Some(reservation) = self.left_reservation.as_ref() {+ reservation.resize(0);+ }+ self.buffered_left_data = None;+ self.left_probe_idx = 0;+ self.left_emit_idx = 0;+ self.state = NLJState::BufferingLeft;+ } else {+ self.state = NLJState::Done;+ }ControlFlow::Continue(())}Err(e) => ControlFlow::Break(Poll::Ready(Some(arrow_err!(e)))),@@ -2863,20 +3261,44 @@ pub(crate) mod tests {);let filter = prepare_join_filter();- let join_types = vec![+ // Join types that support memory-limited fallback should succeed+ // even under tight memory limits (they spill to disk instead of OOM).+ let fallback_join_types = vec![JoinType::Inner,JoinType::Left,- JoinType::Right,- JoinType::Full,JoinType::LeftSemi,JoinType::LeftAnti,JoinType::LeftMark,+ ];++ for join_type in &fallback_join_types {+ let runtime = RuntimeEnvBuilder::new()+ .with_memory_limit(100, 1.0)+ .build_arc()?;+ let task_ctx = TaskContext::default().with_runtime(runtime);+ let task_ctx = Arc::new(task_ctx);++ // Should succeed via spill fallback, not OOM+ let _result = multi_partitioned_join_collect(+ Arc::clone(&left),+ Arc::clone(&right),+ join_type,+ Some(filter.clone()),+ task_ctx,+ )+ .await?;+ }++ // Join types that do NOT support fallback should still OOM.+ let no_fallback_join_types = vec![+ JoinType::Right,+ JoinType::Full,JoinType::RightSemi,JoinType::RightAnti,JoinType::RightMark,];- for join_type in join_types {+ for join_type in &no_fallback_join_types {let runtime = RuntimeEnvBuilder::new().with_memory_limit(100, 1.0).build_arc()?;@@ -2886,17 +3308,14 @@ pub(crate) mod tests {let err = multi_partitioned_join_collect(Arc::clone(&left),Arc::clone(&right),- &join_type,+ join_type,Some(filter.clone()),task_ctx,).await.unwrap_err();- assert_contains!(- err.to_string(),- "Resources exhausted: Additional allocation failed for NestedLoopJoinLoad[0] with top memory consumers (across reservations) as:\n NestedLoopJoinLoad[0]"- );+ assert_contains!(err.to_string(), "Resources exhausted");}Ok(())@@ -2906,4 +3325,224 @@ pub(crate) mod tests {fn columns(schema: &Schema) -> Vec<String> {schema.fields().iter().map(|f| f.name().clone()).collect()}++ // ========================================================================+ // Memory-limited execution tests+ // ========================================================================++ /// Helper to run a NLJ using partition 0 and collect results + metrics.+ async fn join_collect(+ left: Arc<dyn ExecutionPlan>,+ right: Arc<dyn ExecutionPlan>,+ join_type: &JoinType,+ join_filter: Option<JoinFilter>,+ context: Arc<TaskContext>,+ ) -> Result<(Vec<String>, Vec<RecordBatch>, MetricsSet)> {+ let nested_loop_join =+ NestedLoopJoinExec::try_new(left, right, join_filter, join_type, None)?;+ let columns = columns(&nested_loop_join.schema());+ let stream = nested_loop_join.execute(0, context)?;+ let batches: Vec<RecordBatch> = common::collect(stream)+ .await?+ .into_iter()+ .filter(|b| b.num_rows() > 0)+ .collect();+ let metrics = nested_loop_join.metrics().unwrap();+ Ok((columns, batches, metrics))+ }++ /// Create a TaskContext with tight memory limit and disk spilling enabled.+ fn task_ctx_with_memory_limit(+ memory_limit: usize,+ batch_size: usize,+ ) -> Result<Arc<TaskContext>> {+ let runtime = RuntimeEnvBuilder::new()+ .with_memory_limit(memory_limit, 1.0)+ .build_arc()?;+ let cfg = TaskContext::default()+ .session_config()+ .clone()+ .with_batch_size(batch_size);+ let task_ctx = TaskContext::default()+ .with_runtime(runtime)+ .with_session_config(cfg);+ Ok(Arc::new(task_ctx))+ }++ #[tokio::test]+ async fn test_nlj_memory_limited_inner_join() -> Result<()> {+ // Use a very small memory limit to force OOM → fallback to spill.+ let task_ctx = task_ctx_with_memory_limit(50, 16)?;+ let left = build_left_table();+ let right = build_right_table();+ let filter = prepare_join_filter();++ let (columns, batches, metrics) =+ join_collect(left, right, &JoinType::Inner, Some(filter), task_ctx).await?;++ assert_eq!(columns, vec!["a1", "b1", "c1", "a2", "b2", "c2"]);++ // Verify spill actually occurred (memory-limited path was taken)+ assert!(+ metrics.spill_count().unwrap_or(0) > 0,+ "Expected spilling to occur under tight memory limit"+ );++ // Result should be identical to the non-memory-limited case+ allow_duplicates!(assert_snapshot!(batches_to_sort_string(&batches), @r"+ +----+----+----+----+----+----++ | a1 | b1 | c1 | a2 | b2 | c2 |+ +----+----+----+----+----+----++ | 5 | 5 | 50 | 2 | 2 | 80 |+ +----+----+----+----+----+----++ "));+ Ok(())+ }++ #[tokio::test]+ async fn test_nlj_memory_limited_left_join() -> Result<()> {+ let task_ctx = task_ctx_with_memory_limit(50, 16)?;+ let left = build_left_table();+ let right = build_right_table();+ let filter = prepare_join_filter();++ let (columns, batches, metrics) =+ join_collect(left, right, &JoinType::Left, Some(filter), task_ctx).await?;++ assert_eq!(columns, vec!["a1", "b1", "c1", "a2", "b2", "c2"]);++ // Verify spill actually occurred+ assert!(+ metrics.spill_count().unwrap_or(0) > 0,+ "Expected spilling to occur under tight memory limit"+ );++ allow_duplicates!(assert_snapshot!(batches_to_sort_string(&batches), @r"+ +----+----+-----+----+----+----++ | a1 | b1 | c1 | a2 | b2 | c2 |+ +----+----+-----+----+----+----++ | 11 | 8 | 110 | | | |+ | 5 | 5 | 50 | 2 | 2 | 80 |+ | 9 | 8 | 90 | | | |+ +----+----+-----+----+----+----++ "));+ Ok(())+ }++ #[tokio::test]+ async fn test_nlj_fits_in_memory_no_spill() -> Result<()> {+ // Use a large memory limit — everything fits, no spilling needed.+ let task_ctx = task_ctx_with_memory_limit(10_000_000, 16)?;+ let left = build_left_table();+ let right = build_right_table();+ let filter = prepare_join_filter();++ let (columns, batches, metrics) =+ join_collect(left, right, &JoinType::Inner, Some(filter), task_ctx).await?;++ assert_eq!(columns, vec!["a1", "b1", "c1", "a2", "b2", "c2"]);++ // Verify no spilling occurred (standard OnceFut path was used)+ assert_eq!(+ metrics.spill_count().unwrap_or(0),+ 0,+ "Expected no spilling with generous memory limit"+ );++ allow_duplicates!(assert_snapshot!(batches_to_sort_string(&batches), @r"+ +----+----+----+----+----+----++ | a1 | b1 | c1 | a2 | b2 | c2 |+ +----+----+----+----+----+----++ | 5 | 5 | 50 | 2 | 2 | 80 |+ +----+----+----+----+----+----++ "));+ Ok(())+ }++ #[tokio::test]+ async fn test_nlj_memory_limited_empty_inputs() -> Result<()> {+ let task_ctx = task_ctx_with_memory_limit(50, 16)?;++ // Empty left table+ let empty_left = build_table(+ ("a1", &vec![]),+ ("b1", &vec![]),+ ("c1", &vec![]),+ None,+ Vec::new(),+ );+ let right = build_right_table();+ let filter = prepare_join_filter();++ let (_columns, batches, _metrics) =+ join_collect(empty_left, right, &JoinType::Inner, Some(filter), task_ctx)+ .await?;+ assert!(batches.is_empty() || batches.iter().all(|b| b.num_rows() == 0));++ // Empty right table+ let task_ctx2 = task_ctx_with_memory_limit(50, 16)?;+ let left = build_left_table();+ let empty_right = build_table(+ ("a2", &vec![]),+ ("b2", &vec![]),+ ("c2", &vec![]),+ None,+ Vec::new(),+ );+ let filter2 = prepare_join_filter();++ let (_columns, batches, _metrics) = join_collect(+ left,+ empty_right,+ &JoinType::Inner,+ Some(filter2),+ task_ctx2,+ )+ .await?;+ assert!(batches.is_empty() || batches.iter().all(|b| b.num_rows() == 0));++ Ok(())+ }++ #[tokio::test]+ async fn test_nlj_memory_limited_no_disk_falls_back_to_oom() -> Result<()> {+ // When disk is disabled, fallback is not possible and OOM should occur.+ use datafusion_execution::disk_manager::{DiskManagerBuilder, DiskManagerMode};++ let runtime = RuntimeEnvBuilder::new()+ .with_memory_limit(100, 1.0)+ .with_disk_manager_builder(+ DiskManagerBuilder::default().with_mode(DiskManagerMode::Disabled),+ )+ .build_arc()?;+ let task_ctx = Arc::new(TaskContext::default().with_runtime(runtime));++ let left = build_left_table();+ let right = build_right_table();+ let filter = prepare_join_filter();++ let err = join_collect(left, right, &JoinType::Inner, Some(filter), task_ctx)+ .await+ .unwrap_err();++ assert_contains!(err.to_string(), "Resources exhausted");+ Ok(())+ }++ #[tokio::test]+ async fn test_nlj_right_join_no_fallback_on_oom() -> Result<()> {+ // RIGHT JOIN does not support multi-pass fallback (needs global right+ // bitmap). OOM should propagate as an error.+ let task_ctx = task_ctx_with_memory_limit(50, 16)?;+ let left = build_left_table();+ let right = build_right_table();+ let filter = prepare_join_filter();++ let err = join_collect(left, right, &JoinType::Right, Some(filter), task_ctx)+ .await+ .unwrap_err();++ assert_contains!(err.to_string(), "Resources exhausted");+ Ok(())+ }}diff --git a/datafusion/sqllogictest/test_files/nested_loop_join_spill.slt b/datafusion/sqllogictest/test_files/nested_loop_join_spill.sltnew file mode 100644index 0000000000..5b383f3edf--- /dev/null+++ b/datafusion/sqllogictest/test_files/nested_loop_join_spill.slt@@ -0,0 +1,67 @@+# 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.++# Tests for NestedLoopJoinExec memory-limited execution (spill to disk).+# When the left (build) side exceeds the memory budget, the operator falls+# back to a multi-pass strategy that spills the right side to disk.++# Use a single target partition to avoid repartitioning.+statement ok+SET datafusion.execution.target_partitions = 1++# Set a memory limit small enough to force OOM on the left-side buffering+# (100K rows × 8 bytes ≈ 800KB > 150KB limit), triggering spill fallback.+statement ok+SET datafusion.runtime.memory_limit = '150K'++# --- INNER JOIN with non-equijoin predicate (forces NestedLoopJoinExec) ---+# Verify query succeeds and produces correct results under tight memory.+query III nosort+SELECT count(*) as cnt, min(v1) as mn, max(v1) as mx+FROM generate_series(1, 100000) AS t1(v1)+INNER JOIN generate_series(1, 1) AS t2(v2)+ ON (t1.v1 + t2.v2) > 0+----+100000 1 100000++# --- Verify spill metrics via EXPLAIN ANALYZE ---+# The NestedLoopJoinExec line should show spill_count=1, confirming+# the memory-limited fallback path was taken and right side was spilled.+query TT+EXPLAIN ANALYZE SELECT count(*)+FROM generate_series(1, 100000) AS t1(v1)+INNER JOIN generate_series(1, 1) AS t2(v2)+ ON (t1.v1 + t2.v2) > 0+----+Plan with Metrics+01)ProjectionExec: expr=[count(Int64(1))@0 as count(*)], metrics=[<slt:ignore>]+02)--AggregateExec: mode=Single, gby=[], aggr=[count(Int64(1))], metrics=[<slt:ignore>]+03)----NestedLoopJoinExec: join_type=Inner, filter=v1@0 + v2@1 > 0, projection=[], metrics=[output_rows=100.0 K, <slt:ignore> spill_count=1, <slt:ignore>]+04)------ProjectionExec: expr=[value@0 as v1], metrics=[<slt:ignore>]+05)--------LazyMemoryExec: partitions=1, batch_generators=[generate_series: start=1, end=100000, batch_size=8192], metrics=[<slt:ignore>]+06)------ProjectionExec: expr=[value@0 as v2], metrics=[<slt:ignore>]+07)--------LazyMemoryExec: partitions=1, batch_generators=[generate_series: start=1, end=1, batch_size=8192], metrics=[<slt:ignore>]++# Restore settings to slt runner defaults+statement ok+RESET datafusion.runtime.memory_limit++statement ok+SET datafusion.execution.target_partitions = 4++statement ok+RESET datafusion.catalog.create_default_catalog_and_schema