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

sqlspec/_sql.py

@@ -1,6 +1,6 @@
-"""Unified SQL factory for creating SQL builders and column expressions with a clean API.
+"""SQL factory for creating SQL builders and column expressions.
 
-Provides both statement builders (select, insert, update, etc.) and column expressions.
+Provides statement builders (select, insert, update, etc.) and column expressions.
 """
 
 import logging
@@ -33,12 +33,21 @@ 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.core.statement import SQL
 from sqlspec.exceptions import SQLBuilderError
 
 if TYPE_CHECKING:
-    from sqlspec.core.statement import SQL
+    from sqlspec.builder._expression_wrappers import ExpressionWrapper
+
 
 __all__ = (
     "AlterTable",
@@ -100,7 +109,7 @@ SQL_STARTERS = {
 
 
 class SQLFactory:
-    """Unified factory for creating SQL builders and column expressions with a fluent API."""
+    """Factory for creating SQL builders and column expressions."""
 
     @classmethod
     def detect_sql_type(cls, sql: str, dialect: DialectType = None) -> str:
@@ -127,9 +136,6 @@ class SQLFactory:
         """
         self.dialect = dialect
 
-    # ===================
-    # Callable Interface
-    # ===================
     def __call__(self, statement: str, dialect: DialectType = None) -> "Any":
         """Create a SelectBuilder from a SQL string, only allowing SELECT/CTE queries.
 
@@ -175,9 +181,6 @@ class SQLFactory:
         )
         raise SQLBuilderError(msg)
 
-    # ===================
-    # Statement Builders
-    # ===================
     def select(
         self, *columns_or_sql: Union[str, exp.Expression, Column, "SQL", "Case"], dialect: DialectType = None
     ) -> "Select":
@@ -262,10 +265,6 @@ class SQLFactory:
             return builder.into(table_or_sql)
         return builder
 
-    # ===================
-    # DDL Statement Builders
-    # ===================
-
     def create_table(self, table_name: str, dialect: DialectType = None) -> "CreateTable":
         """Create a CREATE TABLE builder.
 
@@ -276,9 +275,7 @@ class SQLFactory:
         Returns:
             CreateTable builder instance
         """
-        builder = CreateTable(table_name)
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateTable(table_name, dialect=dialect or self.dialect)
 
     def create_table_as_select(self, dialect: DialectType = None) -> "CreateTableAsSelect":
         """Create a CREATE TABLE AS SELECT builder.
@@ -289,35 +286,31 @@ class SQLFactory:
         Returns:
             CreateTableAsSelect builder instance
         """
-        builder = CreateTableAsSelect()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateTableAsSelect(dialect=dialect or self.dialect)
 
-    def create_view(self, dialect: DialectType = None) -> "CreateView":
+    def create_view(self, view_name: str, dialect: DialectType = None) -> "CreateView":
         """Create a CREATE VIEW builder.
 
         Args:
+            view_name: Name of the view to create
             dialect: Optional SQL dialect
 
         Returns:
             CreateView builder instance
         """
-        builder = CreateView()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateView(view_name, dialect=dialect or self.dialect)
 
-    def create_materialized_view(self, dialect: DialectType = None) -> "CreateMaterializedView":
+    def create_materialized_view(self, view_name: str, dialect: DialectType = None) -> "CreateMaterializedView":
         """Create a CREATE MATERIALIZED VIEW builder.
 
         Args:
+            view_name: Name of the materialized view to create
             dialect: Optional SQL dialect
 
         Returns:
             CreateMaterializedView builder instance
         """
-        builder = CreateMaterializedView()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateMaterializedView(view_name, dialect=dialect or self.dialect)
 
     def create_index(self, index_name: str, dialect: DialectType = None) -> "CreateIndex":
         """Create a CREATE INDEX builder.
@@ -331,18 +324,17 @@ class SQLFactory:
         """
         return CreateIndex(index_name, dialect=dialect or self.dialect)
 
-    def create_schema(self, dialect: DialectType = None) -> "CreateSchema":
+    def create_schema(self, schema_name: str, dialect: DialectType = None) -> "CreateSchema":
         """Create a CREATE SCHEMA builder.
 
         Args:
+            schema_name: Name of the schema to create
             dialect: Optional SQL dialect
 
         Returns:
             CreateSchema builder instance
         """
-        builder = CreateSchema()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return CreateSchema(schema_name, dialect=dialect or self.dialect)
 
     def drop_table(self, table_name: str, dialect: DialectType = None) -> "DropTable":
         """Create a DROP TABLE builder.
@@ -356,16 +348,17 @@ class SQLFactory:
         """
         return DropTable(table_name, dialect=dialect or self.dialect)
 
-    def drop_view(self, dialect: DialectType = None) -> "DropView":
+    def drop_view(self, view_name: str, dialect: DialectType = None) -> "DropView":
         """Create a DROP VIEW builder.
 
         Args:
+            view_name: Name of the view to drop
             dialect: Optional SQL dialect
 
         Returns:
             DropView builder instance
         """
-        return DropView(dialect=dialect or self.dialect)
+        return DropView(view_name, dialect=dialect or self.dialect)
 
     def drop_index(self, index_name: str, dialect: DialectType = None) -> "DropIndex":
         """Create a DROP INDEX builder.
@@ -379,16 +372,17 @@ class SQLFactory:
         """
         return DropIndex(index_name, dialect=dialect or self.dialect)
 
-    def drop_schema(self, dialect: DialectType = None) -> "DropSchema":
+    def drop_schema(self, schema_name: str, dialect: DialectType = None) -> "DropSchema":
         """Create a DROP SCHEMA builder.
 
         Args:
+            schema_name: Name of the schema to drop
             dialect: Optional SQL dialect
 
         Returns:
             DropSchema builder instance
         """
-        return DropSchema(dialect=dialect or self.dialect)
+        return DropSchema(schema_name, dialect=dialect or self.dialect)
 
     def alter_table(self, table_name: str, dialect: DialectType = None) -> "AlterTable":
         """Create an ALTER TABLE builder.
@@ -400,22 +394,19 @@ class SQLFactory:
         Returns:
             AlterTable builder instance
         """
-        builder = AlterTable(table_name)
-        builder.dialect = dialect or self.dialect
-        return builder
+        return AlterTable(table_name, dialect=dialect or self.dialect)
 
-    def rename_table(self, dialect: DialectType = None) -> "RenameTable":
+    def rename_table(self, old_name: str, dialect: DialectType = None) -> "RenameTable":
         """Create a RENAME TABLE builder.
 
         Args:
+            old_name: Current name of the table
             dialect: Optional SQL dialect
 
         Returns:
             RenameTable builder instance
         """
-        builder = RenameTable()
-        builder.dialect = dialect or self.dialect
-        return builder
+        return RenameTable(old_name, dialect=dialect or self.dialect)
 
     def comment_on(self, dialect: DialectType = None) -> "CommentOn":
         """Create a COMMENT ON builder.
@@ -426,17 +417,11 @@ class SQLFactory:
         Returns:
             CommentOn builder instance
         """
-        builder = CommentOn()
-        builder.dialect = dialect or self.dialect
-        return builder
-
-    # ===================
-    # SQL Analysis Helpers
-    # ===================
+        return CommentOn(dialect=dialect or self.dialect)
 
     @staticmethod
     def _looks_like_sql(candidate: str, expected_type: Optional[str] = None) -> bool:
-        """Efficiently determine if a string looks like SQL.
+        """Determine if a string looks like SQL.
 
         Args:
             candidate: String to check
@@ -453,12 +438,7 @@ class SQLFactory:
         if expected_type:
             return candidate_upper.startswith(expected_type.upper())
 
-        # More sophisticated check for SQL vs column names
-        # Column names that start with SQL keywords are common (user_id, insert_date, etc.)
         if any(candidate_upper.startswith(starter) for starter in SQL_STARTERS):
-            # Additional checks to distinguish real SQL from column names:
-            # 1. Real SQL typically has spaces (SELECT ... FROM, INSERT INTO, etc.)
-            # 2. Check for common SQL syntax patterns
             return " " in candidate
 
         return False
@@ -466,19 +446,16 @@ class SQLFactory:
     def _populate_insert_from_sql(self, builder: "Insert", sql_string: str) -> "Insert":
         """Parse SQL string and populate INSERT builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Insert):
                 builder._expression = parsed_expr
                 return builder
 
             if isinstance(parsed_expr, exp.Select):
-                # The actual conversion logic can be handled by the builder itself
                 logger.info("Detected SELECT statement for INSERT - may need target table specification")
                 return builder
 
-            # For other statement types, just return the builder as-is
             logger.warning("Cannot create INSERT from %s statement", type(parsed_expr).__name__)
 
         except Exception as e:
@@ -488,8 +465,7 @@ class SQLFactory:
     def _populate_select_from_sql(self, builder: "Select", sql_string: str) -> "Select":
         """Parse SQL string and populate SELECT builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Select):
                 builder._expression = parsed_expr
@@ -504,8 +480,7 @@ class SQLFactory:
     def _populate_update_from_sql(self, builder: "Update", sql_string: str) -> "Update":
         """Parse SQL string and populate UPDATE builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Update):
                 builder._expression = parsed_expr
@@ -520,8 +495,7 @@ class SQLFactory:
     def _populate_delete_from_sql(self, builder: "Delete", sql_string: str) -> "Delete":
         """Parse SQL string and populate DELETE builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Delete):
                 builder._expression = parsed_expr
@@ -536,8 +510,7 @@ class SQLFactory:
     def _populate_merge_from_sql(self, builder: "Merge", sql_string: str) -> "Merge":
         """Parse SQL string and populate MERGE builder using SQLGlot directly."""
         try:
-            # Use SQLGlot directly for parsing - no validation here
-            parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
+            parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Merge):
                 builder._expression = parsed_expr
@@ -549,10 +522,6 @@ class SQLFactory:
             logger.warning("Failed to parse MERGE SQL, falling back to traditional mode: %s", e)
         return builder
 
-    # ===================
-    # Column References
-    # ===================
-
     def column(self, name: str, table: Optional[str] = None) -> Column:
         """Create a column reference.
 
@@ -567,10 +536,10 @@ class SQLFactory:
 
     @property
     def case_(self) -> "Case":
-        """Create a CASE expression builder with improved syntax.
+        """Create a CASE expression builder.
 
         Returns:
-            Case builder instance for fluent CASE expression building.
+            Case builder instance for CASE expression building.
 
         Example:
             ```python
@@ -669,23 +638,15 @@ class SQLFactory:
             Column object for the given name.
 
         Note:
-            Special SQL constructs like case_, row_number_, etc. are now
-            handled as properties for better type safety.
+            Special SQL constructs like case_, row_number_, etc. are
+            handled as properties for type safety.
         """
         return Column(name)
 
-    # ===================
-    # Raw SQL Expressions
-    # ===================
-
     @staticmethod
     def raw(sql_fragment: str, **parameters: Any) -> "Union[exp.Expression, SQL]":
         """Create a raw SQL expression from a string fragment with optional parameters.
 
-        This method makes it explicit that you are passing raw SQL that should
-        be parsed and included directly in the query. Useful for complex expressions,
-        database-specific functions, or when you need precise control over the SQL.
-
         Args:
             sql_fragment: Raw SQL string to parse into an expression.
             **parameters: Named parameters for parameter binding.
@@ -699,22 +660,21 @@ class SQLFactory:
 
         Example:
             ```python
-            # Raw expression without parameters (current behavior)
             expr = sql.raw("COALESCE(name, 'Unknown')")
 
-            # Raw SQL with named parameters (new functionality)
+
             stmt = sql.raw(
                 "LOWER(name) LIKE LOWER(:pattern)", pattern=f"%{query}%"
             )
 
-            # Raw complex expression with parameters
+
             expr = sql.raw(
                 "price BETWEEN :min_price AND :max_price",
                 min_price=100,
                 max_price=500,
             )
 
-            # Raw window function
+
             query = sql.select(
                 "name",
                 sql.raw(
@@ -724,11 +684,9 @@ class SQLFactory:
             ```
         """
         if not parameters:
-            # Original behavior - return pure expression
             try:
-                parsed: Optional[exp.Expression] = exp.maybe_parse(sql_fragment)
-                if parsed is not None:
-                    return parsed
+                parsed: exp.Expression = exp.maybe_parse(sql_fragment)
+                return parsed
                 if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
                     return exp.to_identifier(sql_fragment)
                 return exp.Literal.string(sql_fragment)
@@ -736,17 +694,12 @@ class SQLFactory:
                 msg = f"Failed to parse raw SQL fragment '{sql_fragment}': {e}"
                 raise SQLBuilderError(msg) from e
 
-        # New behavior - return SQL statement with parameters
-        from sqlspec.core.statement import SQL
-
         return SQL(sql_fragment, parameters)
 
-    # ===================
-    # Aggregate Functions
-    # ===================
-
     @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:
@@ -756,12 +709,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)
-
-    def count_distinct(self, column: Union[str, exp.Expression]) -> exp.Expression:
+        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, "ExpressionWrapper", "Case"]) -> AggregateExpression:
         """Create a COUNT(DISTINCT column) expression.
 
         Args:
@@ -773,7 +728,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:
@@ -783,11 +740,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:
@@ -796,11 +753,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:
@@ -809,11 +766,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:
@@ -822,15 +779,11 @@ class SQLFactory:
         Returns:
             MIN expression.
         """
-        col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Min(this=col_expr)
-
-    # ===================
-    # Advanced SQL Operations
-    # ===================
+        col_expr = SQLFactory._extract_expression(column)
+        return AggregateExpression(exp.Min(this=col_expr))
 
     @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,7 +794,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # GROUP BY ROLLUP(product, region)
             query = (
                 sql.select("product", "region", sql.sum("sales"))
                 .from_("sales_data")
@@ -850,10 +802,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,7 +816,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # GROUP BY CUBE(product, region)
             query = (
                 sql.select("product", "region", sql.sum("sales"))
                 .from_("sales_data")
@@ -873,10 +824,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:
@@ -887,7 +838,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # GROUP BY GROUPING SETS ((product), (region), ())
             query = (
                 sql.select("product", "region", sql.sum("sales"))
                 .from_("sales_data")
@@ -908,10 +858,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:
@@ -922,7 +872,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # WHERE id = ANY(subquery)
             subquery = sql.select("user_id").from_("active_users")
             query = (
                 sql.select("*")
@@ -932,18 +881,15 @@ 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)
+            parsed: exp.Expression = exp.maybe_parse(values)
+            return FunctionExpression(exp.Any(this=parsed))
+        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,7 +900,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # WHERE id <> ANY(subquery)
             subquery = sql.select("user_id").from_("blocked_users")
             query = (
                 sql.select("*")
@@ -963,14 +908,10 @@ class SQLFactory:
             )
             ```
         """
-        return SQLFactory.any(values)  # NOT ANY is handled by the comparison operator
-
-    # ===================
-    # String Functions
-    # ===================
+        return SQLFactory.any(values)
 
     @staticmethod
-    def concat(*expressions: Union[str, exp.Expression]) -> exp.Expression:
+    def concat(*expressions: Union[str, exp.Expression]) -> StringExpression:
         """Create a CONCAT expression.
 
         Args:
@@ -980,10 +921,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:
@@ -993,10 +934,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:
@@ -1006,10 +947,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:
@@ -1019,14 +960,10 @@ class SQLFactory:
             LENGTH expression.
         """
         col_expr = exp.column(column) if isinstance(column, str) else column
-        return exp.Length(this=col_expr)
-
-    # ===================
-    # Math Functions
-    # ===================
+        return StringExpression(exp.Length(this=col_expr))
 
     @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:
@@ -1038,19 +975,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))
-
-    # ===================
-    # Conversion Functions
-    # ===================
+            return MathExpression(exp.Round(this=col_expr))
+        return MathExpression(exp.Round(this=col_expr, expression=exp.Literal.number(decimals)))
 
     @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
-        literal creation. Handles all Python primitive types correctly:
+        Uses SQLGlot's built-in exp.convert() function for literal creation.
+        Handles all Python primitive types:
         - None -> exp.Null (renders as NULL)
         - bool -> exp.Boolean (renders as TRUE/FALSE or 1/0 based on dialect)
         - int/float -> exp.Literal with is_number=True
@@ -1063,12 +996,51 @@ 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):
+            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.
@@ -1087,7 +1059,6 @@ class SQLFactory:
 
         Example:
             ```python
-            # DECODE(status, 'A', 'Active', 'I', 'Inactive', 'Unknown')
             sql.decode(
                 "status", "A", "Active", "I", "Inactive", "Unknown"
             )
@@ -1104,23 +1075,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:
@@ -1131,10 +1101,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:
@@ -1144,10 +1114,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:
@@ -1158,15 +1130,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,
@@ -1182,31 +1154,25 @@ class SQLFactory:
 
         Example:
             ```python
-            # NVL2(salary, 'Has Salary', 'No Salary')
             sql.nvl2("salary", "Has Salary", "No Salary")
             ```
         """
         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)
-
-    # ===================
-    # Bulk Operations
-    # ===================
+        return ConversionExpression(exp.Case(ifs=[when_clause], default=null_expr))
 
     @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
-        we need an INSERT expression with placeholders for executemany().
+        For bulk loading operations like CSV ingestion where
+        an INSERT expression with placeholders for executemany() is needed.
 
         Args:
             table_name: Name of the table to insert into
@@ -1214,36 +1180,35 @@ class SQLFactory:
             placeholder_style: Placeholder style ("?" for SQLite/PostgreSQL, "%s" for MySQL, ":1" for Oracle)
 
         Returns:
-            INSERT expression with proper placeholders for bulk operations
+            INSERT expression with placeholders for bulk operations
 
         Example:
             ```python
             from sqlspec import sql
 
-            # SQLite/PostgreSQL style
+
             insert_expr = sql.bulk_insert("my_table", 3)
-            # Creates: INSERT INTO "my_table" VALUES (?, ?, ?)
 
-            # MySQL style
+
             insert_expr = sql.bulk_insert(
                 "my_table", 3, placeholder_style="%s"
             )
-            # Creates: INSERT INTO "my_table" VALUES (%s, %s, %s)
 
-            # Oracle style
+
             insert_expr = sql.bulk_insert(
                 "my_table", 3, placeholder_style=":1"
             )
-            # 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":
@@ -1259,10 +1224,10 @@ class SQLFactory:
             ```python
             from sqlspec import sql
 
-            # Simple truncate
+
             truncate_sql = sql.truncate_table("my_table").build().sql
 
-            # Truncate with options
+
             truncate_sql = (
                 sql.truncate_table("my_table")
                 .cascade()
@@ -1272,13 +1237,7 @@ class SQLFactory:
             )
             ```
         """
-        builder = Truncate(dialect=self.dialect)
-        builder._table_name = table_name
-        return builder
-
-    # ===================
-    # Case Expressions
-    # ===================
+        return Truncate(table_name, dialect=self.dialect)
 
     @staticmethod
     def case() -> "Case":
@@ -1289,15 +1248,11 @@ class SQLFactory:
         """
         return Case()
 
-    # ===================
-    # Window Functions
-    # ===================
-
     def row_number(
         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:
@@ -1313,7 +1268,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:
@@ -1329,7 +1284,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:
@@ -1347,7 +1302,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:
@@ -1373,14 +1328,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]
+                over_args["order"] = exp.Order(expressions=[order_by])
 
-        return exp.Window(this=func_expr, **over_args)
+        return FunctionExpression(exp.Window(this=func_expr, **over_args))
 
 
-# Create a default SQL factory instance
 sql = SQLFactory()