You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by al...@apache.org on 2025/09/04 13:39:05 UTC
(datafusion) branch main updated: doc: Document caveats of `swap_inputs()` interface in join executors (#17373)
This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new a68563b30a doc: Document caveats of `swap_inputs()` interface in join executors (#17373)
a68563b30a is described below
commit a68563b30ae03b074bdd687a181e42857e78f24f
Author: Yongting You <20...@gmail.com>
AuthorDate: Thu Sep 4 21:39:01 2025 +0800
doc: Document caveats of `swap_inputs()` interface in join executors (#17373)
* doc caveats of `swap_inputs()` interface in join executors
* fix ci
* Update datafusion/physical-plan/src/joins/hash_join/exec.rs
Co-authored-by: Jonathan Chen <ch...@gmail.com>
---------
Co-authored-by: Jonathan Chen <ch...@gmail.com>
---
datafusion/physical-plan/src/joins/cross_join.rs | 6 ++++++
datafusion/physical-plan/src/joins/hash_join/exec.rs | 15 +++++++++++++++
datafusion/physical-plan/src/joins/nested_loop_join.rs | 6 ++++++
.../physical-plan/src/joins/sort_merge_join/exec.rs | 5 +++++
4 files changed, 32 insertions(+)
diff --git a/datafusion/physical-plan/src/joins/cross_join.rs b/datafusion/physical-plan/src/joins/cross_join.rs
index b8ea6330a1..864def5e91 100644
--- a/datafusion/physical-plan/src/joins/cross_join.rs
+++ b/datafusion/physical-plan/src/joins/cross_join.rs
@@ -175,6 +175,12 @@ impl CrossJoinExec {
/// Returns a new `ExecutionPlan` that computes the same join as this one,
/// with the left and right inputs swapped using the specified
/// `partition_mode`.
+ ///
+ /// # Notes:
+ ///
+ /// This function should be called BEFORE inserting any repartitioning
+ /// operators on the join's children. Check [`super::HashJoinExec::swap_inputs`]
+ /// for more details.
pub fn swap_inputs(&self) -> Result<Arc<dyn ExecutionPlan>> {
let new_join =
CrossJoinExec::new(Arc::clone(&self.right), Arc::clone(&self.left));
diff --git a/datafusion/physical-plan/src/joins/hash_join/exec.rs b/datafusion/physical-plan/src/joins/hash_join/exec.rs
index 5710bfefb5..a2e2d9bf04 100644
--- a/datafusion/physical-plan/src/joins/hash_join/exec.rs
+++ b/datafusion/physical-plan/src/joins/hash_join/exec.rs
@@ -638,6 +638,21 @@ impl HashJoinExec {
///
/// This function is public so other downstream projects can use it to
/// construct `HashJoinExec` with right side as the build side.
+ ///
+ /// For using this interface directly, please refer to below:
+ ///
+ /// Hash join execution may require specific input partitioning (for example,
+ /// the left child may have a single partition while the right child has multiple).
+ ///
+ /// Calling this function on join nodes whose children have already been repartitioned
+ /// (e.g., after a `RepartitionExec` has been inserted) may break the partitioning
+ /// requirements of the hash join. Therefore, ensure you call this function
+ /// before inserting any repartitioning operators on the join's children.
+ ///
+ /// In DataFusion's default SQL interface, this function is used by the `JoinSelection`
+ /// physical optimizer rule to determine a good join order, which is
+ /// executed before the `EnforceDistribution` rule (the rule that may
+ /// insert `RepartitionExec` operators).
pub fn swap_inputs(
&self,
partition_mode: PartitionMode,
diff --git a/datafusion/physical-plan/src/joins/nested_loop_join.rs b/datafusion/physical-plan/src/joins/nested_loop_join.rs
index be39c0990c..ced9078d95 100644
--- a/datafusion/physical-plan/src/joins/nested_loop_join.rs
+++ b/datafusion/physical-plan/src/joins/nested_loop_join.rs
@@ -348,6 +348,12 @@ impl NestedLoopJoinExec {
/// Returns a new `ExecutionPlan` that runs NestedLoopsJoins with the left
/// and right inputs swapped.
+ ///
+ /// # Notes:
+ ///
+ /// This function should be called BEFORE inserting any repartitioning
+ /// operators on the join's children. Check [`super::HashJoinExec::swap_inputs`]
+ /// for more details.
pub fn swap_inputs(&self) -> Result<Arc<dyn ExecutionPlan>> {
let left = self.left();
let right = self.right();
diff --git a/datafusion/physical-plan/src/joins/sort_merge_join/exec.rs b/datafusion/physical-plan/src/joins/sort_merge_join/exec.rs
index da8e28aa15..47158d0cfa 100644
--- a/datafusion/physical-plan/src/joins/sort_merge_join/exec.rs
+++ b/datafusion/physical-plan/src/joins/sort_merge_join/exec.rs
@@ -304,6 +304,11 @@ impl SortMergeJoinExec {
))
}
+ /// # Notes:
+ ///
+ /// This function should be called BEFORE inserting any repartitioning
+ /// operators on the join's children. Check [`super::super::HashJoinExec::swap_inputs`]
+ /// for more details.
pub fn swap_inputs(&self) -> Result<Arc<dyn ExecutionPlan>> {
let left = self.left();
let right = self.right();
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org