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.rsindex 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 thediff --git a/datafusion/physical-plan/src/joins/nested_loop_join.rs b/datafusion/physical-plan/src/joins/nested_loop_join.rsindex 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 presentcrate::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(