sqlspec 0.16.2__py3-none-any.whl → 0.17.1__py3-none-any.whl

sqlspec/_sql.py

@@ -4,10 +4,9 @@ Provides both statement builders (select, insert, update, etc.) and column expre
 """
 
 import logging
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 import sqlglot
-from mypy_extensions import trait
 from sqlglot import exp
 from sqlglot.dialects.dialect import DialectType
 from sqlglot.errors import ParseError as SQLGlotParseError
@@ -34,12 +33,22 @@ from sqlspec.builder import (
     Truncate,
     Update,
 )
+from sqlspec.builder._expression_wrappers import (
+    AggregateExpression,
+    ConversionExpression,
+    FunctionExpression,
+    MathExpression,
+    StringExpression,
+)
+from sqlspec.builder.mixins._join_operations import JoinBuilder
+from sqlspec.builder.mixins._select_operations import Case, SubqueryBuilder, WindowFunctionBuilder
 from sqlspec.exceptions import SQLBuilderError
 
 if TYPE_CHECKING:
-    from sqlspec.builder._column import ColumnExpression
+    from sqlspec.builder._expression_wrappers import ExpressionWrapper
     from sqlspec.core.statement import SQL
 
+
 __all__ = (
     "AlterTable",
     "Case",
@@ -179,7 +188,7 @@ class SQLFactory:
     # Statement Builders
     # ===================
     def select(
-        self, *columns_or_sql: Union[str, exp.Expression, Column, "SQL"], dialect: DialectType = None
+        self, *columns_or_sql: Union[str, exp.Expression, Column, "SQL", "Case"], dialect: DialectType = None
     ) -> "Select":
         builder_dialect = dialect or self.dialect
         if len(columns_or_sql) == 1 and isinstance(columns_or_sql[0], str):
@@ -223,7 +232,10 @@ class SQLFactory:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
                 if detected != "UPDATE":
-                    msg = f"sql.update() expects UPDATE statement, got {detected}. Use sql.{detected.lower()}() if a dedicated builder exists."
+                    msg = (
+                        f"sql.update() expects UPDATE statement, got {detected}. "
+                        f"Use sql.{detected.lower()}() if a dedicated builder exists."
+                    )
                     raise SQLBuilderError(msg)
                 return self._populate_update_from_sql(builder, table_or_sql)
             return builder.table(table_or_sql)
@@ -235,7 +247,10 @@ class SQLFactory:
         if table_or_sql and self._looks_like_sql(table_or_sql):
             detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
             if detected != "DELETE":
-                msg = f"sql.delete() expects DELETE statement, got {detected}. Use sql.{detected.lower()}() if a dedicated builder exists."
+                msg = (
+                    f"sql.delete() expects DELETE statement, got {detected}. "
+                    f"Use sql.{detected.lower()}() if a dedicated builder exists."
+                )
                 raise SQLBuilderError(msg)
             return self._populate_delete_from_sql(builder, table_or_sql)
         return builder
@@ -247,7 +262,10 @@ class SQLFactory:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
                 if detected != "MERGE":
-                    msg = f"sql.merge() expects MERGE statement, got {detected}. Use sql.{detected.lower()}() if a dedicated builder exists."
+                    msg = (
+                        f"sql.merge() expects MERGE statement, got {detected}. "
+                        f"Use sql.{detected.lower()}() if a dedicated builder exists."
+                    )
                     raise SQLBuilderError(msg)
                 return self._populate_merge_from_sql(builder, table_or_sql)
             return builder.into(table_or_sql)
@@ -737,7 +755,9 @@ class SQLFactory:
     # ===================
 
     @staticmethod
-    def count(column: Union[str, exp.Expression] = "*", distinct: bool = False) -> exp.Expression:
+    def count(
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case", "Column"] = "*", distinct: bool = False
+    ) -> AggregateExpression:
         """Create a COUNT expression.
 
         Args:
@@ -747,12 +767,14 @@ class SQLFactory:
         Returns:
             COUNT expression.
         """
-        if column == "*":
-            return exp.Count(this=exp.Star(), distinct=distinct)
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Count(this=col_expr, distinct=distinct)
+        if isinstance(column, str) and column == "*":
+            expr = exp.Count(this=exp.Star(), distinct=distinct)
+        else:
+            col_expr = SQLFactory._extract_expression(column)
+            expr = exp.Count(this=col_expr, distinct=distinct)
+        return AggregateExpression(expr)
 
-    def count_distinct(self, column: Union[str, exp.Expression]) -> exp.Expression:
+    def count_distinct(self, column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create a COUNT(DISTINCT column) expression.
 
         Args:
@@ -764,7 +786,9 @@ class SQLFactory:
         return self.count(column, distinct=True)
 
     @staticmethod
-    def sum(column: Union[str, exp.Expression], distinct: bool = False) -> exp.Expression:
+    def sum(
+        column: Union[str, exp.Expression, "ExpressionWrapper", "Case"], distinct: bool = False
+    ) -> AggregateExpression:
         """Create a SUM expression.
 
         Args:
@@ -774,11 +798,11 @@ class SQLFactory:
         Returns:
             SUM expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Sum(this=col_expr, distinct=distinct)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Sum(this=col_expr, distinct=distinct))
 
     @staticmethod
-    def avg(column: Union[str, exp.Expression]) -> exp.Expression:
+    def avg(column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create an AVG expression.
 
         Args:
@@ -787,11 +811,11 @@ class SQLFactory:
         Returns:
             AVG expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Avg(this=col_expr)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Avg(this=col_expr))
 
     @staticmethod
-    def max(column: Union[str, exp.Expression]) -> exp.Expression:
+    def max(column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create a MAX expression.
 
         Args:
@@ -800,11 +824,11 @@ class SQLFactory:
         Returns:
             MAX expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Max(this=col_expr)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Max(this=col_expr))
 
     @staticmethod
-    def min(column: Union[str, exp.Expression]) -> exp.Expression:
+    def min(column: Union[str, exp.Expression, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create a MIN expression.
 
         Args:
@@ -813,15 +837,15 @@ class SQLFactory:
         Returns:
             MIN expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Min(this=col_expr)
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Min(this=col_expr))
 
     # ===================
     # Advanced SQL Operations
     # ===================
 
     @staticmethod
-    def rollup(*columns: Union[str, exp.Expression]) -> exp.Expression:
+    def rollup(*columns: Union[str, exp.Expression]) -> FunctionExpression:
         """Create a ROLLUP expression for GROUP BY clauses.
 
         Args:
@@ -841,10 +865,10 @@ class SQLFactory:
             ```
         """
         column_exprs = [exp.column(col) if isinstance(col, str) else col for col in columns]
-        return exp.Rollup(expressions=column_exprs)
+        return FunctionExpression(exp.Rollup(expressions=column_exprs))
 
     @staticmethod
-    def cube(*columns: Union[str, exp.Expression]) -> exp.Expression:
+    def cube(*columns: Union[str, exp.Expression]) -> FunctionExpression:
         """Create a CUBE expression for GROUP BY clauses.
 
         Args:
@@ -864,10 +888,10 @@ class SQLFactory:
             ```
         """
         column_exprs = [exp.column(col) if isinstance(col, str) else col for col in columns]
-        return exp.Cube(expressions=column_exprs)
+        return FunctionExpression(exp.Cube(expressions=column_exprs))
 
     @staticmethod
-    def grouping_sets(*column_sets: Union[tuple[str, ...], list[str]]) -> exp.Expression:
+    def grouping_sets(*column_sets: Union[tuple[str, ...], list[str]]) -> FunctionExpression:
         """Create a GROUPING SETS expression for GROUP BY clauses.
 
         Args:
@@ -899,10 +923,10 @@ class SQLFactory:
             else:
                 set_expressions.append(exp.column(column_set))
 
-        return exp.GroupingSets(expressions=set_expressions)
+        return FunctionExpression(exp.GroupingSets(expressions=set_expressions))
 
     @staticmethod
-    def any(values: Union[list[Any], exp.Expression, str]) -> exp.Expression:
+    def any(values: Union[list[Any], exp.Expression, str]) -> FunctionExpression:
         """Create an ANY expression for use with comparison operators.
 
         Args:
@@ -923,18 +947,18 @@ class SQLFactory:
             ```
         """
         if isinstance(values, list):
-            literals = [SQLFactory._to_literal(v) for v in values]
-            return exp.Any(this=exp.Array(expressions=literals))
+            literals = [SQLFactory.to_literal(v) for v in values]
+            return FunctionExpression(exp.Any(this=exp.Array(expressions=literals)))
         if isinstance(values, str):
             # Parse as SQL
             parsed = exp.maybe_parse(values)  # type: ignore[var-annotated]
             if parsed:
-                return exp.Any(this=parsed)
-            return exp.Any(this=exp.Literal.string(values))
-        return exp.Any(this=values)
+                return FunctionExpression(exp.Any(this=parsed))
+            return FunctionExpression(exp.Any(this=exp.Literal.string(values)))
+        return FunctionExpression(exp.Any(this=values))
 
     @staticmethod
-    def not_any_(values: Union[list[Any], exp.Expression, str]) -> exp.Expression:
+    def not_any_(values: Union[list[Any], exp.Expression, str]) -> FunctionExpression:
         """Create a NOT ANY expression for use with comparison operators.
 
         Args:
@@ -954,14 +978,14 @@ class SQLFactory:
             )
             ```
         """
-        return SQLFactory.any(values)  # NOT ANY is handled by the comparison operator
+        return SQLFactory.any(values)
 
     # ===================
     # String Functions
     # ===================
 
     @staticmethod
-    def concat(*expressions: Union[str, exp.Expression]) -> exp.Expression:
+    def concat(*expressions: Union[str, exp.Expression]) -> StringExpression:
         """Create a CONCAT expression.
 
         Args:
@@ -971,10 +995,10 @@ class SQLFactory:
             CONCAT expression.
         """
         exprs = [exp.column(expr) if isinstance(expr, str) else expr for expr in expressions]
-        return exp.Concat(expressions=exprs)
+        return StringExpression(exp.Concat(expressions=exprs))
 
     @staticmethod
-    def upper(column: Union[str, exp.Expression]) -> exp.Expression:
+    def upper(column: Union[str, exp.Expression]) -> StringExpression:
         """Create an UPPER expression.
 
         Args:
@@ -984,10 +1008,10 @@ class SQLFactory:
             UPPER expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Upper(this=col_expr)
+        return StringExpression(exp.Upper(this=col_expr))
 
     @staticmethod
-    def lower(column: Union[str, exp.Expression]) -> exp.Expression:
+    def lower(column: Union[str, exp.Expression]) -> StringExpression:
         """Create a LOWER expression.
 
         Args:
@@ -997,10 +1021,10 @@ class SQLFactory:
             LOWER expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Lower(this=col_expr)
+        return StringExpression(exp.Lower(this=col_expr))
 
     @staticmethod
-    def length(column: Union[str, exp.Expression]) -> exp.Expression:
+    def length(column: Union[str, exp.Expression]) -> StringExpression:
         """Create a LENGTH expression.
 
         Args:
@@ -1010,14 +1034,14 @@ class SQLFactory:
             LENGTH expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Length(this=col_expr)
+        return StringExpression(exp.Length(this=col_expr))
 
     # ===================
     # Math Functions
     # ===================
 
     @staticmethod
-    def round(column: Union[str, exp.Expression], decimals: int = 0) -> exp.Expression:
+    def round(column: Union[str, exp.Expression], decimals: int = 0) -> MathExpression:
         """Create a ROUND expression.
 
         Args:
@@ -1029,15 +1053,15 @@ class SQLFactory:
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
         if decimals == 0:
-            return exp.Round(this=col_expr)
-        return exp.Round(this=col_expr, expression=exp.Literal.number(decimals))
+            return MathExpression(exp.Round(this=col_expr))
+        return MathExpression(exp.Round(this=col_expr, expression=exp.Literal.number(decimals)))
 
     # ===================
     # Conversion Functions
     # ===================
 
     @staticmethod
-    def _to_literal(value: Any) -> exp.Expression:
+    def to_literal(value: Any) -> FunctionExpression:
         """Convert a Python value to a SQLGlot literal expression.
 
         Uses SQLGlot's built-in exp.convert() function for optimal dialect-agnostic
@@ -1054,12 +1078,52 @@ class SQLFactory:
         Returns:
             SQLGlot expression representing the literal value.
         """
+        if isinstance(value, exp.Expression):
+            return FunctionExpression(value)
+        return FunctionExpression(exp.convert(value))
+
+    @staticmethod
+    def _to_expression(value: Any) -> exp.Expression:
+        """Convert a Python value to a raw SQLGlot expression.
+
+        Args:
+            value: Python value or SQLGlot expression to convert.
+
+        Returns:
+            Raw SQLGlot expression.
+        """
+        if isinstance(value, exp.Expression):
+            return value
+        return exp.convert(value)
+
+    @staticmethod
+    def _extract_expression(value: Any) -> exp.Expression:
+        """Extract SQLGlot expression from value, handling our wrapper types.
+
+        Args:
+            value: String, SQLGlot expression, or our wrapper type.
+
+        Returns:
+            Raw SQLGlot expression.
+        """
+        from sqlspec.builder._expression_wrappers import ExpressionWrapper
+        from sqlspec.builder.mixins._select_operations import Case
+
+        if isinstance(value, str):
+            return exp.column(value)
+        if isinstance(value, Column):
+            return value._expression
+        if isinstance(value, ExpressionWrapper):
+            return value.expression
+        if isinstance(value, Case):
+            # Case has _expression property via trait
+            return exp.Case(ifs=value._conditions, default=value._default)
         if isinstance(value, exp.Expression):
             return value
         return exp.convert(value)
 
     @staticmethod
-    def decode(column: Union[str, exp.Expression], *args: Union[str, exp.Expression, Any]) -> exp.Expression:
+    def decode(column: Union[str, exp.Expression], *args: Union[str, exp.Expression, Any]) -> FunctionExpression:
         """Create a DECODE expression (Oracle-style conditional logic).
 
         DECODE compares column to each search value and returns the corresponding result.
@@ -1096,22 +1160,22 @@ class SQLFactory:
         for i in range(0, len(args) - 1, 2):
             if i + 1 >= len(args):
                 # Odd number of args means last one is default
-                default = SQLFactory._to_literal(args[i])
+                default = SQLFactory._to_expression(args[i])
                 break
 
             search_val = args[i]
             result_val = args[i + 1]
 
-            search_expr = SQLFactory._to_literal(search_val)
-            result_expr = SQLFactory._to_literal(result_val)
+            search_expr = SQLFactory._to_expression(search_val)
+            result_expr = SQLFactory._to_expression(result_val)
 
             condition = exp.EQ(this=col_expr, expression=search_expr)
-            conditions.append(exp.When(this=condition, then=result_expr))
+            conditions.append(exp.If(this=condition, true=result_expr))
 
-        return exp.Case(ifs=conditions, default=default)
+        return FunctionExpression(exp.Case(ifs=conditions, default=default))
 
     @staticmethod
-    def cast(column: Union[str, exp.Expression], data_type: str) -> exp.Expression:
+    def cast(column: Union[str, exp.Expression], data_type: str) -> ConversionExpression:
         """Create a CAST expression for type conversion.
 
         Args:
@@ -1122,10 +1186,10 @@ class SQLFactory:
             CAST expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Cast(this=col_expr, to=exp.DataType.build(data_type))
+        return ConversionExpression(exp.Cast(this=col_expr, to=exp.DataType.build(data_type)))
 
     @staticmethod
-    def coalesce(*expressions: Union[str, exp.Expression]) -> exp.Expression:
+    def coalesce(*expressions: Union[str, exp.Expression]) -> ConversionExpression:
         """Create a COALESCE expression.
 
         Args:
@@ -1135,10 +1199,12 @@ class SQLFactory:
             COALESCE expression.
         """
         exprs = [exp.column(expr) if isinstance(expr, str) else expr for expr in expressions]
-        return exp.Coalesce(expressions=exprs)
+        return ConversionExpression(exp.Coalesce(expressions=exprs))
 
     @staticmethod
-    def nvl(column: Union[str, exp.Expression], substitute_value: Union[str, exp.Expression, Any]) -> exp.Expression:
+    def nvl(
+        column: Union[str, exp.Expression], substitute_value: Union[str, exp.Expression, Any]
+    ) -> ConversionExpression:
         """Create an NVL (Oracle-style) expression using COALESCE.
 
         Args:
@@ -1149,15 +1215,15 @@ class SQLFactory:
             COALESCE expression equivalent to NVL.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        sub_expr = SQLFactory._to_literal(substitute_value)
-        return exp.Coalesce(expressions=[col_expr, sub_expr])
+        sub_expr = SQLFactory._to_expression(substitute_value)
+        return ConversionExpression(exp.Coalesce(expressions=[col_expr, sub_expr]))
 
     @staticmethod
     def nvl2(
         column: Union[str, exp.Expression],
         value_if_not_null: Union[str, exp.Expression, Any],
         value_if_null: Union[str, exp.Expression, Any],
-    ) -> exp.Expression:
+    ) -> ConversionExpression:
         """Create an NVL2 (Oracle-style) expression using CASE.
 
         NVL2 returns value_if_not_null if column is not NULL,
@@ -1178,22 +1244,22 @@ class SQLFactory:
             ```
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        not_null_expr = SQLFactory._to_literal(value_if_not_null)
-        null_expr = SQLFactory._to_literal(value_if_null)
+        not_null_expr = SQLFactory._to_expression(value_if_not_null)
+        null_expr = SQLFactory._to_expression(value_if_null)
 
         # Create CASE WHEN column IS NOT NULL THEN value_if_not_null ELSE value_if_null END
         is_null = exp.Is(this=col_expr, expression=exp.Null())
         condition = exp.Not(this=is_null)
         when_clause = exp.If(this=condition, true=not_null_expr)
 
-        return exp.Case(ifs=[when_clause], default=null_expr)
+        return ConversionExpression(exp.Case(ifs=[when_clause], default=null_expr))
 
     # ===================
     # Bulk Operations
     # ===================
 
     @staticmethod
-    def bulk_insert(table_name: str, column_count: int, placeholder_style: str = "?") -> exp.Expression:
+    def bulk_insert(table_name: str, column_count: int, placeholder_style: str = "?") -> FunctionExpression:
         """Create bulk INSERT expression for executemany operations.
 
         This is specifically for bulk loading operations like CSV ingestion where
@@ -1228,13 +1294,15 @@ class SQLFactory:
             # Creates: INSERT INTO "my_table" VALUES (:1, :2, :3)
             ```
         """
-        return exp.Insert(
-            this=exp.Table(this=exp.to_identifier(table_name)),
-            expression=exp.Values(
-                expressions=[
-                    exp.Tuple(expressions=[exp.Placeholder(this=placeholder_style) for _ in range(column_count)])
-                ]
-            ),
+        return FunctionExpression(
+            exp.Insert(
+                this=exp.Table(this=exp.to_identifier(table_name)),
+                expression=exp.Values(
+                    expressions=[
+                        exp.Tuple(expressions=[exp.Placeholder(this=placeholder_style) for _ in range(column_count)])
+                    ]
+                ),
+            )
         )
 
     def truncate(self, table_name: str) -> "Truncate":
@@ -1288,7 +1356,7 @@ class SQLFactory:
         self,
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Create a ROW_NUMBER() window function.
 
         Args:
@@ -1304,7 +1372,7 @@ class SQLFactory:
         self,
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Create a RANK() window function.
 
         Args:
@@ -1320,7 +1388,7 @@ class SQLFactory:
         self,
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Create a DENSE_RANK() window function.
 
         Args:
@@ -1338,7 +1406,7 @@ class SQLFactory:
         func_args: list[exp.Expression],
         partition_by: Optional[Union[str, list[str], exp.Expression]] = None,
         order_by: Optional[Union[str, list[str], exp.Expression]] = None,
-    ) -> exp.Expression:
+    ) -> FunctionExpression:
         """Helper to create window function expressions.
 
         Args:
@@ -1364,418 +1432,13 @@ class SQLFactory:
 
         if order_by:
             if isinstance(order_by, str):
-                over_args["order"] = [exp.column(order_by).asc()]
+                over_args["order"] = exp.Order(expressions=[exp.column(order_by).asc()])
             elif isinstance(order_by, list):
-                over_args["order"] = [exp.column(col).asc() for col in order_by]
+                over_args["order"] = exp.Order(expressions=[exp.column(col).asc() for col in order_by])
             elif isinstance(order_by, exp.Expression):
-                over_args["order"] = [order_by]
-
-        return exp.Window(this=func_expr, **over_args)
-
-
-@trait
-class Case:
-    """Builder for CASE expressions using the SQL factory.
-
-    Example:
-        ```python
-        from sqlspec import sql
-
-        case_expr = (
-            sql.case()
-            .when(sql.age < 18, "Minor")
-            .when(sql.age < 65, "Adult")
-            .else_("Senior")
-            .end()
-        )
-        ```
-    """
-
-    def __init__(self) -> None:
-        """Initialize the CASE expression builder."""
-        self._conditions: list[exp.If] = []
-        self._default: Optional[exp.Expression] = None
-
-    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
-        """Equal to (==) - convert to expression then compare."""
-        from sqlspec.builder._column import ColumnExpression
-
-        case_expr = exp.Case(ifs=self._conditions, default=self._default)
-        if other is None:
-            return ColumnExpression(exp.Is(this=case_expr, expression=exp.Null()))
-        return ColumnExpression(exp.EQ(this=case_expr, expression=exp.convert(other)))
-
-    def __hash__(self) -> int:
-        """Make Case hashable."""
-        return hash(id(self))
-
-    def when(self, condition: Union[str, exp.Expression], value: Union[str, exp.Expression, Any]) -> "Case":
-        """Add a WHEN clause.
-
-        Args:
-            condition: Condition to test.
-            value: Value to return if condition is true.
-
-        Returns:
-            Self for method chaining.
-        """
-        cond_expr = exp.maybe_parse(condition) or exp.column(condition) if isinstance(condition, str) else condition
-        val_expr = SQLFactory._to_literal(value)
-
-        # SQLGlot uses exp.If for CASE WHEN clauses, not exp.When
-        when_clause = exp.If(this=cond_expr, true=val_expr)
-        self._conditions.append(when_clause)
-        return self
-
-    def else_(self, value: Union[str, exp.Expression, Any]) -> "Case":
-        """Add an ELSE clause.
-
-        Args:
-            value: Default value to return.
-
-        Returns:
-            Self for method chaining.
-        """
-        self._default = SQLFactory._to_literal(value)
-        return self
-
-    def end(self) -> exp.Expression:
-        """Complete the CASE expression.
-
-        Returns:
-            Complete CASE expression.
-        """
-        return exp.Case(ifs=self._conditions, default=self._default)
-
-    def as_(self, alias: str) -> exp.Alias:
-        """Complete the CASE expression with an alias.
-
-        Args:
-            alias: Alias name for the CASE expression.
-
-        Returns:
-            Aliased CASE expression.
-        """
-        case_expr = exp.Case(ifs=self._conditions, default=self._default)
-        return cast("exp.Alias", exp.alias_(case_expr, alias))
-
-
-@trait
-class WindowFunctionBuilder:
-    """Builder for window functions with fluent syntax.
-
-    Example:
-        ```python
-        from sqlspec import sql
-
-        # sql.row_number_.partition_by("department").order_by("salary")
-        window_func = (
-            sql.row_number_.partition_by("department")
-            .order_by("salary")
-            .as_("row_num")
-        )
-        ```
-    """
-
-    def __init__(self, function_name: str) -> None:
-        """Initialize the window function builder.
-
-        Args:
-            function_name: Name of the window function (row_number, rank, etc.)
-        """
-        self._function_name = function_name
-        self._partition_by_cols: list[exp.Expression] = []
-        self._order_by_cols: list[exp.Expression] = []
-        self._alias: Optional[str] = None
-
-    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
-        """Equal to (==) - convert to expression then compare."""
-        from sqlspec.builder._column import ColumnExpression
-
-        window_expr = self._build_expression()
-        if other is None:
-            return ColumnExpression(exp.Is(this=window_expr, expression=exp.Null()))
-        return ColumnExpression(exp.EQ(this=window_expr, expression=exp.convert(other)))
-
-    def __hash__(self) -> int:
-        """Make WindowFunctionBuilder hashable."""
-        return hash(id(self))
-
-    def partition_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
-        """Add PARTITION BY clause.
-
-        Args:
-            *columns: Columns to partition by.
+                over_args["order"] = exp.Order(expressions=[order_by])
 
-        Returns:
-            Self for method chaining.
-        """
-        for col in columns:
-            col_expr = exp.column(col) if isinstance(col, str) else col
-            self._partition_by_cols.append(col_expr)
-        return self
-
-    def order_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
-        """Add ORDER BY clause.
-
-        Args:
-            *columns: Columns to order by.
-
-        Returns:
-            Self for method chaining.
-        """
-        for col in columns:
-            if isinstance(col, str):
-                col_expr = exp.column(col).asc()
-                self._order_by_cols.append(col_expr)
-            else:
-                # Convert to ordered expression
-                self._order_by_cols.append(exp.Ordered(this=col, desc=False))
-        return self
-
-    def as_(self, alias: str) -> exp.Alias:
-        """Complete the window function with an alias.
-
-        Args:
-            alias: Alias name for the window function.
-
-        Returns:
-            Aliased window function expression.
-        """
-        window_expr = self._build_expression()
-        return cast("exp.Alias", exp.alias_(window_expr, alias))
-
-    def build(self) -> exp.Expression:
-        """Complete the window function without an alias.
-
-        Returns:
-            Window function expression.
-        """
-        return self._build_expression()
-
-    def _build_expression(self) -> exp.Expression:
-        """Build the complete window function expression."""
-        # Create the function expression
-        func_expr = exp.Anonymous(this=self._function_name.upper(), expressions=[])
-
-        # Build the OVER clause arguments
-        over_args: dict[str, Any] = {}
-
-        if self._partition_by_cols:
-            over_args["partition_by"] = self._partition_by_cols
-
-        if self._order_by_cols:
-            over_args["order"] = exp.Order(expressions=self._order_by_cols)
-
-        return exp.Window(this=func_expr, **over_args)
-
-
-@trait
-class SubqueryBuilder:
-    """Builder for subquery operations with fluent syntax.
-
-    Example:
-        ```python
-        from sqlspec import sql
-
-        # sql.exists_(subquery)
-        exists_check = sql.exists_(
-            sql.select("1")
-            .from_("orders")
-            .where_eq("user_id", sql.users.id)
-        )
-
-        # sql.in_(subquery)
-        in_check = sql.in_(
-            sql.select("category_id")
-            .from_("categories")
-            .where_eq("active", True)
-        )
-        ```
-    """
-
-    def __init__(self, operation: str) -> None:
-        """Initialize the subquery builder.
-
-        Args:
-            operation: Type of subquery operation (exists, in, any, all)
-        """
-        self._operation = operation
-
-    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
-
-        # SubqueryBuilder doesn't have a direct expression, so this is a placeholder
-        # In practice, this shouldn't be called as subqueries are used differently
-        placeholder_expr = exp.Literal.string(f"subquery_{self._operation}")
-        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 SubqueryBuilder hashable."""
-        return hash(id(self))
-
-    def __call__(self, subquery: Union[str, exp.Expression, Any]) -> exp.Expression:
-        """Build the subquery expression.
-
-        Args:
-            subquery: The subquery - can be a SQL string, SelectBuilder, or expression
-
-        Returns:
-            The subquery expression (EXISTS, IN, ANY, ALL, etc.)
-        """
-        subquery_expr: exp.Expression
-        if isinstance(subquery, str):
-            # Parse as SQL
-            parsed: Optional[exp.Expression] = exp.maybe_parse(subquery)
-            if not parsed:
-                msg = f"Could not parse subquery SQL: {subquery}"
-                raise SQLBuilderError(msg)
-            subquery_expr = parsed
-        elif hasattr(subquery, "build") and callable(getattr(subquery, "build", None)):
-            # It's a query builder - build it to get the SQL and parse
-            built_query = subquery.build()  # pyright: ignore[reportAttributeAccessIssue]
-            subquery_expr = exp.maybe_parse(built_query.sql)
-            if not subquery_expr:
-                msg = f"Could not parse built query: {built_query.sql}"
-                raise SQLBuilderError(msg)
-        elif isinstance(subquery, exp.Expression):
-            subquery_expr = subquery
-        else:
-            # Try to convert to expression
-            parsed = exp.maybe_parse(str(subquery))
-            if not parsed:
-                msg = f"Could not convert subquery to expression: {subquery}"
-                raise SQLBuilderError(msg)
-            subquery_expr = parsed
-
-        # Build the appropriate expression based on operation
-        if self._operation == "exists":
-            return exp.Exists(this=subquery_expr)
-        if self._operation == "in":
-            # For IN, we create a subquery that can be used with WHERE column IN (subquery)
-            return exp.In(expressions=[subquery_expr])
-        if self._operation == "any":
-            return exp.Any(this=subquery_expr)
-        if self._operation == "all":
-            return exp.All(this=subquery_expr)
-        msg = f"Unknown subquery operation: {self._operation}"
-        raise SQLBuilderError(msg)
-
-
-@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) -> "JoinBuilder":
-        """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)
+        return FunctionExpression(exp.Window(this=func_expr, **over_args))
 
 
 # Create a default SQL factory instance