datafusion_common/
join_type.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Defines the [`JoinType`], [`JoinConstraint`] and [`JoinSide`] types.
19
20use std::{
21    fmt::{self, Display, Formatter},
22    str::FromStr,
23};
24
25use crate::error::_not_impl_err;
26use crate::{DataFusionError, Result};
27
28/// Join type
29#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Hash)]
30pub enum JoinType {
31    /// Inner Join - Returns only rows where there is a matching value in both tables based on the join condition.
32    /// For example, if joining table A and B on A.id = B.id, only rows where A.id equals B.id will be included.
33    /// All columns from both tables are returned for the matching rows. Non-matching rows are excluded entirely.
34    Inner,
35    /// Left Join - Returns all rows from the left table and matching rows from the right table.
36    /// If no match, NULL values are returned for columns from the right table.
37    Left,
38    /// Right Join - Returns all rows from the right table and matching rows from the left table.
39    /// If no match, NULL values are returned for columns from the left table.
40    Right,
41    /// Full Join (also called Full Outer Join) - Returns all rows from both tables, matching rows where possible.
42    /// When a row from either table has no match in the other table, the missing columns are filled with NULL values.
43    /// For example, if table A has row X with no match in table B, the result will contain row X with NULL values for all of table B's columns.
44    /// This join type preserves all records from both tables, making it useful when you need to see all data regardless of matches.
45    Full,
46    /// Left Semi Join - Returns rows from the left table that have matching rows in the right table.
47    /// Only columns from the left table are returned.
48    LeftSemi,
49    /// Right Semi Join - Returns rows from the right table that have matching rows in the left table.
50    /// Only columns from the right table are returned.
51    RightSemi,
52    /// Left Anti Join - Returns rows from the left table that do not have a matching row in the right table.
53    LeftAnti,
54    /// Right Anti Join - Returns rows from the right table that do not have a matching row in the left table.
55    RightAnti,
56    /// Left Mark join
57    ///
58    /// Returns one record for each record from the left input. The output contains an additional
59    /// column "mark" which is true if there is at least one match in the right input where the
60    /// join condition evaluates to true. Otherwise, the mark column is false. For more details see
61    /// [1]. This join type is used to decorrelate EXISTS subqueries used inside disjunctive
62    /// predicates.
63    ///
64    /// Note: This we currently do not implement the full null semantics for the mark join described
65    /// in [1] which will be needed if we and ANY subqueries. In our version the mark column will
66    /// only be true for had a match and false when no match was found, never null.
67    ///
68    /// [1]: http://btw2017.informatik.uni-stuttgart.de/slidesandpapers/F1-10-37/paper_web.pdf
69    LeftMark,
70}
71
72impl JoinType {
73    pub fn is_outer(self) -> bool {
74        self == JoinType::Left || self == JoinType::Right || self == JoinType::Full
75    }
76
77    /// Returns the `JoinType` if the (2) inputs were swapped
78    ///
79    /// Panics if [`Self::supports_swap`] returns false
80    pub fn swap(&self) -> JoinType {
81        match self {
82            JoinType::Inner => JoinType::Inner,
83            JoinType::Full => JoinType::Full,
84            JoinType::Left => JoinType::Right,
85            JoinType::Right => JoinType::Left,
86            JoinType::LeftSemi => JoinType::RightSemi,
87            JoinType::RightSemi => JoinType::LeftSemi,
88            JoinType::LeftAnti => JoinType::RightAnti,
89            JoinType::RightAnti => JoinType::LeftAnti,
90            JoinType::LeftMark => {
91                unreachable!("LeftMark join type does not support swapping")
92            }
93        }
94    }
95
96    /// Does the join type support swapping  inputs?
97    pub fn supports_swap(&self) -> bool {
98        matches!(
99            self,
100            JoinType::Inner
101                | JoinType::Left
102                | JoinType::Right
103                | JoinType::Full
104                | JoinType::LeftSemi
105                | JoinType::RightSemi
106                | JoinType::LeftAnti
107                | JoinType::RightAnti
108        )
109    }
110}
111
112impl Display for JoinType {
113    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
114        let join_type = match self {
115            JoinType::Inner => "Inner",
116            JoinType::Left => "Left",
117            JoinType::Right => "Right",
118            JoinType::Full => "Full",
119            JoinType::LeftSemi => "LeftSemi",
120            JoinType::RightSemi => "RightSemi",
121            JoinType::LeftAnti => "LeftAnti",
122            JoinType::RightAnti => "RightAnti",
123            JoinType::LeftMark => "LeftMark",
124        };
125        write!(f, "{join_type}")
126    }
127}
128
129impl FromStr for JoinType {
130    type Err = DataFusionError;
131
132    fn from_str(s: &str) -> Result<Self> {
133        let s = s.to_uppercase();
134        match s.as_str() {
135            "INNER" => Ok(JoinType::Inner),
136            "LEFT" => Ok(JoinType::Left),
137            "RIGHT" => Ok(JoinType::Right),
138            "FULL" => Ok(JoinType::Full),
139            "LEFTSEMI" => Ok(JoinType::LeftSemi),
140            "RIGHTSEMI" => Ok(JoinType::RightSemi),
141            "LEFTANTI" => Ok(JoinType::LeftAnti),
142            "RIGHTANTI" => Ok(JoinType::RightAnti),
143            "LEFTMARK" => Ok(JoinType::LeftMark),
144            _ => _not_impl_err!("The join type {s} does not exist or is not implemented"),
145        }
146    }
147}
148
149/// Join constraint
150#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Hash)]
151pub enum JoinConstraint {
152    /// Join ON
153    On,
154    /// Join USING
155    Using,
156}
157
158impl Display for JoinSide {
159    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
160        match self {
161            JoinSide::Left => write!(f, "left"),
162            JoinSide::Right => write!(f, "right"),
163            JoinSide::None => write!(f, "none"),
164        }
165    }
166}
167
168/// Join side.
169/// Stores the referred table side during calculations
170#[derive(Debug, Clone, Copy, PartialEq)]
171pub enum JoinSide {
172    /// Left side of the join
173    Left,
174    /// Right side of the join
175    Right,
176    /// Neither side of the join, used for Mark joins where the mark column does not belong to
177    /// either side of the join
178    None,
179}
180
181impl JoinSide {
182    /// Inverse the join side
183    pub fn negate(&self) -> Self {
184        match self {
185            JoinSide::Left => JoinSide::Right,
186            JoinSide::Right => JoinSide::Left,
187            JoinSide::None => JoinSide::None,
188        }
189    }
190}
datafusion_common/join_type.rs

datafusion_common/
join_type.rs
