sqlspec 0.22.0__py3-none-any.whl → 0.23.0__py3-none-any.whl

sqlspec/_sql.py

@@ -628,6 +628,42 @@ class SQLFactory:
         """Create a CROSS JOIN builder."""
         return JoinBuilder("cross join")
 
+    @property
+    def lateral_join_(self) -> "JoinBuilder":
+        """Create a LATERAL JOIN builder.
+
+        Returns:
+            JoinBuilder configured for LATERAL JOIN
+
+        Example:
+            ```python
+            query = (
+                sql.select("u.name", "arr.value")
+                .from_("users u")
+                .join(sql.lateral_join_("UNNEST(u.tags)").on("true"))
+            )
+            ```
+        """
+        return JoinBuilder("lateral join", lateral=True)
+
+    @property
+    def left_lateral_join_(self) -> "JoinBuilder":
+        """Create a LEFT LATERAL JOIN builder.
+
+        Returns:
+            JoinBuilder configured for LEFT LATERAL JOIN
+        """
+        return JoinBuilder("left join", lateral=True)
+
+    @property
+    def cross_lateral_join_(self) -> "JoinBuilder":
+        """Create a CROSS LATERAL JOIN builder.
+
+        Returns:
+            JoinBuilder configured for CROSS LATERAL JOIN
+        """
+        return JoinBuilder("cross join", lateral=True)
+
     def __getattr__(self, name: str) -> "Column":
         """Dynamically create column references.
 

sqlspec/builder/mixins/_join_operations.py

@@ -14,7 +14,6 @@ from sqlspec.exceptions import SQLBuilderError
 from sqlspec.utils.type_guards import has_query_builder_parameters
 
 if TYPE_CHECKING:
-    from sqlspec.builder._column import ColumnExpression
     from sqlspec.core.statement import SQL
     from sqlspec.protocols import SQLBuilderProtocol
 
@@ -36,74 +35,133 @@ class JoinClauseMixin:
         on: Optional[Union[str, exp.Expression, "SQL"]] = None,
         alias: Optional[str] = None,
         join_type: str = "INNER",
+        lateral: bool = False,
     ) -> Self:
         builder = cast("SQLBuilderProtocol", self)
+        self._validate_join_context(builder)
+
+        # Handle Join expressions directly (from JoinBuilder.on() calls)
+        if isinstance(table, exp.Join):
+            if builder._expression is not None and isinstance(builder._expression, exp.Select):
+                builder._expression = builder._expression.join(table, copy=False)
+            return cast("Self", builder)
+
+        table_expr = self._parse_table_expression(table, alias, builder)
+        on_expr = self._parse_on_condition(on, builder)
+        join_expr = self._create_join_expression(table_expr, on_expr, join_type)
+
+        if lateral:
+            self._apply_lateral_modifier(join_expr)
+
+        if builder._expression is not None and isinstance(builder._expression, exp.Select):
+            builder._expression = builder._expression.join(join_expr, copy=False)
+        return cast("Self", builder)
+
+    def _validate_join_context(self, builder: "SQLBuilderProtocol") -> None:
+        """Validate that the join can be applied to the current expression."""
         if builder._expression is None:
             builder._expression = exp.Select()
         if not isinstance(builder._expression, exp.Select):
             msg = "JOIN clause is only supported for SELECT statements."
             raise SQLBuilderError(msg)
-        table_expr: exp.Expression
+
+    def _parse_table_expression(
+        self, table: Union[str, exp.Expression, Any], alias: Optional[str], builder: "SQLBuilderProtocol"
+    ) -> exp.Expression:
+        """Parse table parameter into a SQLGlot expression."""
         if isinstance(table, str):
-            table_expr = parse_table_expression(table, alias)
-        elif has_query_builder_parameters(table):
-            if hasattr(table, "_expression") and getattr(table, "_expression", None) is not None:
-                table_expr_value = getattr(table, "_expression", None)
-                if table_expr_value is not None:
-                    subquery_exp = exp.paren(table_expr_value)
-                else:
-                    subquery_exp = exp.paren(exp.Anonymous(this=""))
-                table_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
+            return parse_table_expression(table, alias)
+        if has_query_builder_parameters(table):
+            return self._handle_query_builder_table(table, alias, builder)
+        if isinstance(table, exp.Expression):
+            return table
+        return cast("exp.Expression", table)
+
+    def _handle_query_builder_table(
+        self, table: Any, alias: Optional[str], builder: "SQLBuilderProtocol"
+    ) -> exp.Expression:
+        """Handle table parameters that are query builders."""
+        if hasattr(table, "_expression") and getattr(table, "_expression", None) is not None:
+            table_expr_value = getattr(table, "_expression", None)
+            if table_expr_value is not None:
+                subquery_exp = exp.paren(table_expr_value)
             else:
-                subquery = table.build()
-                sql_str = subquery.sql if hasattr(subquery, "sql") and not callable(subquery.sql) else str(subquery)
-                subquery_exp = exp.paren(exp.maybe_parse(sql_str, dialect=getattr(builder, "dialect", None)))
-                table_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
-        else:
-            table_expr = table
-        on_expr: Optional[exp.Expression] = None
-        if on is not None:
-            if isinstance(on, str):
-                on_expr = exp.condition(on)
-            elif hasattr(on, "expression") and hasattr(on, "sql"):
-                # Handle SQL objects (from sql.raw with parameters)
-                expression = getattr(on, "expression", None)
-                if expression is not None and isinstance(expression, exp.Expression):
-                    # Merge parameters from SQL object into builder
-                    if hasattr(on, "parameters") and hasattr(builder, "add_parameter"):
-                        sql_parameters = getattr(on, "parameters", {})
-                        for param_name, param_value in sql_parameters.items():
-                            builder.add_parameter(param_value, name=param_name)
-                    on_expr = expression
-                else:
-                    # If expression is None, fall back to parsing the raw SQL
-                    sql_text = getattr(on, "sql", "")
-                    # Merge parameters even when parsing raw SQL
-                    if hasattr(on, "parameters") and hasattr(builder, "add_parameter"):
-                        sql_parameters = getattr(on, "parameters", {})
-                        for param_name, param_value in sql_parameters.items():
-                            builder.add_parameter(param_value, name=param_name)
-                    on_expr = exp.maybe_parse(sql_text) or exp.condition(str(sql_text))
-            # For other types (should be exp.Expression)
-            elif isinstance(on, exp.Expression):
-                on_expr = on
-            else:
-                # Last resort - convert to string and parse
-                on_expr = exp.condition(str(on))
+                subquery_exp = exp.paren(exp.Anonymous(this=""))
+            return exp.alias_(subquery_exp, alias) if alias else subquery_exp
+        subquery = table.build()
+        sql_str = subquery.sql if hasattr(subquery, "sql") and not callable(subquery.sql) else str(subquery)
+        subquery_exp = exp.paren(exp.maybe_parse(sql_str, dialect=getattr(builder, "dialect", None)))
+        return exp.alias_(subquery_exp, alias) if alias else subquery_exp
+
+    def _parse_on_condition(
+        self, on: Optional[Union[str, exp.Expression, "SQL"]], builder: "SQLBuilderProtocol"
+    ) -> Optional[exp.Expression]:
+        """Parse ON condition into a SQLGlot expression."""
+        if on is None:
+            return None
+
+        if isinstance(on, str):
+            return exp.condition(on)
+        if hasattr(on, "expression") and hasattr(on, "sql"):
+            return self._handle_sql_object_condition(on, builder)
+        if isinstance(on, exp.Expression):
+            return on
+        # Last resort - convert to string and parse
+        return exp.condition(str(on))
+
+    def _handle_sql_object_condition(self, on: Any, builder: "SQLBuilderProtocol") -> exp.Expression:
+        """Handle SQL object conditions with parameter binding."""
+        expression = getattr(on, "expression", None)
+        if expression is not None and isinstance(expression, exp.Expression):
+            # Merge parameters from SQL object into builder
+            if hasattr(on, "parameters") and hasattr(builder, "add_parameter"):
+                sql_parameters = getattr(on, "parameters", {})
+                for param_name, param_value in sql_parameters.items():
+                    builder.add_parameter(param_value, name=param_name)
+            return cast("exp.Expression", expression)
+        # If expression is None, fall back to parsing the raw SQL
+        sql_text = getattr(on, "sql", "")
+        # Merge parameters even when parsing raw SQL
+        if hasattr(on, "parameters") and hasattr(builder, "add_parameter"):
+            sql_parameters = getattr(on, "parameters", {})
+            for param_name, param_value in sql_parameters.items():
+                builder.add_parameter(param_value, name=param_name)
+        parsed_expr = exp.maybe_parse(sql_text)
+        return parsed_expr if parsed_expr is not None else exp.condition(str(sql_text))
+
+    def _create_join_expression(
+        self, table_expr: exp.Expression, on_expr: Optional[exp.Expression], join_type: str
+    ) -> exp.Join:
+        """Create the appropriate JOIN expression based on join type."""
         join_type_upper = join_type.upper()
         if join_type_upper == "INNER":
-            join_expr = exp.Join(this=table_expr, on=on_expr)
-        elif join_type_upper == "LEFT":
-            join_expr = exp.Join(this=table_expr, on=on_expr, side="LEFT")
-        elif join_type_upper == "RIGHT":
-            join_expr = exp.Join(this=table_expr, on=on_expr, side="RIGHT")
-        elif join_type_upper == "FULL":
-            join_expr = exp.Join(this=table_expr, on=on_expr, side="FULL", kind="OUTER")
+            return exp.Join(this=table_expr, on=on_expr)
+        if join_type_upper == "LEFT":
+            return exp.Join(this=table_expr, on=on_expr, side="LEFT")
+        if join_type_upper == "RIGHT":
+            return exp.Join(this=table_expr, on=on_expr, side="RIGHT")
+        if join_type_upper == "FULL":
+            return exp.Join(this=table_expr, on=on_expr, side="FULL", kind="OUTER")
+        if join_type_upper == "CROSS":
+            return exp.Join(this=table_expr, kind="CROSS")
+        msg = f"Unsupported join type: {join_type}"
+        raise SQLBuilderError(msg)
+
+    def _apply_lateral_modifier(self, join_expr: exp.Join) -> None:
+        """Apply LATERAL modifier to the join expression."""
+        current_kind = join_expr.args.get("kind")
+        current_side = join_expr.args.get("side")
+
+        if current_kind == "CROSS":
+            join_expr.set("kind", "CROSS LATERAL")
+        elif current_kind == "OUTER" and current_side == "FULL":
+            join_expr.set("side", "FULL")  # Keep side
+            join_expr.set("kind", "OUTER LATERAL")
+        elif current_side:
+            join_expr.set("kind", f"{current_side} LATERAL")
+            join_expr.set("side", None)  # Clear side to avoid duplication
         else:
-            msg = f"Unsupported join type: {join_type}"
-            raise SQLBuilderError(msg)
-        builder._expression = builder._expression.join(join_expr, copy=False)
-        return cast("Self", builder)
+            join_expr.set("kind", "LATERAL")
 
     def inner_join(
         self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
@@ -154,6 +212,63 @@ class JoinClauseMixin:
         builder._expression = builder._expression.join(join_expr, copy=False)
         return cast("Self", builder)
 
+    def lateral_join(
+        self,
+        table: Union[str, exp.Expression, Any],
+        on: Optional[Union[str, exp.Expression, "SQL"]] = None,
+        alias: Optional[str] = None,
+    ) -> Self:
+        """Create a LATERAL JOIN.
+
+        Args:
+            table: Table, subquery, or table function to join
+            on: Optional join condition (for LATERAL JOINs with ON clause)
+            alias: Optional alias for the joined table/subquery
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            ```python
+            query = (
+                sql.select("u.name", "arr.value")
+                .from_("users u")
+                .lateral_join("UNNEST(u.tags)", alias="arr")
+            )
+            ```
+        """
+        return self.join(table, on=on, alias=alias, join_type="INNER", lateral=True)
+
+    def left_lateral_join(
+        self,
+        table: Union[str, exp.Expression, Any],
+        on: Optional[Union[str, exp.Expression, "SQL"]] = None,
+        alias: Optional[str] = None,
+    ) -> Self:
+        """Create a LEFT LATERAL JOIN.
+
+        Args:
+            table: Table, subquery, or table function to join
+            on: Optional join condition
+            alias: Optional alias for the joined table/subquery
+
+        Returns:
+            Self for method chaining
+        """
+        return self.join(table, on=on, alias=alias, join_type="LEFT", lateral=True)
+
+    def cross_lateral_join(self, table: Union[str, exp.Expression, Any], alias: Optional[str] = None) -> Self:
+        """Create a CROSS LATERAL JOIN (no ON condition).
+
+        Args:
+            table: Table, subquery, or table function to join
+            alias: Optional alias for the joined table/subquery
+
+        Returns:
+            Self for method chaining
+        """
+        return self.join(table, on=None, alias=alias, join_type="CROSS", lateral=True)
+
 
 @trait
 class JoinBuilder:
@@ -181,32 +296,19 @@ class JoinBuilder:
         ```
     """
 
-    def __init__(self, join_type: str) -> None:
+    def __init__(self, join_type: str, lateral: bool = False) -> None:
         """Initialize the join builder.
 
         Args:
-            join_type: Type of join (inner, left, right, full, cross)
+            join_type: Type of join (inner, left, right, full, cross, lateral)
+            lateral: Whether this is a LATERAL join
         """
         self._join_type = join_type.upper()
+        self._lateral = lateral
         self._table: Optional[Union[str, exp.Expression]] = None
         self._condition: Optional[exp.Expression] = None
         self._alias: Optional[str] = None
 
-    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
-        """Equal to (==) - not typically used but needed for type consistency."""
-        from sqlspec.builder._column import ColumnExpression
-
-        # JoinBuilder doesn't have a direct expression, so this is a placeholder
-        # In practice, this shouldn't be called as joins are used differently
-        placeholder_expr = exp.Literal.string(f"join_{self._join_type.lower()}")
-        if other is None:
-            return ColumnExpression(exp.Is(this=placeholder_expr, expression=exp.Null()))
-        return ColumnExpression(exp.EQ(this=placeholder_expr, expression=exp.convert(other)))
-
-    def __hash__(self) -> int:
-        """Make JoinBuilder hashable."""
-        return hash(id(self))
-
     def __call__(self, table: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
         """Set the table to join.
 
@@ -254,15 +356,33 @@ class JoinBuilder:
                 table_expr = exp.alias_(table_expr, self._alias)
 
         # Create the appropriate join type using same pattern as existing JoinClauseMixin
-        if self._join_type == "INNER JOIN":
-            return exp.Join(this=table_expr, on=condition_expr)
-        if self._join_type == "LEFT JOIN":
-            return exp.Join(this=table_expr, on=condition_expr, side="LEFT")
-        if self._join_type == "RIGHT JOIN":
-            return exp.Join(this=table_expr, on=condition_expr, side="RIGHT")
-        if self._join_type == "FULL JOIN":
-            return exp.Join(this=table_expr, on=condition_expr, side="FULL", kind="OUTER")
-        if self._join_type == "CROSS JOIN":
+        if self._join_type in {"INNER JOIN", "INNER", "LATERAL JOIN"}:
+            join_expr = exp.Join(this=table_expr, on=condition_expr)
+        elif self._join_type in {"LEFT JOIN", "LEFT"}:
+            join_expr = exp.Join(this=table_expr, on=condition_expr, side="LEFT")
+        elif self._join_type in {"RIGHT JOIN", "RIGHT"}:
+            join_expr = exp.Join(this=table_expr, on=condition_expr, side="RIGHT")
+        elif self._join_type in {"FULL JOIN", "FULL"}:
+            join_expr = exp.Join(this=table_expr, on=condition_expr, side="FULL", kind="OUTER")
+        elif self._join_type in {"CROSS JOIN", "CROSS"}:
             # CROSS JOIN doesn't use ON condition
-            return exp.Join(this=table_expr, kind="CROSS")
-        return exp.Join(this=table_expr, on=condition_expr)
+            join_expr = exp.Join(this=table_expr, kind="CROSS")
+        else:
+            join_expr = exp.Join(this=table_expr, on=condition_expr)
+
+        if self._lateral or self._join_type == "LATERAL JOIN":
+            current_kind = join_expr.args.get("kind")
+            current_side = join_expr.args.get("side")
+
+            if current_kind == "CROSS":
+                join_expr.set("kind", "CROSS LATERAL")
+            elif current_kind == "OUTER" and current_side == "FULL":
+                join_expr.set("side", "FULL")  # Keep side
+                join_expr.set("kind", "OUTER LATERAL")
+            elif current_side:
+                join_expr.set("kind", f"{current_side} LATERAL")
+                join_expr.set("side", None)  # Clear side to avoid duplication
+            else:
+                join_expr.set("kind", "LATERAL")
+
+        return join_expr

{sqlspec-0.22.0.dist-info → sqlspec-0.23.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.22.0
+Version: 0.23.0
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.22.0.dist-info → sqlspec-0.23.0.dist-info}/RECORD

@@ -2,7 +2,7 @@ sqlspec/__init__.py,sha256=JkL9cp1h19tz1rCl-3WAep6kbZs8JLxNlb1SrQl8PWc,2114
 sqlspec/__main__.py,sha256=lXBKZMOXA1uY735Rnsb-GS7aXy0nt22tYmd2X9FcxrY,253
 sqlspec/__metadata__.py,sha256=IUw6MCTy1oeUJ1jAVYbuJLkOWbiAWorZ5W-E-SAD9N4,395
 sqlspec/_serialization.py,sha256=6U5-smk2h2yl0i6am2prtOLJTdu4NJQdcLlSfSUMaUQ,2590
-sqlspec/_sql.py,sha256=j9WljOgCme4jTfL6NegEWOhK-Rr3JEmhtbneh8ZN1bQ,45221
+sqlspec/_sql.py,sha256=QHx_awVF6yFxcNLcuAk19AnJe1FvX1FwqjxhJcUjXD4,46221
 sqlspec/_typing.py,sha256=jv-7QHGLrJLfnP86bR-Xcmj3PDoddNZEKDz_vYRBiAU,22684
 sqlspec/base.py,sha256=koDh1AecwCAkntSqSda6J_cpMOLonXiV6hh3GCCXf_s,25459
 sqlspec/cli.py,sha256=Fe5Wbnrb_fkE9qm4gbBEXx3d0Q7VR-S-1t76ouAx2mg,20120
@@ -72,7 +72,7 @@ sqlspec/builder/mixins/__init__.py,sha256=YXhAzKmQbQtne5j26SKWY8PUxwosl0RhlhLoah
 sqlspec/builder/mixins/_cte_and_set_ops.py,sha256=gANbAnL7ulkIMS1NG47nd_5laEsjwmEaROu-kTVbbF4,9152
 sqlspec/builder/mixins/_delete_operations.py,sha256=LCzXoNtPUVgJ5KxhKoQj-METq51g5aDqoEmDmB66e08,1271
 sqlspec/builder/mixins/_insert_operations.py,sha256=ipU1Hhue6MRFfbouDDXyONGC9-jmW7LYuo4HuMtioJs,10437
-sqlspec/builder/mixins/_join_operations.py,sha256=TjVK6uJjhzbg4kmbMBCQkuW-UgTKqpFHvaKcSFOeB_w,11530
+sqlspec/builder/mixins/_join_operations.py,sha256=1CN1E6TwtFng4ftKmIYN0MAJNZLkWISGB2UY1E1tivw,16036
 sqlspec/builder/mixins/_merge_operations.py,sha256=v2JZbyOZyT5mS0cJo82ckjE9eR2LqoAS-YO2NJWK2a4,24297
 sqlspec/builder/mixins/_order_limit_operations.py,sha256=i5QXZ_1aCzAhv3VG4Tp08kW8vYqEHU04TRoZPZgS2KA,5573
 sqlspec/builder/mixins/_pivot_operations.py,sha256=s3b2zSOL0zEXEGXo1lBm5MuqXWl15qMww_krsmFqj3I,6163
@@ -131,9 +131,9 @@ sqlspec/utils/singleton.py,sha256=-j-s6LS0pP_wTEUYIyK2wSdoeIE_tn7O7B-j7_aODRQ,12
 sqlspec/utils/sync_tools.py,sha256=ONdhmx1Dq0_c6ReRaTlXzz6dVmAwz6CybCvsTUAVu1g,8768
 sqlspec/utils/text.py,sha256=ZqaXCVuUbdj_110pdTYjmAxfV3ZtR7J6EixuNazQLFY,3333
 sqlspec/utils/type_guards.py,sha256=ktXwBQLLqOvk1W2wJcmk3bUprrsegs8nAZ879qDe0AU,32880
-sqlspec-0.22.0.dist-info/METADATA,sha256=DZJrWaO7T5jLPe2GlL6M_MmKveqCb-oU1Awx3CDm6J0,23548
-sqlspec-0.22.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sqlspec-0.22.0.dist-info/entry_points.txt,sha256=G-ZqY1Nuuw3Iys7nXw23f6ILenk_Lt47VdK2mhJCWHg,53
-sqlspec-0.22.0.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
-sqlspec-0.22.0.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
-sqlspec-0.22.0.dist-info/RECORD,,
+sqlspec-0.23.0.dist-info/METADATA,sha256=bSrPoVRmVNHSvsvNGO7j_Il8xpIlsHqz82B57bjjbRM,23548
+sqlspec-0.23.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sqlspec-0.23.0.dist-info/entry_points.txt,sha256=G-ZqY1Nuuw3Iys7nXw23f6ILenk_Lt47VdK2mhJCWHg,53
+sqlspec-0.23.0.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
+sqlspec-0.23.0.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
+sqlspec-0.23.0.dist-info/RECORD,,