Skip to content

Apache DataFusion SQL Query Engine

feat: push dynamic filters through nested loop joins (#25030)

Yash Bhisikar902ee8a67e68
diff --git a/datafusion/core/tests/physical_optimizer/filter_pushdown.rs b/datafusion/core/tests/physical_optimizer/filter_pushdown.rs
index 1ad268c4b4..ddd4bb4d27 100644
--- a/datafusion/core/tests/physical_optimizer/filter_pushdown.rs
+++ b/datafusion/core/tests/physical_optimizer/filter_pushdown.rs
@@ -70,7 +70,7 @@ use datafusion_physical_plan::{
ChildrenPropertiesMode, ReplaceChildrenOptions, plan_contains_expression_id,
},
filter::{FilterExec, FilterExecBuilder},
- joins::{HashJoinExec, PartitionMode},
+ joins::{HashJoinExec, NestedLoopJoinExec, PartitionMode},
projection::ProjectionExec,
repartition::RepartitionExec,
sorts::sort::SortExec,
@@ -4166,6 +4166,194 @@ fn test_hashjoin_dynamic_filter_requires_probe_consumer() {
}
}
+#[tokio::test]
+async fn test_nlj_dynamic_filter_pushdown_preserves_unmatched_rows() {
+ use datafusion_common::JoinSide;
+ use datafusion_physical_plan::joins::utils::{ColumnIndex, JoinFilter};
+
+ for enabled in [false, true] {
+ let scan = |batch: RecordBatch| {
+ TestScanBuilder::new(batch.schema())
+ .with_support(true)
+ .with_batches(vec![batch])
+ .build()
+ };
+ // The hash join keeps keys 1 and 3. In the NLJ, 1 matches 2 and 3
+ // is unmatched. Pushing the filter to the right input would remove 2
+ // and incorrectly turn the matching row into an unmatched row.
+ let left = scan(record_batch!(("key", Int32, [1, 2, 3])).unwrap());
+ let right = scan(record_batch!(("key", Int32, [2])).unwrap());
+ let filter = JoinFilter::new(
+ Arc::new(BinaryExpr::new(
+ Arc::new(Column::new("left", 0)),
+ Operator::Lt,
+ Arc::new(Column::new("right", 1)),
+ )),
+ vec![
+ ColumnIndex {
+ index: 0,
+ side: JoinSide::Left,
+ },
+ ColumnIndex {
+ index: 0,
+ side: JoinSide::Right,
+ },
+ ],
+ Arc::new(Schema::new(vec![
+ Field::new("left", DataType::Int32, false),
+ Field::new("right", DataType::Int32, false),
+ ])),
+ );
+ let probe = Arc::new(
+ NestedLoopJoinExec::try_new(left, right, Some(filter), &JoinType::Left, None)
+ .unwrap(),
+ );
+ let build = scan(record_batch!(("key", Int32, [1, 3])).unwrap());
+ let plan = Arc::new(
+ HashJoinExec::try_new(
+ build,
+ probe,
+ vec![(
+ Arc::new(Column::new("key", 0)),
+ Arc::new(Column::new("key", 0)),
+ )],
+ None,
+ &JoinType::Inner,
+ None,
+ PartitionMode::CollectLeft,
+ datafusion_common::NullEquality::NullEqualsNothing,
+ false,
+ )
+ .unwrap(),
+ ) as Arc<dyn ExecutionPlan>;
+ let mut config = ConfigOptions::default();
+ config.execution.parquet.pushdown_filters = true;
+ config.optimizer.enable_join_dynamic_filter_pushdown = enabled;
+ let plan = FilterPushdown::new_post_optimization()
+ .optimize(plan, &config)
+ .unwrap();
+ assert_eq!(
+ plan.dynamic_expressions_produced().len(),
+ usize::from(enabled)
+ );
+ if enabled {
+ let id = plan.dynamic_expressions_produced()[0]
+ .expression_id()
+ .unwrap();
+ let hash_join = plan.downcast_ref::<HashJoinExec>().unwrap();
+ let nlj = hash_join
+ .right()
+ .downcast_ref::<NestedLoopJoinExec>()
+ .unwrap();
+ assert!(plan_contains_expression_id(nlj.left(), id).unwrap());
+ assert!(!plan_contains_expression_id(nlj.right(), id).unwrap());
+ }
+ let ctx = SessionContext::new_with_config(SessionConfig::from(config));
+ ctx.register_object_store(
+ ObjectStoreUrl::parse("test://").unwrap().as_ref(),
+ Arc::new(InMemory::new()),
+ );
+ let batches = collect(plan, ctx.task_ctx()).await.unwrap();
+ assert_batches_eq!(
+ [
+ "+-----+-----+-----+",
+ "| key | key | key |",
+ "+-----+-----+-----+",
+ "| 1 | 1 | 2 |",
+ "| 3 | 3 | |",
+ "+-----+-----+-----+",
+ ],
+ &batches
+ );
+ }
+}
+
+#[tokio::test]
+async fn test_nlj_dynamic_filter_pushdown_from_hashjoin() {
+ for filtered_side in [0, 1] {
+ let mut results = Vec::new();
+ for enabled in [false, true] {
+ let probe_batch = record_batch!(("key", Int32, [1, 2, 3])).unwrap();
+ let schema = probe_batch.schema();
+ let scan = || {
+ TestScanBuilder::new(Arc::clone(&schema))
+ .with_support(true)
+ .with_batches(vec![probe_batch.clone()])
+ .build()
+ };
+ // The identical names and reversed output order ensure the filter
+ // reaches the intended input by position, not by name.
+ let probe = Arc::new(
+ NestedLoopJoinExec::try_new(
+ scan(),
+ scan(),
+ None,
+ &JoinType::Inner,
+ Some(vec![1, 0]),
+ )
+ .unwrap(),
+ );
+ let build = TestScanBuilder::new(schema)
+ .with_support(true)
+ .with_batches(vec![record_batch!(("key", Int32, [2])).unwrap()])
+ .build();
+ let plan = Arc::new(
+ HashJoinExec::try_new(
+ build,
+ probe,
+ vec![(
+ Arc::new(Column::new("key", 0)),
+ Arc::new(Column::new("key", 1 - filtered_side)),
+ )],
+ None,
+ &JoinType::Inner,
+ None,
+ PartitionMode::CollectLeft,
+ datafusion_common::NullEquality::NullEqualsNothing,
+ false,
+ )
+ .unwrap(),
+ ) as Arc<dyn ExecutionPlan>;
+ let mut config = ConfigOptions::default();
+ config.execution.parquet.pushdown_filters = true;
+ config.optimizer.enable_join_dynamic_filter_pushdown = enabled;
+ let plan = FilterPushdown::new_post_optimization()
+ .optimize(plan, &config)
+ .unwrap();
+ assert_eq!(
+ plan.dynamic_expressions_produced().len(),
+ usize::from(enabled)
+ );
+ let join = plan.downcast_ref::<HashJoinExec>().unwrap();
+ let nlj = join.right().downcast_ref::<NestedLoopJoinExec>().unwrap();
+ if enabled {
+ let id = plan.dynamic_expressions_produced()[0]
+ .expression_id()
+ .unwrap();
+ for (side, child) in nlj.children().iter().enumerate() {
+ assert_eq!(
+ plan_contains_expression_id(child, id).unwrap(),
+ side == filtered_side
+ );
+ }
+ }
+ let ctx = SessionContext::new_with_config(SessionConfig::from(config));
+ ctx.register_object_store(
+ ObjectStoreUrl::parse("test://").unwrap().as_ref(),
+ Arc::new(InMemory::new()),
+ );
+ let batches = collect(Arc::clone(&plan), ctx.task_ctx()).await.unwrap();
+ assert_eq!(batches.iter().map(RecordBatch::num_rows).sum::<usize>(), 3);
+ if enabled {
+ let dynamic = plan.dynamic_expressions_produced().remove(0);
+ assert_ne!(dynamic.snapshot().unwrap().unwrap().to_string(), "true");
+ }
+ results.push(pretty_format_batches(&batches).unwrap().to_string());
+ }
+ assert_eq!(results[0], results[1]);
+ }
+}
+
// Not portable to sqllogictest: stands in for a distributed planner that splits
// an already-optimized plan into stages, leaving the HashJoinExec and the scan
// consuming its dynamic filter on different workers. Whether to produce the
diff --git a/datafusion/physical-plan/src/joins/nested_loop_join.rs b/datafusion/physical-plan/src/joins/nested_loop_join.rs
index 462576b2b4..0ed1236a09 100644
--- a/datafusion/physical-plan/src/joins/nested_loop_join.rs
+++ b/datafusion/physical-plan/src/joins/nested_loop_join.rs
@@ -29,6 +29,9 @@ use super::utils::{
};
use crate::common::can_project;
use crate::execution_plan::{EmissionType, boundedness_from_children};
+use crate::filter_pushdown::{
+ ChildFilterDescription, FilterDescription, FilterPushdownPhase, PushedDownPredicate,
+};
use crate::joins::SharedBitmapBuilder;
use crate::joins::utils::{
BuildProbeJoinMetrics, ColumnIndex, JoinFilter, OnceAsync, OnceFut,
@@ -62,6 +65,7 @@ use arrow::datatypes::{Schema, SchemaRef};
use arrow::record_batch::RecordBatch;
use arrow_schema::DataType;
use datafusion_common::cast::as_boolean_array;
+use datafusion_common::config::ConfigOptions;
use datafusion_common::tree_node::TreeNodeRecursion;
use datafusion_common::{
JoinSide, NullEquality, Result, ScalarValue, Statistics, arrow_err,
@@ -71,9 +75,11 @@ use datafusion_common::{
use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
use datafusion_execution::{SpillFile, TaskContext};
use datafusion_expr::JoinType;
+use datafusion_physical_expr::PhysicalExpr;
use datafusion_physical_expr::equivalence::{
ProjectionMapping, join_equivalence_properties,
};
+use datafusion_physical_expr::expressions::DynamicFilterPhysicalExpr;
use datafusion_physical_expr::projection::{ProjectionRef, combine_projections};
use futures::future::BoxFuture;
@@ -576,7 +582,7 @@ impl ExecutionPlan for NestedLoopJoinExec {
fn apply_expressions(
&self,
- f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+ f: &mut dyn FnMut(&Arc<dyn PhysicalExpr>) -> Result<TreeNodeRecursion>,
) -> Result<TreeNodeRecursion> {
// Apply to join filter expressions if present
crate::apply_expression_roots(
@@ -832,6 +838,77 @@ impl ExecutionPlan for NestedLoopJoinExec {
Ok(Arc::new(stats.project(self.projection.as_ref())))
}
+ fn gather_filters_for_pushdown(
+ &self,
+ phase: FilterPushdownPhase,
+ parent_filters: Vec<Arc<dyn PhysicalExpr>>,
+ config: &ConfigOptions,
+ ) -> Result<FilterDescription> {
+ if phase != FilterPushdownPhase::Post
+ || !config.optimizer.enable_join_dynamic_filter_pushdown
+ {
+ return Ok(FilterDescription::new()
+ .with_child(ChildFilterDescription::all_unsupported(&parent_filters))
+ .with_child(ChildFilterDescription::all_unsupported(&parent_filters)));
+ }
+
+ // Removing rows from the non-preserved side of an outer or anti join
+ // can create new unmatched rows. Only route filters to output-preserving
+ // inputs; unlike a hash join, an NLJ has no equijoin keys to translate
+ // filters onto the other input of a semi join.
+ let (left_preserved, right_preserved) = match self.join_type {
+ JoinType::Inner => (true, true),
+ JoinType::Left
+ | JoinType::LeftSemi
+ | JoinType::LeftAnti
+ | JoinType::LeftMark => (true, false),
+ JoinType::Right
+ | JoinType::RightSemi
+ | JoinType::RightAnti
+ | JoinType::RightMark => (false, true),
+ JoinType::Full => (false, false),
+ };
+ let output_indices: Vec<_> = match &self.projection {
+ Some(projection) => projection.to_vec(),
+ None => (0..self.column_indices.len()).collect(),
+ };
+ let mut description = FilterDescription::new();
+ for (side, preserved, child) in [
+ (JoinSide::Left, left_preserved, self.left()),
+ (JoinSide::Right, right_preserved, self.right()),
+ ] {
+ // Map positions explicitly: names can repeat within an input as
+ // well as across the two sides of the join.
+ let column_mapping = output_indices
+ .iter()
+ .enumerate()
+ .filter_map(|(output, input)| {
+ let column = &self.column_indices[*input];
+ (column.side == side).then_some((output, column.index))
+ })
+ .collect();
+ let mut child_description = if preserved {
+ ChildFilterDescription::from_child_with_column_mapping(
+ &parent_filters,
+ column_mapping,
+ child,
+ )?
+ } else {
+ ChildFilterDescription::all_unsupported(&parent_filters)
+ };
+ for (filter, pushed) in parent_filters
+ .iter()
+ .zip(&mut child_description.parent_filters)
+ {
+ if !filter.is::<DynamicFilterPhysicalExpr>() {
+ *pushed = PushedDownPredicate::unsupported(Arc::clone(filter));
+ }
+ }
+ description = description.with_child(child_description);
+ }
+ Ok(description)
+ }
+
/// Tries to push `projection` down through `nested_loop_join`. If possible, performs the
/// pushdown and returns a new [`NestedLoopJoinExec`] as the top plan which has projections
/// as its children. Otherwise, returns `None`.
@@ -4205,6 +4282,145 @@ pub(crate) mod tests {
use insta::assert_snapshot;
use rstest::rstest;
+ #[test]
+ fn test_nlj_dynamic_filter_pushdown() -> Result<()> {
+ use crate::filter_pushdown::PushedDown;
+ use arrow::array::record_batch;
+ use datafusion_physical_expr::expressions::lit;
+
+ // Identical names within and across inputs must not affect routing.
+ // Reordered outputs also exercise the NLJ's embedded projection.
+ let batch = record_batch!(("key", Int32, [1, 2]), ("key", Int32, [2, 1]))?;
+ let input: Arc<dyn ExecutionPlan> =
+ TestMemoryExec::try_new_exec(&[vec![batch.clone()]], batch.schema(), None)?;
+ for join_type in [
+ JoinType::Inner,
+ JoinType::Left,
+ JoinType::Right,
+ JoinType::Full,
+ JoinType::LeftSemi,
+ JoinType::RightSemi,
+ JoinType::LeftAnti,
+ JoinType::RightAnti,
+ JoinType::LeftMark,
+ JoinType::RightMark,
+ ] {
+ let join = NestedLoopJoinExec::try_new(
+ Arc::clone(&input),
+ Arc::clone(&input),
+ None,
+ &join_type,
+ None,
+ )?;
+ for reorder in [false, true] {
+ let projection =
+ reorder.then(|| (0..join.schema().fields().len()).rev().collect());
+ let join = join.with_projection(projection)?;
+ for output in 0..join.schema().fields().len() {
+ let column: Arc<dyn PhysicalExpr> =
+ Arc::new(Column::new(join.schema().field(output).name(), output));
+ let source = Arc::new(DynamicFilterPhysicalExpr::new(
+ vec![Arc::clone(&column)],
+ lit(true),
+ ));
+ let filters = join
+ .gather_filters_for_pushdown(
+ FilterPushdownPhase::Post,
+ vec![Arc::clone(&source) as _],
+ &ConfigOptions::default(),
+ )?
+ .parent_filters();
+ let unprojected =
+ join.projection.as_ref().map_or(output, |p| p[output]);
+ let side = join.column_indices[unprojected].side;
+ let expected = match join_type {
+ JoinType::Inner => {
+ [side == JoinSide::Left, side == JoinSide::Right]
+ }
+ JoinType::Left
+ | JoinType::LeftSemi
+ | JoinType::LeftAnti
+ | JoinType::LeftMark => [side == JoinSide::Left, false],
+ JoinType::Right
+ | JoinType::RightSemi
+ | JoinType::RightAnti
+ | JoinType::RightMark => [false, side == JoinSide::Right],
+ JoinType::Full => [false, false],
+ };
+ // Update after routing to prove the remapped consumer stays live.
+ source.update(Arc::new(BinaryExpr::new(
+ column,
+ Operator::Eq,
+ lit(2i32),
+ )))?;
+ for (child, accepted) in filters.iter().zip(expected) {
+ assert_eq!(
+ matches!(child[0].discriminant, PushedDown::Yes),
+ accepted,
+ "{join_type:?}, reorder={reorder}, output={output}"
+ );
+ if accepted {
+ assert_eq!(
+ child[0].predicate.expression_id(),
+ source.expression_id()
+ );
+ let values = child[0]
+ .predicate
+ .evaluate(&batch)?
+ .into_array(batch.num_rows())?;
+ assert_eq!(
+ as_boolean_array(&values)?.iter().collect::<Vec<_>>(),
+ if join.column_indices[unprojected].index == 0 {
+ vec![Some(false), Some(true)]
+ } else {
+ vec![Some(true), Some(false)]
+ }
+ );
+ }
+ }
+ }
+ }
+ }
+
+ let join = NestedLoopJoinExec::try_new(
+ Arc::clone(&input),
+ input,
+ None,
+ &JoinType::Inner,
+ None,
+ )?;
+ let left: Arc<dyn PhysicalExpr> = Arc::new(Column::new("key", 0));
+ let right: Arc<dyn PhysicalExpr> = Arc::new(Column::new("key", 2));
+ let whole: Arc<dyn PhysicalExpr> = Arc::new(DynamicFilterPhysicalExpr::new(
+ vec![Arc::clone(&left)],
+ lit(true),
+ ));
+ let mixed: Arc<dyn PhysicalExpr> = Arc::new(DynamicFilterPhysicalExpr::new(
+ vec![Arc::clone(&left), right],
+ lit(true),
+ ));
+ let static_filter: Arc<dyn PhysicalExpr> =
+ Arc::new(BinaryExpr::new(left, Operator::Eq, lit(2i32)));
+ for (phase, enabled, filters) in [
+ (FilterPushdownPhase::Pre, true, vec![Arc::clone(&whole)]),
+ (FilterPushdownPhase::Post, false, vec![whole]),
+ (FilterPushdownPhase::Post, true, vec![mixed, static_filter]),
+ ] {
+ let mut config = ConfigOptions::default();
+ config.optimizer.enable_join_dynamic_filter_pushdown = enabled;
+ let description =
+ join.gather_filters_for_pushdown(phase, filters, &config)?;
+ assert!(
+ description
+ .parent_filters()
+ .iter()
+ .flatten()
+ .all(|f| matches!(f.discriminant, PushedDown::No))
+ );
+ }
+ Ok(())
+ }
+
fn delayed_stream(batch: RecordBatch, delay: Duration) -> SendableRecordBatchStream {
let schema = batch.schema();
Box::pin(crate::stream::RecordBatchStreamAdapter::new(