Skip to content

Apache DataFusion SQL Query Engine

Handle canceled partitioned hash join dynamic filters lazily (#21666)

Adrian Garcia Badaracco88759566065f
diff --git a/datafusion/physical-plan/src/joins/hash_join/exec.rs b/datafusion/physical-plan/src/joins/hash_join/exec.rs
index 735375441f..0eca270ebb 100644
--- a/datafusion/physical-plan/src/joins/hash_join/exec.rs
+++ b/datafusion/physical-plan/src/joins/hash_join/exec.rs
@@ -1316,6 +1316,33 @@ impl ExecutionPlan for HashJoinExec {
.with_category(MetricCategory::Rows)
.counter(ARRAY_MAP_CREATED_COUNT_METRIC_NAME, partition);
+ // Initialize build_accumulator lazily with runtime partition counts (only if enabled)
+ // Use RepartitionExec's random state (seeds: 0,0,0,0) for partition routing
+ let repartition_random_state = REPARTITION_RANDOM_STATE;
+ let build_accumulator = enable_dynamic_filter_pushdown
+ .then(|| {
+ self.dynamic_filter.as_ref().map(|df| {
+ let filter = Arc::clone(&df.filter);
+ let on_right = self
+ .on
+ .iter()
+ .map(|(_, right_expr)| Arc::clone(right_expr))
+ .collect::<Vec<_>>();
+ Some(Arc::clone(df.build_accumulator.get_or_init(|| {
+ Arc::new(SharedBuildAccumulator::new_from_partition_mode(
+ self.mode,
+ self.left.as_ref(),
+ self.right.as_ref(),
+ filter,
+ on_right,
+ repartition_random_state,
+ ))
+ })))
+ })
+ })
+ .flatten()
+ .flatten();
+
let left_fut = match self.mode {
PartitionMode::CollectLeft => self.left_fut.try_once(|| {
let left_stream = self.left.execute(0, Arc::clone(&context))?;
@@ -1343,7 +1370,6 @@ impl ExecutionPlan for HashJoinExec {
let reservation =
MemoryConsumer::new(format!("HashJoinInput[{partition}]"))
.register(context.memory_pool());
-
OnceFut::new(collect_left_input(
self.random_state.random_state().clone(),
left_stream,
@@ -1368,33 +1394,6 @@ impl ExecutionPlan for HashJoinExec {
let batch_size = context.session_config().batch_size();
- // Initialize build_accumulator lazily with runtime partition counts (only if enabled)
- // Use RepartitionExec's random state (seeds: 0,0,0,0) for partition routing
- let repartition_random_state = REPARTITION_RANDOM_STATE;
- let build_accumulator = enable_dynamic_filter_pushdown
- .then(|| {
- self.dynamic_filter.as_ref().map(|df| {
- let filter = Arc::clone(&df.filter);
- let on_right = self
- .on
- .iter()
- .map(|(_, right_expr)| Arc::clone(right_expr))
- .collect::<Vec<_>>();
- Some(Arc::clone(df.build_accumulator.get_or_init(|| {
- Arc::new(SharedBuildAccumulator::new_from_partition_mode(
- self.mode,
- self.left.as_ref(),
- self.right.as_ref(),
- filter,
- on_right,
- repartition_random_state,
- ))
- })))
- })
- })
- .flatten()
- .flatten();
-
// we have the batches and the hash map with their keys. We can how create a stream
// over the right that uses this information to issue new batches.
let right_stream = self.right.execute(partition, context)?;
@@ -2347,6 +2346,22 @@ mod tests {
right: Arc<dyn ExecutionPlan>,
on: JoinOn,
join_type: JoinType,
+ ) -> Result<(HashJoinExec, Arc<DynamicFilterPhysicalExpr>)> {
+ hash_join_with_dynamic_filter_and_mode(
+ left,
+ right,
+ on,
+ join_type,
+ PartitionMode::CollectLeft,
+ )
+ }
+
+ fn hash_join_with_dynamic_filter_and_mode(
+ left: Arc<dyn ExecutionPlan>,
+ right: Arc<dyn ExecutionPlan>,
+ on: JoinOn,
+ join_type: JoinType,
+ mode: PartitionMode,
) -> Result<(HashJoinExec, Arc<DynamicFilterPhysicalExpr>)> {
let dynamic_filter = HashJoinExec::create_dynamic_filter(&on);
let mut join = HashJoinExec::try_new(
@@ -2356,7 +2371,7 @@ mod tests {
None,
&join_type,
None,
- PartitionMode::CollectLeft,
+ mode,
NullEquality::NullEqualsNothing,
false,
)?;
@@ -5628,6 +5643,158 @@ mod tests {
Ok(())
}
+ #[tokio::test]
+ async fn test_partitioned_dynamic_filter_reports_empty_canceled_partitions()
+ -> Result<()> {
+ let mut session_config = SessionConfig::default();
+ session_config
+ .options_mut()
+ .optimizer
+ .enable_dynamic_filter_pushdown = true;
+ let task_ctx =
+ Arc::new(TaskContext::default().with_session_config(session_config));
+
+ let child_left_schema = Arc::new(Schema::new(vec![
+ Field::new("child_left_payload", DataType::Int32, false),
+ Field::new("child_key", DataType::Int32, false),
+ Field::new("child_left_extra", DataType::Int32, false),
+ ]));
+ let child_right_schema = Arc::new(Schema::new(vec![
+ Field::new("child_right_payload", DataType::Int32, false),
+ Field::new("child_right_key", DataType::Int32, false),
+ Field::new("child_right_extra", DataType::Int32, false),
+ ]));
+ let parent_left_schema = Arc::new(Schema::new(vec![
+ Field::new("parent_payload", DataType::Int32, false),
+ Field::new("parent_key", DataType::Int32, false),
+ Field::new("parent_extra", DataType::Int32, false),
+ ]));
+
+ let child_left: Arc<dyn ExecutionPlan> = TestMemoryExec::try_new_exec(
+ &[
+ vec![build_table_i32(
+ ("child_left_payload", &vec![10]),
+ ("child_key", &vec![0]),
+ ("child_left_extra", &vec![100]),
+ )],
+ vec![build_table_i32(
+ ("child_left_payload", &vec![11]),
+ ("child_key", &vec![1]),
+ ("child_left_extra", &vec![101]),
+ )],
+ vec![build_table_i32(
+ ("child_left_payload", &vec![12]),
+ ("child_key", &vec![2]),
+ ("child_left_extra", &vec![102]),
+ )],
+ vec![build_table_i32(
+ ("child_left_payload", &vec![13]),
+ ("child_key", &vec![3]),
+ ("child_left_extra", &vec![103]),
+ )],
+ ],
+ Arc::clone(&child_left_schema),
+ None,
+ )?;
+ let child_right: Arc<dyn ExecutionPlan> = TestMemoryExec::try_new_exec(
+ &[
+ vec![build_table_i32(
+ ("child_right_payload", &vec![20]),
+ ("child_right_key", &vec![0]),
+ ("child_right_extra", &vec![200]),
+ )],
+ vec![build_table_i32(
+ ("child_right_payload", &vec![21]),
+ ("child_right_key", &vec![1]),
+ ("child_right_extra", &vec![201]),
+ )],
+ vec![build_table_i32(
+ ("child_right_payload", &vec![22]),
+ ("child_right_key", &vec![2]),
+ ("child_right_extra", &vec![202]),
+ )],
+ vec![build_table_i32(
+ ("child_right_payload", &vec![23]),
+ ("child_right_key", &vec![3]),
+ ("child_right_extra", &vec![203]),
+ )],
+ ],
+ Arc::clone(&child_right_schema),
+ None,
+ )?;
+ let parent_left: Arc<dyn ExecutionPlan> = TestMemoryExec::try_new_exec(
+ &[
+ vec![build_table_i32(
+ ("parent_payload", &vec![30]),
+ ("parent_key", &vec![0]),
+ ("parent_extra", &vec![300]),
+ )],
+ vec![RecordBatch::new_empty(Arc::clone(&parent_left_schema))],
+ vec![build_table_i32(
+ ("parent_payload", &vec![32]),
+ ("parent_key", &vec![2]),
+ ("parent_extra", &vec![302]),
+ )],
+ vec![RecordBatch::new_empty(Arc::clone(&parent_left_schema))],
+ ],
+ Arc::clone(&parent_left_schema),
+ None,
+ )?;
+
+ let child_on = vec![(
+ Arc::new(Column::new_with_schema("child_key", &child_left_schema)?) as _,
+ Arc::new(Column::new_with_schema(
+ "child_right_key",
+ &child_right_schema,
+ )?) as _,
+ )];
+ let (child_join, _child_dynamic_filter) = hash_join_with_dynamic_filter_and_mode(
+ child_left,
+ child_right,
+ child_on,
+ JoinType::Inner,
+ PartitionMode::Partitioned,
+ )?;
+ let child_join: Arc<dyn ExecutionPlan> = Arc::new(child_join);
+
+ let parent_on = vec![(
+ Arc::new(Column::new_with_schema("parent_key", &parent_left_schema)?) as _,
+ Arc::new(Column::new_with_schema("child_key", &child_join.schema())?) as _,
+ )];
+ let parent_join = HashJoinExec::try_new(
+ parent_left,
+ child_join,
+ parent_on,
+ None,
+ &JoinType::RightSemi,
+ None,
+ PartitionMode::Partitioned,
+ NullEquality::NullEqualsNothing,
+ false,
+ )?;
+
+ let batches = tokio::time::timeout(
+ std::time::Duration::from_secs(5),
+ crate::execution_plan::collect(Arc::new(parent_join), task_ctx),
+ )
+ .await
+ .expect("partitioned right-semi join should not hang")?;
+
+ assert_batches_sorted_eq!(
+ [
+ "+--------------------+-----------+------------------+---------------------+-----------------+-------------------+",
+ "| child_left_payload | child_key | child_left_extra | child_right_payload | child_right_key | child_right_extra |",
+ "+--------------------+-----------+------------------+---------------------+-----------------+-------------------+",
+ "| 10 | 0 | 100 | 20 | 0 | 200 |",
+ "| 12 | 2 | 102 | 22 | 2 | 202 |",
+ "+--------------------+-----------+------------------+---------------------+-----------------+-------------------+",
+ ],
+ &batches
+ );
+
+ Ok(())
+ }
+
#[tokio::test]
async fn test_hash_join_skips_probe_on_empty_build_after_partition_bounds_report()
-> Result<()> {
diff --git a/datafusion/physical-plan/src/joins/hash_join/shared_bounds.rs b/datafusion/physical-plan/src/joins/hash_join/shared_bounds.rs
index f32dc7fa80..23ca14f5ba 100644
--- a/datafusion/physical-plan/src/joins/hash_join/shared_bounds.rs
+++ b/datafusion/physical-plan/src/joins/hash_join/shared_bounds.rs
@@ -33,7 +33,7 @@ use crate::joins::hash_join::partitioned_hash_eval::{
use arrow::array::ArrayRef;
use arrow::datatypes::{DataType, Field, Schema};
use datafusion_common::config::ConfigOptions;
-use datafusion_common::{Result, ScalarValue};
+use datafusion_common::{DataFusionError, Result, ScalarValue, SharedResult};
use datafusion_expr::Operator;
use datafusion_functions::core::r#struct as struct_func;
use datafusion_physical_expr::expressions::{
@@ -42,7 +42,7 @@ use datafusion_physical_expr::expressions::{
use datafusion_physical_expr::{PhysicalExpr, PhysicalExprRef, ScalarFunctionExpr};
use parking_lot::Mutex;
-use tokio::sync::Barrier;
+use tokio::sync::Notify;
/// Represents the minimum and maximum values for a specific column.
/// Used in dynamic filter pushdown to establish value boundaries.
@@ -183,6 +183,25 @@ fn create_bounds_predicate(
}
}
+/// Combines a membership predicate and a bounds predicate with logical AND.
+///
+/// Returns `None` when neither is available; callers decide the fallback (e.g.
+/// skip updating the filter vs. emit a `lit(true)` branch inside a CASE).
+fn combine_membership_and_bounds(
+ membership_expr: Option<Arc<dyn PhysicalExpr>>,
+ bounds_expr: Option<Arc<dyn PhysicalExpr>>,
+) -> Option<Arc<dyn PhysicalExpr>> {
+ match (membership_expr, bounds_expr) {
+ (Some(membership), Some(bounds)) => {
+ Some(Arc::new(BinaryExpr::new(bounds, Operator::And, membership))
+ as Arc<dyn PhysicalExpr>)
+ }
+ (Some(membership), None) => Some(membership),
+ (None, Some(bounds)) => Some(bounds),
+ (None, None) => None,
+ }
+}
+
/// Coordinates build-side information collection across multiple partitions
///
/// This structure collects information from the build side (hash tables and/or bounds) and
@@ -193,9 +212,12 @@ fn create_bounds_predicate(
/// ## Synchronization Strategy
///
/// 1. Each partition computes information from its build-side data (hash maps and/or bounds)
-/// 2. Information is stored in the shared state
-/// 3. A barrier tracks how many partitions have reported
-/// 4. When the last partition reports, information is merged and the filter is updated exactly once
+/// 2. Information is stored in the shared state, which tracks how many partitions have reported
+/// 3. When the last partition reports, one waiter is elected as the finalizer; it merges the
+/// collected information, updates the dynamic filter exactly once, and publishes the
+/// terminal result by transitioning [`CompletionState`] to `Ready`
+/// 4. A [`tokio::sync::Notify`] wakes any other partitions parked in `wait_for_completion`,
+/// which then observe the `Ready` state under the mutex and return immediately
///
/// ## Hash Map vs Bounds
///
@@ -215,8 +237,14 @@ fn create_bounds_predicate(
/// partition executions.
pub(crate) struct SharedBuildAccumulator {
/// Build-side data protected by a single mutex to avoid ordering concerns
- inner: Mutex<AccumulatedBuildData>,
- barrier: Barrier,
+ inner: Mutex<AccumulatorState>,
+ /// Wakes every partition that is parked in [`Self::wait_for_completion`]
+ /// once [`AccumulatorState::completion`] transitions to
+ /// [`CompletionState::Ready`]. Notifications are fired once per
+ /// accumulator lifetime (the elected finalizer publishes the terminal
+ /// result, then broadcasts), so late subscribers simply re-check the
+ /// state under the mutex and return immediately.
+ completion_notify: Notify,
/// Dynamic filter for pushdown to probe side
dynamic_filter: Arc<DynamicFilterPhysicalExpr>,
/// Right side join expressions needed for creating filter expressions
@@ -262,13 +290,40 @@ struct PartitionData {
/// Build-side data organized by partition mode
enum AccumulatedBuildData {
Partitioned {
- partitions: Vec<Option<PartitionData>>,
+ partitions: Vec<PartitionStatus>,
+ completed_partitions: usize,
},
CollectLeft {
- data: Option<PartitionData>,
+ data: PartitionStatus,
+ reported_count: usize,
+ expected_reports: usize,
},
}
+enum CompletionState {
+ Pending,
+ Finalizing,
+ Ready(SharedResult<()>),
+}
+
+struct AccumulatorState {
+ data: AccumulatedBuildData,
+ completion: CompletionState,
+}
+
+#[derive(Clone)]
+enum PartitionStatus {
+ Pending,
+ Reported(PartitionData),
+ CanceledUnknown,
+}
+
+#[derive(Clone)]
+enum FinalizeInput {
+ Partitioned(Vec<PartitionStatus>),
+ CollectLeft(PartitionStatus),
+}
+
impl SharedBuildAccumulator {
/// Creates a new SharedBuildAccumulator configured for the given partition mode
///
@@ -323,21 +378,27 @@ impl SharedBuildAccumulator {
let mode_data = match partition_mode {
PartitionMode::Partitioned => AccumulatedBuildData::Partitioned {
partitions: vec![
- None;
+ PartitionStatus::Pending;
left_child.output_partitioning().partition_count()
],
+ completed_partitions: 0,
+ },
+ PartitionMode::CollectLeft => AccumulatedBuildData::CollectLeft {
+ data: PartitionStatus::Pending,
+ reported_count: 0,
+ expected_reports: expected_calls,
},
- PartitionMode::CollectLeft => {
- AccumulatedBuildData::CollectLeft { data: None }
- }
PartitionMode::Auto => unreachable!(
"PartitionMode::Auto should not be present at execution time. This is a bug in DataFusion, please report it!"
),
};
Self {
- inner: Mutex::new(mode_data),
- barrier: Barrier::new(expected_calls),
+ inner: Mutex::new(AccumulatorState {
+ data: mode_data,
+ completion: CompletionState::Pending,
+ }),
+ completion_notify: Notify::new(),
dynamic_filter,
on_right,
repartition_random_state,
@@ -358,229 +419,273 @@ impl SharedBuildAccumulator {
/// # Returns
/// * `Result<()>` - Ok if successful, Err if filter update failed or mode mismatch
pub(crate) async fn report_build_data(&self, data: PartitionBuildData) -> Result<()> {
- // Store data in the accumulator
- {
+ let finalize_input = {
let mut guard = self.inner.lock();
+ self.store_build_data(&mut guard, data)?;
+ self.take_finalize_input_if_ready(&mut guard)
+ };
- match (data, &mut *guard) {
- // Partitioned mode
- (
- PartitionBuildData::Partitioned {
- partition_id,
- pushdown,
- bounds,
- },
- AccumulatedBuildData::Partitioned { partitions },
- ) => {
- partitions[partition_id] = Some(PartitionData { pushdown, bounds });
- }
- // CollectLeft mode (store once, deduplicate across partitions)
- (
- PartitionBuildData::CollectLeft { pushdown, bounds },
- AccumulatedBuildData::CollectLeft { data },
- ) => {
- // Deduplicate - all partitions report the same data in CollectLeft
- if data.is_none() {
- *data = Some(PartitionData { pushdown, bounds });
- }
+ if let Some(finalize_input) = finalize_input {
+ self.finish(finalize_input);
+ }
+
+ self.wait_for_completion().await
+ }
+
+ pub(crate) fn report_canceled_partition(&self, partition_id: usize) {
+ let finalize_input = {
+ let mut guard = self.inner.lock();
+ self.store_canceled_partition(&mut guard, partition_id);
+ self.take_finalize_input_if_ready(&mut guard)
+ };
+
+ if let Some(finalize_input) = finalize_input {
+ self.finish(finalize_input);
+ }
+ }
+
+ fn store_build_data(
+ &self,
+ guard: &mut AccumulatorState,
+ data: PartitionBuildData,
+ ) -> Result<()> {
+ match (data, &mut guard.data) {
+ (
+ PartitionBuildData::Partitioned {
+ partition_id,
+ pushdown,
+ bounds,
+ },
+ AccumulatedBuildData::Partitioned {
+ partitions,
+ completed_partitions,
+ },
+ ) => {
+ if matches!(partitions[partition_id], PartitionStatus::Pending) {
+ *completed_partitions += 1;
}
- // Mismatched modes - should never happen
- _ => {
- return datafusion_common::internal_err!(
- "Build data mode mismatch in report_build_data"
- );
+ partitions[partition_id] =
+ PartitionStatus::Reported(PartitionData { pushdown, bounds });
+ }
+ (
+ PartitionBuildData::CollectLeft { pushdown, bounds },
+ AccumulatedBuildData::CollectLeft {
+ data,
+ reported_count,
+ ..
+ },
+ ) => {
+ if matches!(data, PartitionStatus::Pending) {
+ *data = PartitionStatus::Reported(PartitionData { pushdown, bounds });
}
+ *reported_count += 1;
+ }
+ _ => {
+ return datafusion_common::internal_err!(
+ "Build data mode mismatch in report_build_data"
+ );
}
}
+ Ok(())
+ }
- // Wait for all partitions to report
- if self.barrier.wait().await.is_leader() {
- // All partitions have reported, so we can create and update the filter
- let inner = self.inner.lock();
-
- match &*inner {
- // CollectLeft: Simple conjunction of bounds and membership check
- AccumulatedBuildData::CollectLeft { data } => {
- if let Some(partition_data) = data {
- // Create membership predicate (InList for small build sides, hash lookup otherwise)
- let membership_expr = create_membership_predicate(
- &self.on_right,
- partition_data.pushdown.clone(),
- &HASH_JOIN_SEED,
- self.probe_schema.as_ref(),
- )?;
-
- // Create bounds check expression (if bounds available)
- let bounds_expr = create_bounds_predicate(
- &self.on_right,
- &partition_data.bounds,
- );
-
- // Combine membership and bounds expressions for multi-layer optimization:
- // - Bounds (min/max): Enable statistics-based pruning (Parquet row group/file skipping)
- // - Membership (InList/hash lookup): Enables:
- // * Precise filtering (exact value matching)
- // * Bloom filter utilization (if present in Parquet files)
- // * Better pruning for data types where min/max isn't effective (e.g., UUIDs)
- // Together, they provide complementary benefits and maximize data skipping.
- // Only update the filter if we have something to push down
- if let Some(filter_expr) = match (membership_expr, bounds_expr) {
- (Some(membership), Some(bounds)) => {
- // Both available: combine with AND
- Some(Arc::new(BinaryExpr::new(
- bounds,
- Operator::And,
- membership,
- ))
- as Arc<dyn PhysicalExpr>)
- }
- (Some(membership), None) => {
- // Membership available but no bounds
- // This is reachable when we have data but bounds aren't available
- // (e.g., unsupported data types or no columns with bounds)
- Some(membership)
- }
- (None, Some(bounds)) => {
- // Bounds available but no membership.
- // This should be unreachable in practice: we can always push down a reference
- // to the hash table.
- // But it seems safer to handle it defensively.
- Some(bounds)
- }
- (None, None) => {
- // No filter available (e.g., empty build side)
- // Don't update the filter, but continue to mark complete
- None
- }
- } {
- self.dynamic_filter.update(filter_expr)?;
- }
+ fn store_canceled_partition(
+ &self,
+ guard: &mut AccumulatorState,
+ partition_id: usize,
+ ) {
+ if let AccumulatedBuildData::Partitioned {
+ partitions,
+ completed_partitions,
+ } = &mut guard.data
+ && matches!(partitions[partition_id], PartitionStatus::Pending)
+ {
+ partitions[partition_id] = PartitionStatus::CanceledUnknown;
+ *completed_partitions += 1;
+ }
+ }
+
+ fn take_finalize_input_if_ready(
+ &self,
+ guard: &mut AccumulatorState,
+ ) -> Option<FinalizeInput> {
+ if !matches!(guard.completion, CompletionState::Pending) {
+ return None;
+ }
+
+ let finalize_input = match &guard.data {
+ AccumulatedBuildData::Partitioned {
+ partitions,
+ completed_partitions,
+ } if *completed_partitions == partitions.len() => {
+ Some(FinalizeInput::Partitioned(partitions.clone()))
+ }
+ AccumulatedBuildData::CollectLeft {
+ data,
+ reported_count,
+ expected_reports,
+ } if *reported_count == *expected_reports => {
+ Some(FinalizeInput::CollectLeft(data.clone()))
+ }
+ _ => None,
+ }?;
+
+ guard.completion = CompletionState::Finalizing;
+ Some(finalize_input)
+ }
+
+ fn finish(&self, finalize_input: FinalizeInput) {
+ let result = self.build_filter(finalize_input).map_err(Arc::new);
+ self.dynamic_filter.mark_complete();
+
+ let mut guard = self.inner.lock();
+ guard.completion = CompletionState::Ready(result);
+ drop(guard);
+ self.completion_notify.notify_waiters();
+ }
+
+ async fn wait_for_completion(&self) -> Result<()> {
+ loop {
+ let notified = {
+ let guard = self.inner.lock();
+ match &guard.completion {
+ CompletionState::Ready(Ok(())) => return Ok(()),
+ CompletionState::Ready(Err(err)) => {
+ return Err(DataFusionError::Shared(Arc::clone(err)));
+ }
+ CompletionState::Pending | CompletionState::Finalizing => {
+ self.completion_notify.notified()
}
}
- // Partitioned: CASE expression routing to per-partition filters
- AccumulatedBuildData::Partitioned { partitions } => {
- // Collect all partition data (should all be Some at this point)
- let partition_data: Vec<_> =
- partitions.iter().filter_map(|p| p.as_ref()).collect();
-
- if !partition_data.is_empty() {
- // Build a CASE expression that combines range checks AND membership checks
- // CASE (hash_repartition(join_keys) % num_partitions)
- // WHEN 0 THEN (col >= min_0 AND col <= max_0 AND ...) AND membership_check_0
- // WHEN 1 THEN (col >= min_1 AND col <= max_1 AND ...) AND membership_check_1
- // ...
- // ELSE false
- // END
-
- let num_partitions = partition_data.len();
-
- // Create base expression: hash_repartition(join_keys) % num_partitions
- let routing_hash_expr = Arc::new(HashExpr::new(
- self.on_right.clone(),
- self.repartition_random_state.clone(),
- "hash_repartition".to_string(),
- ))
- as Arc<dyn PhysicalExpr>;
-
- let modulo_expr = Arc::new(BinaryExpr::new(
- routing_hash_expr,
- Operator::Modulo,
- lit(ScalarValue::UInt64(Some(num_partitions as u64))),
- ))
- as Arc<dyn PhysicalExpr>;
-
- // Create WHEN branches for each partition
- let when_then_branches: Vec<(
- Arc<dyn PhysicalExpr>,
- Arc<dyn PhysicalExpr>,
- )> = partitions
- .iter()
- .enumerate()
- .filter_map(|(partition_id, partition_opt)| {
- partition_opt.as_ref().and_then(|partition| {
- // Skip empty partitions - they would always return false anyway
- match &partition.pushdown {
- PushdownStrategy::Empty => None,
- _ => Some((partition_id, partition)),
- }
- })
- })
- .map(|(partition_id, partition)| -> Result<_> {
- // WHEN partition_id
- let when_expr =
- lit(ScalarValue::UInt64(Some(partition_id as u64)));
-
- // THEN: Combine bounds check AND membership predicate
-
- // 1. Create membership predicate (InList for small build sides, hash lookup otherwise)
- let membership_expr = create_membership_predicate(
- &self.on_right,
- partition.pushdown.clone(),
- &HASH_JOIN_SEED,
- self.probe_schema.as_ref(),
- )?;
-
- // 2. Create bounds check expression for this partition (if bounds available)
- let bounds_expr = create_bounds_predicate(
- &self.on_right,
- &partition.bounds,
- );
-
- // 3. Combine membership and bounds expressions
- let then_expr = match (membership_expr, bounds_expr) {
- (Some(membership), Some(bounds)) => {
- // Both available: combine with AND
- Arc::new(BinaryExpr::new(
- bounds,
- Operator::And,
- membership,
- ))
- as Arc<dyn PhysicalExpr>
- }
- (Some(membership), None) => {
- // Membership available but no bounds (e.g., unsupported data types)
- membership
- }
- (None, Some(bounds)) => {
- // Bounds available but no membership.
- // This should be unreachable in practice: we can always push down a reference
- // to the hash table.
- // But it seems safer to handle it defensively.
- bounds
- }
- (None, None) => {
- // No filter for this partition - should not happen due to filter_map above
- // but handle defensively by returning a "true" literal
- lit(true)
- }
- };
-
- Ok((when_expr, then_expr))
- })
- .collect::<Result<Vec<_>>>()?;
-
- // Optimize for single partition: skip CASE expression entirely
- let filter_expr = if when_then_branches.is_empty() {
- // All partitions are empty: no rows can match
- lit(false)
- } else if when_then_branches.len() == 1 {
- // Single partition: just use the condition directly
- // since hash % 1 == 0 always, the WHEN 0 branch will always match
- Arc::clone(&when_then_branches[0].1)
- } else {
- // Multiple partitions: create CASE expression
- Arc::new(CaseExpr::try_new(
- Some(modulo_expr),
- when_then_branches,
- Some(lit(false)), // ELSE false
- )?) as Arc<dyn PhysicalExpr>
- };
+ };
+ notified.await;
+ }
+ }
+ fn build_filter(&self, finalize_input: FinalizeInput) -> Result<()> {
+ match finalize_input {
+ FinalizeInput::CollectLeft(partition) => match partition {
+ PartitionStatus::Reported(partition_data) => {
+ let membership_expr = create_membership_predicate(
+ &self.on_right,
+ partition_data.pushdown.clone(),
+ &HASH_JOIN_SEED,
+ self.probe_schema.as_ref(),
+ )?;
+ let bounds_expr =
+ create_bounds_predicate(&self.on_right, &partition_data.bounds);
+
+ if let Some(filter_expr) =
+ combine_membership_and_bounds(membership_expr, bounds_expr)
+ {
self.dynamic_filter.update(filter_expr)?;
}
}
+ PartitionStatus::Pending => {
+ return datafusion_common::internal_err!(
+ "attempted to finalize collect-left dynamic filter without reported build data"
+ );
+ }
+ PartitionStatus::CanceledUnknown => {
+ return datafusion_common::internal_err!(
+ "collect-left dynamic filter cannot finalize with canceled build data"
+ );
+ }
+ },
+ FinalizeInput::Partitioned(partitions) => {
+ let num_partitions = partitions.len();
+ let routing_hash_expr = Arc::new(HashExpr::new(
+ self.on_right.clone(),
+ self.repartition_random_state.clone(),
+ "hash_repartition".to_string(),
+ )) as Arc<dyn PhysicalExpr>;
+
+ let modulo_expr = Arc::new(BinaryExpr::new(
+ routing_hash_expr,
+ Operator::Modulo,
+ lit(ScalarValue::UInt64(Some(num_partitions as u64))),
+ )) as Arc<dyn PhysicalExpr>;
+
+ let mut real_branches = Vec::new();
+ let mut empty_partition_ids = Vec::new();
+ let mut has_canceled_unknown = false;
+
+ for (partition_id, partition) in partitions.iter().enumerate() {
+ match partition {
+ PartitionStatus::Reported(partition)
+ if matches!(partition.pushdown, PushdownStrategy::Empty) =>
+ {
+ empty_partition_ids.push(partition_id);
+ }
+ PartitionStatus::Reported(partition) => {
+ let membership_expr = create_membership_predicate(
+ &self.on_right,
+ partition.pushdown.clone(),
+ &HASH_JOIN_SEED,
+ self.probe_schema.as_ref(),
+ )?;
+ let bounds_expr = create_bounds_predicate(
+ &self.on_right,
+ &partition.bounds,
+ );
+ let then_expr = combine_membership_and_bounds(
+ membership_expr,
+ bounds_expr,
+ )
+ .unwrap_or_else(|| lit(true));
+ real_branches.push((
+ lit(ScalarValue::UInt64(Some(partition_id as u64))),
+ then_expr,
+ ));
+ }
+ PartitionStatus::CanceledUnknown => {
+ has_canceled_unknown = true;
+ }
+ PartitionStatus::Pending => {
+ return datafusion_common::internal_err!(
+ "attempted to finalize dynamic filter with pending partition"
+ );
+ }
+ }
+ }
+
+ let filter_expr = if has_canceled_unknown {
+ let mut when_then_branches = empty_partition_ids
+ .into_iter()
+ .map(|partition_id| {
+ (
+ lit(ScalarValue::UInt64(Some(partition_id as u64))),
+ lit(false),
+ )
+ })
+ .collect::<Vec<_>>();
+ when_then_branches.extend(real_branches);
+
+ if when_then_branches.is_empty() {
+ lit(true)
+ } else {
+ Arc::new(CaseExpr::try_new(
+ Some(modulo_expr),
+ when_then_branches,
+ Some(lit(true)),
+ )?) as Arc<dyn PhysicalExpr>
+ }
+ } else if real_branches.is_empty() {
+ lit(false)
+ } else if real_branches.len() == 1
+ && empty_partition_ids.len() + 1 == num_partitions
+ {
+ Arc::clone(&real_branches[0].1)
+ } else {
+ Arc::new(CaseExpr::try_new(
+ Some(modulo_expr),
+ real_branches,
+ Some(lit(false)),
+ )?) as Arc<dyn PhysicalExpr>
+ };
+
+ self.dynamic_filter.update(filter_expr)?;
}
- self.dynamic_filter.mark_complete();
}
Ok(())
@@ -592,3 +697,100 @@ impl fmt::Debug for SharedBuildAccumulator {
write!(f, "SharedBuildAccumulator")
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn make_partitioned_accumulator(num_partitions: usize) -> SharedBuildAccumulator {
+ let probe_schema = Arc::new(Schema::new(vec![Field::new(
+ "probe_key",
+ DataType::Int32,
+ false,
+ )]));
+ let dynamic_filter = Arc::new(DynamicFilterPhysicalExpr::new(vec![], lit(true)));
+ SharedBuildAccumulator {
+ inner: Mutex::new(AccumulatorState {
+ data: AccumulatedBuildData::Partitioned {
+ partitions: vec![PartitionStatus::Pending; num_partitions],
+ completed_partitions: 0,
+ },
+ completion: CompletionState::Pending,
+ }),
+ completion_notify: Notify::new(),
+ dynamic_filter,
+ on_right: vec![],
+ repartition_random_state: SeededRandomState::with_seed(1),
+ probe_schema,
+ }
+ }
+
+ fn partitioned_state(acc: &SharedBuildAccumulator) -> (Vec<PartitionStatus>, usize) {
+ let guard = acc.inner.lock();
+ let AccumulatedBuildData::Partitioned {
+ partitions,
+ completed_partitions,
+ } = &guard.data
+ else {
+ panic!("expected partitioned accumulator");
+ };
+ (partitions.clone(), *completed_partitions)
+ }
+
+ // Regression guard for the build-report lifecycle fix: on `Drop`, a stream
+ // in `BuildReportState::ReportScheduled` still calls `report_canceled_partition`
+ // because it cannot tell whether the coordinator has already observed the
+ // report (first poll of the `OnceFut` runs `store_build_data` synchronously
+ // before the future's first `.await`, but the stream doesn't learn that
+ // until `get_shared` returns `Ok`). Correctness therefore relies on
+ // `store_canceled_partition` being a no-op when the partition is already
+ // `Reported`. This test pins that invariant.
+ #[test]
+ fn report_canceled_partition_is_noop_after_report() {
+ let acc = make_partitioned_accumulator(2);
+
+ {
+ let mut guard = acc.inner.lock();
+ acc.store_build_data(
+ &mut guard,
+ PartitionBuildData::Partitioned {
+ partition_id: 0,
+ pushdown: PushdownStrategy::Empty,
+ bounds: PartitionBounds::new(vec![]),
+ },
+ )
+ .unwrap();
+ }
+ let (partitions, completed) = partitioned_state(&acc);
+ assert!(matches!(partitions[0], PartitionStatus::Reported(_)));
+ assert_eq!(completed, 1);
+
+ acc.report_canceled_partition(0);
+ let (partitions, completed) = partitioned_state(&acc);
+ assert!(
+ matches!(partitions[0], PartitionStatus::Reported(_)),
+ "late cancel must not overwrite a prior Reported status"
+ );
+ assert_eq!(completed, 1, "late cancel must not double-count completion");
+ }
+
+ // Drop from the `NotReported` (or first-poll-never-ran) state must
+ // transition `Pending` -> `CanceledUnknown` and bump `completed_partitions`,
+ // which is what unblocks sibling partitions waiting on the coordinator.
+ #[test]
+ fn report_canceled_partition_marks_pending_partition_canceled() {
+ let acc = make_partitioned_accumulator(2);
+
+ acc.report_canceled_partition(0);
+ let (partitions, completed) = partitioned_state(&acc);
+ assert!(matches!(partitions[0], PartitionStatus::CanceledUnknown));
+ assert_eq!(completed, 1);
+
+ // Idempotent: a second cancel (e.g. a stray double-drop) must not
+ // double-count completion.
+ acc.report_canceled_partition(0);
+ let (partitions, completed) = partitioned_state(&acc);
+ assert!(matches!(partitions[0], PartitionStatus::CanceledUnknown));
+ assert_eq!(completed, 1);
+ }
+}
diff --git a/datafusion/physical-plan/src/joins/hash_join/stream.rs b/datafusion/physical-plan/src/joins/hash_join/stream.rs
index 1004fba3d4..9885fb5c5c 100644
--- a/datafusion/physical-plan/src/joins/hash_join/stream.rs
+++ b/datafusion/physical-plan/src/joins/hash_join/stream.rs
@@ -170,6 +170,19 @@ impl ProcessProbeBatchState {
}
}
+/// Lifecycle of this partition's build-data report to the shared coordinator.
+///
+/// `ReportScheduled` means the reporting `OnceFut` has been constructed but is
+/// lazy: the coordinator has not yet observed the report. Only `ReportDelivered`
+/// guarantees the coordinator saw it, so `Drop` must still cancel the partition
+/// when the state is `ReportScheduled` — otherwise sibling partitions wait
+/// forever for a report that never runs.
+enum BuildReportState {
+ NotReported,
+ ReportScheduled,
+ ReportDelivered,
+}
+
/// [`Stream`] for [`super::HashJoinExec`] that does the actual join.
///
/// This stream:
@@ -219,6 +232,8 @@ pub(super) struct HashJoinStream {
/// Optional future to signal when build information has been reported by all partitions
/// and the dynamic filter has been updated
build_waiter: Option<OnceFut<()>>,
+ /// Tracks where this partition is in the build-data reporting lifecycle.
+ build_report_state: BuildReportState,
/// Partitioning mode to use
mode: PartitionMode,
/// Output buffer for coalescing small batches into larger ones with optional fetch limit.
@@ -400,6 +415,7 @@ impl HashJoinStream {
right_side_ordered,
build_accumulator,
build_waiter: None,
+ build_report_state: BuildReportState::NotReported,
mode,
output_buffer,
null_aware,
@@ -421,6 +437,49 @@ impl HashJoinStream {
}
}
+ /// Transitions state after build-side data has been collected, automatically
+ /// reporting build data to the accumulator when one is present.
+ ///
+ /// If a `build_accumulator` is configured, this method constructs the
+ /// appropriate [`PartitionBuildData`], schedules the reporting future, and
+ /// returns [`HashJoinStreamState::WaitPartitionBoundsReport`]. Otherwise it
+ /// delegates to [`Self::state_after_build_ready`].
+ fn transition_after_build_collected(
+ &mut self,
+ left_data: &Arc<JoinLeftData>,
+ ) -> HashJoinStreamState {
+ let Some(build_accumulator) = self.build_accumulator.as_ref() else {
+ return Self::state_after_build_ready(self.join_type, left_data.as_ref());
+ };
+
+ let pushdown = left_data.membership().clone();
+ let bounds = left_data
+ .bounds
+ .clone()
+ .unwrap_or_else(|| PartitionBounds::new(vec![]));
+
+ let build_data = match self.mode {
+ PartitionMode::Partitioned => PartitionBuildData::Partitioned {
+ partition_id: self.partition,
+ pushdown,
+ bounds,
+ },
+ PartitionMode::CollectLeft => {
+ PartitionBuildData::CollectLeft { pushdown, bounds }
+ }
+ PartitionMode::Auto => unreachable!(
+ "PartitionMode::Auto should not be present at execution time. This is a bug in DataFusion, please report it!"
+ ),
+ };
+
+ let acc = Arc::clone(build_accumulator);
+ self.build_waiter = Some(OnceFut::new(async move {
+ acc.report_build_data(build_data).await
+ }));
+ self.build_report_state = BuildReportState::ReportScheduled;
+ HashJoinStreamState::WaitPartitionBoundsReport
+ }
+
/// Separate implementation function that unpins the [`HashJoinStream`] so
/// that partial borrows work correctly
fn poll_next_impl(
@@ -483,6 +542,7 @@ impl HashJoinStream {
) -> Poll<Result<StatefulStreamResult<Option<RecordBatch>>>> {
if let Some(ref mut fut) = self.build_waiter {
ready!(fut.get_shared(cx))?;
+ self.build_report_state = BuildReportState::ReportDelivered;
}
let build_side = self.build_side.try_as_ready()?;
self.state =
@@ -511,55 +571,7 @@ impl HashJoinStream {
// not the build side (left). The probe-side NULL check happens during process_probe_batch.
// The probe_side_has_null flag will be set there if any probe batch contains NULL.
- // Handle dynamic filter build-side information accumulation
- //
- // Dynamic filter coordination between partitions:
- // Report hash maps (Partitioned mode) or bounds (CollectLeft mode) to the accumulator
- // which will handle synchronization and filter updates
- if let Some(ref build_accumulator) = self.build_accumulator {
- let build_accumulator = Arc::clone(build_accumulator);
-
- let left_side_partition_id = match self.mode {
- PartitionMode::Partitioned => self.partition,
- PartitionMode::CollectLeft => 0,
- PartitionMode::Auto => unreachable!(
- "PartitionMode::Auto should not be present at execution time. This is a bug in DataFusion, please report it!"
- ),
- };
-
- // Determine pushdown strategy based on availability of InList values
- let pushdown = left_data.membership().clone();
-
- // Construct the appropriate build data enum variant based on partition mode
- let build_data = match self.mode {
- PartitionMode::Partitioned => PartitionBuildData::Partitioned {
- partition_id: left_side_partition_id,
- pushdown,
- bounds: left_data
- .bounds
- .clone()
- .unwrap_or_else(|| PartitionBounds::new(vec![])),
- },
- PartitionMode::CollectLeft => PartitionBuildData::CollectLeft {
- pushdown,
- bounds: left_data
- .bounds
- .clone()
- .unwrap_or_else(|| PartitionBounds::new(vec![])),
- },
- PartitionMode::Auto => unreachable!(
- "PartitionMode::Auto should not be present at execution time"
- ),
- };
-
- self.build_waiter = Some(OnceFut::new(async move {
- build_accumulator.report_build_data(build_data).await
- }));
- self.state = HashJoinStreamState::WaitPartitionBoundsReport;
- } else {
- self.state =
- Self::state_after_build_ready(self.join_type, left_data.as_ref());
- }
+ self.state = self.transition_after_build_collected(&left_data);
self.build_side = BuildSide::Ready(BuildSideReadyState { left_data });
Poll::Ready(Ok(StatefulStreamResult::Continue))
@@ -947,3 +959,15 @@ impl Stream for HashJoinStream {
self.poll_next_impl(cx)
}
}
+
+impl Drop for HashJoinStream {
+ fn drop(&mut self) {
+ if self.mode == PartitionMode::Partitioned
+ && !matches!(self.build_report_state, BuildReportState::ReportDelivered)
+ && let Some(build_accumulator) = &self.build_accumulator
+ {
+ build_accumulator.report_canceled_partition(self.partition);
+ self.build_report_state = BuildReportState::ReportDelivered;
+ }
+ }
+}