sqlspec 0.16.1__py3-none-any.whl → 0.17.0__py3-none-any.whl

sqlspec/builder/_parsing_utils.py

@@ -9,10 +9,13 @@ from typing import Any, Final, Optional, Union, cast
 
 from sqlglot import exp, maybe_parse, parse_one
 
+from sqlspec.core.parameters import ParameterStyle
 from sqlspec.utils.type_guards import has_expression_attr, has_parameter_builder
 
 
-def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> exp.Expression:
+def parse_column_expression(
+    column_input: Union[str, exp.Expression, Any], builder: Optional[Any] = None
+) -> exp.Expression:
     """Parse a column input that might be a complex expression.
 
     Handles cases like:
@@ -22,9 +25,11 @@ def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> ex
     - Function calls: "MAX(price)" -> Max(this=Column(price))
     - Complex expressions: "CASE WHEN ... END" -> Case(...)
     - Custom Column objects from our builder
+    - SQL objects with raw SQL expressions
 
     Args:
-        column_input: String, SQLGlot expression, or Column object
+        column_input: String, SQLGlot expression, SQL object, or Column object
+        builder: Optional builder instance for parameter merging
 
     Returns:
         exp.Expression: Parsed SQLGlot expression
@@ -32,6 +37,26 @@ def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> ex
     if isinstance(column_input, exp.Expression):
         return column_input
 
+    # Handle SQL objects (from sql.raw with parameters)
+    if hasattr(column_input, "expression") and hasattr(column_input, "sql"):
+        # This is likely a SQL object
+        expression = getattr(column_input, "expression", None)
+        if expression is not None and isinstance(expression, exp.Expression):
+            # Merge parameters from SQL object into builder if available
+            if builder and hasattr(column_input, "parameters") and hasattr(builder, "add_parameter"):
+                sql_parameters = getattr(column_input, "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(column_input, "sql", "")
+        # Merge parameters even when parsing raw SQL
+        if builder and hasattr(column_input, "parameters") and hasattr(builder, "add_parameter"):
+            sql_parameters = getattr(column_input, "parameters", {})
+            for param_name, param_value in sql_parameters.items():
+                builder.add_parameter(param_value, name=param_name)
+        return exp.maybe_parse(sql_text) or exp.column(str(sql_text))
+
     if has_expression_attr(column_input):
         try:
             attr_value = column_input._expression
@@ -127,6 +152,32 @@ def parse_condition_expression(
     if not isinstance(condition_input, str):
         condition_input = str(condition_input)
 
+    # Convert database-specific parameter styles to SQLGlot-compatible format
+    # This ensures that placeholders like $1, %s, :1 are properly recognized as parameters
+    from sqlspec.core.parameters import ParameterValidator
+
+    validator = ParameterValidator()
+    param_info = validator.extract_parameters(condition_input)
+
+    # If we found parameters, convert incompatible ones to SQLGlot-compatible format
+    if param_info:
+        # Convert problematic parameter styles to :param_N format for SQLGlot
+        converted_condition = condition_input
+        for param in reversed(param_info):  # Reverse to preserve positions
+            if param.style in {
+                ParameterStyle.NUMERIC,
+                ParameterStyle.POSITIONAL_PYFORMAT,
+                ParameterStyle.POSITIONAL_COLON,
+            }:
+                # Convert $1, %s, :1 to :param_0, :param_1, etc.
+                placeholder = f":param_{param.ordinal}"
+                converted_condition = (
+                    converted_condition[: param.position]
+                    + placeholder
+                    + converted_condition[param.position + len(param.placeholder_text) :]
+                )
+        condition_input = converted_condition
+
     try:
         return exp.condition(condition_input)
     except Exception:

sqlspec/builder/mixins/_join_operations.py

@@ -9,9 +9,11 @@ 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
 
-__all__ = ("JoinClauseMixin",)
+__all__ = ("JoinBuilder", "JoinClauseMixin")
 
 
 @trait
@@ -26,7 +28,7 @@ class JoinClauseMixin:
     def join(
         self,
         table: Union[str, exp.Expression, Any],
-        on: Optional[Union[str, exp.Expression]] = None,
+        on: Optional[Union[str, exp.Expression, "SQL"]] = None,
         alias: Optional[str] = None,
         join_type: str = "INNER",
     ) -> Self:
@@ -56,7 +58,33 @@ class JoinClauseMixin:
             table_expr = table
         on_expr: Optional[exp.Expression] = None
         if on is not None:
-            on_expr = exp.condition(on) if isinstance(on, str) else on
+            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))
         join_type_upper = join_type.upper()
         if join_type_upper == "INNER":
             join_expr = exp.Join(this=table_expr, on=on_expr)
@@ -73,22 +101,22 @@ class JoinClauseMixin:
         return cast("Self", builder)
 
     def inner_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression], alias: Optional[str] = None
+        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
     ) -> Self:
         return self.join(table, on, alias, "INNER")
 
     def left_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression], alias: Optional[str] = None
+        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
     ) -> Self:
         return self.join(table, on, alias, "LEFT")
 
     def right_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression], alias: Optional[str] = None
+        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
     ) -> Self:
         return self.join(table, on, alias, "RIGHT")
 
     def full_join(
-        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression], alias: Optional[str] = None
+        self, table: Union[str, exp.Expression, Any], on: Union[str, exp.Expression, "SQL"], alias: Optional[str] = None
     ) -> Self:
         return self.join(table, on, alias, "FULL")
 
@@ -120,3 +148,116 @@ class JoinClauseMixin:
         join_expr = exp.Join(this=table_expr, kind="CROSS")
         builder._expression = builder._expression.join(join_expr, copy=False)
         return cast("Self", builder)
+
+
+@trait
+class JoinBuilder:
+    """Builder for JOIN operations with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.left_join_("posts").on("users.id = posts.user_id")
+        join_clause = sql.left_join_("posts").on(
+            "users.id = posts.user_id"
+        )
+
+        # Or with query builder
+        query = (
+            sql.select("users.name", "posts.title")
+            .from_("users")
+            .join(
+                sql.left_join_("posts").on(
+                    "users.id = posts.user_id"
+                )
+            )
+        )
+        ```
+    """
+
+    def __init__(self, join_type: str) -> None:
+        """Initialize the join builder.
+
+        Args:
+            join_type: Type of join (inner, left, right, full, cross)
+        """
+        self._join_type = join_type.upper()
+        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.
+
+        Args:
+            table: Table name or expression to join
+            alias: Optional alias for the table
+
+        Returns:
+            Self for method chaining
+        """
+        self._table = table
+        self._alias = alias
+        return self
+
+    def on(self, condition: Union[str, exp.Expression]) -> exp.Expression:
+        """Set the join condition and build the JOIN expression.
+
+        Args:
+            condition: JOIN condition (e.g., "users.id = posts.user_id")
+
+        Returns:
+            Complete JOIN expression
+        """
+        if not self._table:
+            msg = "Table must be set before calling .on()"
+            raise SQLBuilderError(msg)
+
+        # Parse the condition
+        condition_expr: exp.Expression
+        if isinstance(condition, str):
+            parsed: Optional[exp.Expression] = exp.maybe_parse(condition)
+            condition_expr = parsed or exp.condition(condition)
+        else:
+            condition_expr = condition
+
+        # Build table expression
+        table_expr: exp.Expression
+        if isinstance(self._table, str):
+            table_expr = exp.to_table(self._table)
+            if self._alias:
+                table_expr = exp.alias_(table_expr, self._alias)
+        else:
+            table_expr = self._table
+            if self._alias:
+                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":
+            # CROSS JOIN doesn't use ON condition
+            return exp.Join(this=table_expr, kind="CROSS")
+        return exp.Join(this=table_expr, on=condition_expr)

sqlspec/builder/mixins/_merge_operations.py

@@ -179,14 +179,23 @@ class MergeMatchedClauseMixin:
         whens.append("expressions", when_clause)
 
     def when_matched_then_update(
-        self, set_values: dict[str, Any], condition: Optional[Union[str, exp.Expression]] = None
+        self,
+        set_values: Optional[dict[str, Any]] = None,
+        condition: Optional[Union[str, exp.Expression]] = None,
+        **kwargs: Any,
     ) -> Self:
         """Define the UPDATE action for matched rows.
 
+        Supports:
+        - when_matched_then_update({"column": value})
+        - when_matched_then_update(column=value, other_column=other_value)
+        - when_matched_then_update({"column": value}, other_column=other_value)
+
         Args:
             set_values: A dictionary of column names and their new values to set.
                         The values will be parameterized.
             condition: An optional additional condition for this specific action.
+            **kwargs: Column-value pairs to update on match.
 
         Raises:
             SQLBuilderError: If the condition type is unsupported.
@@ -194,14 +203,48 @@ class MergeMatchedClauseMixin:
         Returns:
             The current builder instance for method chaining.
         """
+        # Combine set_values dict and kwargs
+        all_values = dict(set_values or {}, **kwargs)
+
+        if not all_values:
+            msg = "No update values provided. Use set_values dict or kwargs."
+            raise SQLBuilderError(msg)
+
         update_expressions: list[exp.EQ] = []
-        for col, val in set_values.items():
-            column_name = col if isinstance(col, str) else str(col)
-            if "." in column_name:
-                column_name = column_name.split(".")[-1]
-            param_name = self._generate_unique_parameter_name(column_name)
-            param_name = self.add_parameter(val, name=param_name)[1]
-            update_expressions.append(exp.EQ(this=exp.column(col), expression=exp.var(param_name)))
+        for col, val in all_values.items():
+            if hasattr(val, "expression") and hasattr(val, "sql"):
+                # Handle SQL objects (from sql.raw with parameters)
+                expression = getattr(val, "expression", None)
+                if expression is not None and isinstance(expression, exp.Expression):
+                    # Merge parameters from SQL object into builder
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    value_expr = expression
+                else:
+                    # If expression is None, fall back to parsing the raw SQL
+                    sql_text = getattr(val, "sql", "")
+                    # Merge parameters even when parsing raw SQL
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    # Check if sql_text is callable (like Expression.sql method)
+                    if callable(sql_text):
+                        sql_text = str(val)
+                    value_expr = exp.maybe_parse(sql_text) or exp.convert(str(sql_text))
+            elif isinstance(val, exp.Expression):
+                value_expr = val
+            else:
+                column_name = col if isinstance(col, str) else str(col)
+                if "." in column_name:
+                    column_name = column_name.split(".")[-1]
+                param_name = self._generate_unique_parameter_name(column_name)
+                param_name = self.add_parameter(val, name=param_name)[1]
+                value_expr = exp.Placeholder(this=param_name)
+
+            update_expressions.append(exp.EQ(this=exp.column(col), expression=value_expr))
 
         when_args: dict[str, Any] = {"matched": True, "then": exp.Update(expressions=update_expressions)}
 
@@ -386,15 +429,24 @@ class MergeNotMatchedBySourceClauseMixin:
         raise NotImplementedError(msg)
 
     def when_not_matched_by_source_then_update(
-        self, set_values: dict[str, Any], condition: Optional[Union[str, exp.Expression]] = None
+        self,
+        set_values: Optional[dict[str, Any]] = None,
+        condition: Optional[Union[str, exp.Expression]] = None,
+        **kwargs: Any,
     ) -> Self:
         """Define the UPDATE action for rows not matched by source.
 
         This is useful for handling rows that exist in the target but not in the source.
 
+        Supports:
+        - when_not_matched_by_source_then_update({"column": value})
+        - when_not_matched_by_source_then_update(column=value, other_column=other_value)
+        - when_not_matched_by_source_then_update({"column": value}, other_column=other_value)
+
         Args:
             set_values: A dictionary of column names and their new values to set.
             condition: An optional additional condition for this specific action.
+            **kwargs: Column-value pairs to update when not matched by source.
 
         Raises:
             SQLBuilderError: If the condition type is unsupported.
@@ -402,14 +454,48 @@ class MergeNotMatchedBySourceClauseMixin:
         Returns:
             The current builder instance for method chaining.
         """
+        # Combine set_values dict and kwargs
+        all_values = dict(set_values or {}, **kwargs)
+
+        if not all_values:
+            msg = "No update values provided. Use set_values dict or kwargs."
+            raise SQLBuilderError(msg)
+
         update_expressions: list[exp.EQ] = []
-        for col, val in set_values.items():
-            column_name = col if isinstance(col, str) else str(col)
-            if "." in column_name:
-                column_name = column_name.split(".")[-1]
-            param_name = self._generate_unique_parameter_name(column_name)
-            param_name = self.add_parameter(val, name=param_name)[1]
-            update_expressions.append(exp.EQ(this=exp.column(col), expression=exp.var(param_name)))
+        for col, val in all_values.items():
+            if hasattr(val, "expression") and hasattr(val, "sql"):
+                # Handle SQL objects (from sql.raw with parameters)
+                expression = getattr(val, "expression", None)
+                if expression is not None and isinstance(expression, exp.Expression):
+                    # Merge parameters from SQL object into builder
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    value_expr = expression
+                else:
+                    # If expression is None, fall back to parsing the raw SQL
+                    sql_text = getattr(val, "sql", "")
+                    # Merge parameters even when parsing raw SQL
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    # Check if sql_text is callable (like Expression.sql method)
+                    if callable(sql_text):
+                        sql_text = str(val)
+                    value_expr = exp.maybe_parse(sql_text) or exp.convert(str(sql_text))
+            elif isinstance(val, exp.Expression):
+                value_expr = val
+            else:
+                column_name = col if isinstance(col, str) else str(col)
+                if "." in column_name:
+                    column_name = column_name.split(".")[-1]
+                param_name = self._generate_unique_parameter_name(column_name)
+                param_name = self.add_parameter(val, name=param_name)[1]
+                value_expr = exp.Placeholder(this=param_name)
+
+            update_expressions.append(exp.EQ(this=exp.column(col), expression=value_expr))
 
         when_args: dict[str, Any] = {
             "matched": False,