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

sqlspec/_sql.py

@@ -1,21 +1,71 @@
 """Unified SQL factory for creating SQL builders and column expressions with a clean API.
 
-This module provides the `sql` factory object for easy SQL construction:
-- `sql` provides both statement builders (select, insert, update, etc.) and column expressions
+Provides both statement builders (select, insert, update, etc.) and column expressions.
 """
 
 import logging
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 import sqlglot
+from mypy_extensions import trait
 from sqlglot import exp
 from sqlglot.dialects.dialect import DialectType
 from sqlglot.errors import ParseError as SQLGlotParseError
 
+from sqlspec.builder import (
+    AlterTable,
+    Column,
+    CommentOn,
+    CreateIndex,
+    CreateMaterializedView,
+    CreateSchema,
+    CreateTable,
+    CreateTableAsSelect,
+    CreateView,
+    Delete,
+    DropIndex,
+    DropSchema,
+    DropTable,
+    DropView,
+    Insert,
+    Merge,
+    RenameTable,
+    Select,
+    Truncate,
+    Update,
+)
 from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder import Column, Delete, Insert, Merge, Select, Update
 
-__all__ = ("SQLFactory",)
+if TYPE_CHECKING:
+    from sqlspec.builder._column import ColumnExpression
+    from sqlspec.core.statement import SQL
+
+__all__ = (
+    "AlterTable",
+    "Case",
+    "Column",
+    "CommentOn",
+    "CreateIndex",
+    "CreateMaterializedView",
+    "CreateSchema",
+    "CreateTable",
+    "CreateTableAsSelect",
+    "CreateView",
+    "Delete",
+    "DropIndex",
+    "DropSchema",
+    "DropTable",
+    "DropView",
+    "Insert",
+    "Merge",
+    "RenameTable",
+    "SQLFactory",
+    "Select",
+    "Truncate",
+    "Update",
+    "WindowFunctionBuilder",
+    "sql",
+)
 
 logger = logging.getLogger("sqlspec")
 
@@ -50,58 +100,18 @@ SQL_STARTERS = {
 
 
 class SQLFactory:
-    """Unified factory for creating SQL builders and column expressions with a fluent API.
-
-    Provides both statement builders and column expressions through a single, clean interface.
-    Now supports parsing raw SQL strings into appropriate builders for enhanced flexibility.
-
-    Example:
-        ```python
-        from sqlspec import sql
-
-        # Traditional builder usage (unchanged)
-        query = (
-            sql.select(sql.id, sql.name)
-            .from_("users")
-            .where("age > 18")
-        )
-
-        # New: Raw SQL parsing
-        insert_sql = sql.insert(
-            "INSERT INTO users (name, email) VALUES ('John', 'john@example.com')"
-        )
-        select_sql = sql.select(
-            "SELECT * FROM users WHERE active = 1"
-        )
-
-        # RETURNING clause detection
-        returning_insert = sql.insert(
-            "INSERT INTO users (name) VALUES ('John') RETURNING id"
-        )
-        # → When executed, will return SelectResult instead of ExecuteResult
-
-        # Smart INSERT FROM SELECT
-        insert_from_select = sql.insert(
-            "SELECT id, name FROM source WHERE active = 1"
-        )
-        # → Will prompt for target table or convert to INSERT FROM SELECT pattern
-        ```
-    """
+    """Unified factory for creating SQL builders and column expressions with a fluent API."""
 
     @classmethod
     def detect_sql_type(cls, sql: str, dialect: DialectType = None) -> str:
         try:
-            # Minimal parsing just to get the command type
             parsed_expr = sqlglot.parse_one(sql, read=dialect)
             if parsed_expr and parsed_expr.key:
                 return parsed_expr.key.upper()
-            # Fallback for expressions that might not have a direct 'key'
-            # or where key is None (e.g. some DDL without explicit command like SET)
             if parsed_expr:
-                # Attempt to get the class name as a fallback, e.g., "Set", "Command"
                 command_type = type(parsed_expr).__name__.upper()
                 if command_type == "COMMAND" and parsed_expr.this:
-                    return str(parsed_expr.this).upper()  # e.g. "SET", "ALTER"
+                    return str(parsed_expr.this).upper()
                 return command_type
         except SQLGlotParseError:
             logger.debug("Failed to parse SQL for type detection: %s", sql[:100])
@@ -120,15 +130,7 @@ class SQLFactory:
     # ===================
     # Callable Interface
     # ===================
-    def __call__(
-        self,
-        statement: str,
-        parameters: Optional[Any] = None,
-        *filters: Any,
-        config: Optional[Any] = None,
-        dialect: DialectType = None,
-        **kwargs: Any,
-    ) -> "Any":
+    def __call__(self, statement: str, dialect: DialectType = None) -> "Any":
         """Create a SelectBuilder from a SQL string, only allowing SELECT/CTE queries.
 
         Args:
@@ -152,7 +154,6 @@ class SQLFactory:
             msg = f"Failed to parse SQL: {e}"
             raise SQLBuilderError(msg) from e
         actual_type = type(parsed_expr).__name__.upper()
-        # Map sqlglot expression class to type string
         expr_type_map = {
             "SELECT": "SELECT",
             "INSERT": "INSERT",
@@ -177,7 +178,9 @@ class SQLFactory:
     # ===================
     # Statement Builders
     # ===================
-    def select(self, *columns_or_sql: Union[str, exp.Expression, Column], dialect: DialectType = None) -> "Select":
+    def select(
+        self, *columns_or_sql: Union[str, exp.Expression, Column, "SQL"], dialect: DialectType = None
+    ) -> "Select":
         builder_dialect = dialect or self.dialect
         if len(columns_or_sql) == 1 and isinstance(columns_or_sql[0], str):
             sql_candidate = columns_or_sql[0].strip()
@@ -190,12 +193,8 @@ class SQLFactory:
                     )
                     raise SQLBuilderError(msg)
                 select_builder = Select(dialect=builder_dialect)
-                if select_builder._expression is None:
-                    select_builder.__post_init__()
                 return self._populate_select_from_sql(select_builder, sql_candidate)
         select_builder = Select(dialect=builder_dialect)
-        if select_builder._expression is None:
-            select_builder.__post_init__()
         if columns_or_sql:
             select_builder.select(*columns_or_sql)
         return select_builder
@@ -203,8 +202,6 @@ class SQLFactory:
     def insert(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Insert":
         builder_dialect = dialect or self.dialect
         builder = Insert(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -222,8 +219,6 @@ class SQLFactory:
     def update(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Update":
         builder_dialect = dialect or self.dialect
         builder = Update(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -237,8 +232,6 @@ class SQLFactory:
     def delete(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Delete":
         builder_dialect = dialect or self.dialect
         builder = Delete(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         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":
@@ -250,8 +243,6 @@ class SQLFactory:
     def merge(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Merge":
         builder_dialect = dialect or self.dialect
         builder = Merge(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -262,6 +253,174 @@ 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.
+
+        Args:
+            table_name: Name of the table to create
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateTable builder instance
+        """
+        builder = CreateTable(table_name)
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_table_as_select(self, dialect: DialectType = None) -> "CreateTableAsSelect":
+        """Create a CREATE TABLE AS SELECT builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateTableAsSelect builder instance
+        """
+        builder = CreateTableAsSelect()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_view(self, dialect: DialectType = None) -> "CreateView":
+        """Create a CREATE VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateView builder instance
+        """
+        builder = CreateView()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_materialized_view(self, dialect: DialectType = None) -> "CreateMaterializedView":
+        """Create a CREATE MATERIALIZED VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateMaterializedView builder instance
+        """
+        builder = CreateMaterializedView()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_index(self, index_name: str, dialect: DialectType = None) -> "CreateIndex":
+        """Create a CREATE INDEX builder.
+
+        Args:
+            index_name: Name of the index to create
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateIndex builder instance
+        """
+        return CreateIndex(index_name, dialect=dialect or self.dialect)
+
+    def create_schema(self, dialect: DialectType = None) -> "CreateSchema":
+        """Create a CREATE SCHEMA builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateSchema builder instance
+        """
+        builder = CreateSchema()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def drop_table(self, table_name: str, dialect: DialectType = None) -> "DropTable":
+        """Create a DROP TABLE builder.
+
+        Args:
+            table_name: Name of the table to drop
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropTable builder instance
+        """
+        return DropTable(table_name, dialect=dialect or self.dialect)
+
+    def drop_view(self, dialect: DialectType = None) -> "DropView":
+        """Create a DROP VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropView builder instance
+        """
+        return DropView(dialect=dialect or self.dialect)
+
+    def drop_index(self, index_name: str, dialect: DialectType = None) -> "DropIndex":
+        """Create a DROP INDEX builder.
+
+        Args:
+            index_name: Name of the index to drop
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropIndex builder instance
+        """
+        return DropIndex(index_name, dialect=dialect or self.dialect)
+
+    def drop_schema(self, dialect: DialectType = None) -> "DropSchema":
+        """Create a DROP SCHEMA builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropSchema builder instance
+        """
+        return DropSchema(dialect=dialect or self.dialect)
+
+    def alter_table(self, table_name: str, dialect: DialectType = None) -> "AlterTable":
+        """Create an ALTER TABLE builder.
+
+        Args:
+            table_name: Name of the table to alter
+            dialect: Optional SQL dialect
+
+        Returns:
+            AlterTable builder instance
+        """
+        builder = AlterTable(table_name)
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def rename_table(self, dialect: DialectType = None) -> "RenameTable":
+        """Create a RENAME TABLE builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            RenameTable builder instance
+        """
+        builder = RenameTable()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def comment_on(self, dialect: DialectType = None) -> "CommentOn":
+        """Create a COMMENT ON builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CommentOn builder instance
+        """
+        builder = CommentOn()
+        builder.dialect = dialect or self.dialect
+        return builder
+
     # ===================
     # SQL Analysis Helpers
     # ===================
@@ -300,8 +459,6 @@ class SQLFactory:
         try:
             # Use SQLGlot directly for parsing - no validation here
             parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
-            if parsed_expr is None:
-                parsed_expr = sqlglot.parse_one(sql_string, read=self.dialect)
 
             if isinstance(parsed_expr, exp.Insert):
                 builder._expression = parsed_expr
@@ -324,8 +481,6 @@ class SQLFactory:
         try:
             # Use SQLGlot directly for parsing - no validation here
             parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
-            if parsed_expr is None:
-                parsed_expr = sqlglot.parse_one(sql_string, read=self.dialect)
 
             if isinstance(parsed_expr, exp.Select):
                 builder._expression = parsed_expr
@@ -342,8 +497,6 @@ class SQLFactory:
         try:
             # Use SQLGlot directly for parsing - no validation here
             parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
-            if parsed_expr is None:
-                parsed_expr = sqlglot.parse_one(sql_string, read=self.dialect)
 
             if isinstance(parsed_expr, exp.Update):
                 builder._expression = parsed_expr
@@ -360,8 +513,6 @@ class SQLFactory:
         try:
             # Use SQLGlot directly for parsing - no validation here
             parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
-            if parsed_expr is None:
-                parsed_expr = sqlglot.parse_one(sql_string, read=self.dialect)
 
             if isinstance(parsed_expr, exp.Delete):
                 builder._expression = parsed_expr
@@ -378,8 +529,6 @@ class SQLFactory:
         try:
             # Use SQLGlot directly for parsing - no validation here
             parsed_expr = exp.maybe_parse(sql_string, dialect=self.dialect)  # type: ignore[var-annotated]
-            if parsed_expr is None:
-                parsed_expr = sqlglot.parse_one(sql_string, read=self.dialect)
 
             if isinstance(parsed_expr, exp.Merge):
                 builder._expression = parsed_expr
@@ -395,17 +544,194 @@ class SQLFactory:
     # Column References
     # ===================
 
-    def __getattr__(self, name: str) -> Column:
-        """Dynamically create column references.
+    def column(self, name: str, table: Optional[str] = None) -> Column:
+        """Create a column reference.
 
         Args:
             name: Column name.
+            table: Optional table name.
 
         Returns:
             Column object that supports method chaining and operator overloading.
         """
+        return Column(name, table)
+
+    @property
+    def case_(self) -> "Case":
+        """Create a CASE expression builder with improved syntax.
+
+        Returns:
+            Case builder instance for fluent CASE expression building.
+
+        Example:
+            ```python
+            case_expr = (
+                sql.case_.when("x = 1", "one")
+                .when("x = 2", "two")
+                .else_("other")
+                .end()
+            )
+            aliased_case = (
+                sql.case_.when("status = 'active'", 1)
+                .else_(0)
+                .as_("is_active")
+            )
+            ```
+        """
+        return Case()
+
+    @property
+    def row_number_(self) -> "WindowFunctionBuilder":
+        """Create a ROW_NUMBER() window function builder."""
+        return WindowFunctionBuilder("row_number")
+
+    @property
+    def rank_(self) -> "WindowFunctionBuilder":
+        """Create a RANK() window function builder."""
+        return WindowFunctionBuilder("rank")
+
+    @property
+    def dense_rank_(self) -> "WindowFunctionBuilder":
+        """Create a DENSE_RANK() window function builder."""
+        return WindowFunctionBuilder("dense_rank")
+
+    @property
+    def lag_(self) -> "WindowFunctionBuilder":
+        """Create a LAG() window function builder."""
+        return WindowFunctionBuilder("lag")
+
+    @property
+    def lead_(self) -> "WindowFunctionBuilder":
+        """Create a LEAD() window function builder."""
+        return WindowFunctionBuilder("lead")
+
+    @property
+    def exists_(self) -> "SubqueryBuilder":
+        """Create an EXISTS subquery builder."""
+        return SubqueryBuilder("exists")
+
+    @property
+    def in_(self) -> "SubqueryBuilder":
+        """Create an IN subquery builder."""
+        return SubqueryBuilder("in")
+
+    @property
+    def any_(self) -> "SubqueryBuilder":
+        """Create an ANY subquery builder."""
+        return SubqueryBuilder("any")
+
+    @property
+    def all_(self) -> "SubqueryBuilder":
+        """Create an ALL subquery builder."""
+        return SubqueryBuilder("all")
+
+    @property
+    def inner_join_(self) -> "JoinBuilder":
+        """Create an INNER JOIN builder."""
+        return JoinBuilder("inner join")
+
+    @property
+    def left_join_(self) -> "JoinBuilder":
+        """Create a LEFT JOIN builder."""
+        return JoinBuilder("left join")
+
+    @property
+    def right_join_(self) -> "JoinBuilder":
+        """Create a RIGHT JOIN builder."""
+        return JoinBuilder("right join")
+
+    @property
+    def full_join_(self) -> "JoinBuilder":
+        """Create a FULL OUTER JOIN builder."""
+        return JoinBuilder("full join")
+
+    @property
+    def cross_join_(self) -> "JoinBuilder":
+        """Create a CROSS JOIN builder."""
+        return JoinBuilder("cross join")
+
+    def __getattr__(self, name: str) -> "Column":
+        """Dynamically create column references.
+
+        Args:
+            name: Column name.
+
+        Returns:
+            Column object for the given name.
+
+        Note:
+            Special SQL constructs like case_, row_number_, etc. are now
+            handled as properties for better 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.
+
+        Returns:
+            SQLGlot expression from the parsed SQL fragment (if no parameters).
+            SQL statement object (if parameters provided).
+
+        Raises:
+            SQLBuilderError: If the SQL fragment cannot be parsed.
+
+        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(
+                    "ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC)"
+                ),
+            ).from_("employees")
+            ```
+        """
+        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
+                if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
+                    return exp.to_identifier(sql_fragment)
+                return exp.Literal.string(sql_fragment)
+            except Exception as e:
+                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
     # ===================
@@ -597,7 +923,7 @@ class SQLFactory:
             ```
         """
         if isinstance(values, list):
-            literals = [exp.Literal.string(str(v)) if isinstance(v, str) else exp.Literal.number(v) for v in values]
+            literals = [SQLFactory._to_literal(v) for v in values]
             return exp.Any(this=exp.Array(expressions=literals))
         if isinstance(values, str):
             # Parse as SQL
@@ -607,6 +933,29 @@ class SQLFactory:
             return exp.Any(this=exp.Literal.string(values))
         return exp.Any(this=values)
 
+    @staticmethod
+    def not_any_(values: Union[list[Any], exp.Expression, str]) -> exp.Expression:
+        """Create a NOT ANY expression for use with comparison operators.
+
+        Args:
+            values: Values, expression, or subquery for the NOT ANY clause.
+
+        Returns:
+            NOT ANY expression.
+
+        Example:
+            ```python
+            # WHERE id <> ANY(subquery)
+            subquery = sql.select("user_id").from_("blocked_users")
+            query = (
+                sql.select("*")
+                .from_("users")
+                .where(sql.id.neq(sql.not_any(subquery)))
+            )
+            ```
+        """
+        return SQLFactory.any(values)  # NOT ANY is handled by the comparison operator
+
     # ===================
     # String Functions
     # ===================
@@ -687,6 +1036,28 @@ class SQLFactory:
     # Conversion Functions
     # ===================
 
+    @staticmethod
+    def _to_literal(value: Any) -> exp.Expression:
+        """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:
+        - 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
+        - str -> exp.Literal with is_string=True
+        - exp.Expression -> returned as-is (passthrough)
+
+        Args:
+            value: Python value or SQLGlot expression to convert.
+
+        Returns:
+            SQLGlot expression representing the literal value.
+        """
+        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:
         """Create a DECODE expression (Oracle-style conditional logic).
@@ -725,29 +1096,14 @@ 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 = exp.Literal.string(str(args[i])) if not isinstance(args[i], exp.Expression) else args[i]
+                default = SQLFactory._to_literal(args[i])
                 break
 
             search_val = args[i]
             result_val = args[i + 1]
 
-            if isinstance(search_val, str):
-                search_expr = exp.Literal.string(search_val)
-            elif isinstance(search_val, (int, float)):
-                search_expr = exp.Literal.number(search_val)
-            elif isinstance(search_val, exp.Expression):
-                search_expr = search_val  # type: ignore[assignment]
-            else:
-                search_expr = exp.Literal.string(str(search_val))
-
-            if isinstance(result_val, str):
-                result_expr = exp.Literal.string(result_val)
-            elif isinstance(result_val, (int, float)):
-                result_expr = exp.Literal.number(result_val)
-            elif isinstance(result_val, exp.Expression):
-                result_expr = result_val  # type: ignore[assignment]
-            else:
-                result_expr = exp.Literal.string(str(result_val))
+            search_expr = SQLFactory._to_literal(search_val)
+            result_expr = SQLFactory._to_literal(result_val)
 
             condition = exp.EQ(this=col_expr, expression=search_expr)
             conditions.append(exp.When(this=condition, then=result_expr))
@@ -793,30 +1149,136 @@ 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])
 
-        if isinstance(substitute_value, str):
-            sub_expr = exp.Literal.string(substitute_value)
-        elif isinstance(substitute_value, (int, float)):
-            sub_expr = exp.Literal.number(substitute_value)
-        elif isinstance(substitute_value, exp.Expression):
-            sub_expr = substitute_value  # type: ignore[assignment]
-        else:
-            sub_expr = exp.Literal.string(str(substitute_value))
+    @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:
+        """Create an NVL2 (Oracle-style) expression using CASE.
 
-        return exp.Coalesce(expressions=[col_expr, sub_expr])
+        NVL2 returns value_if_not_null if column is not NULL,
+        otherwise returns value_if_null.
+
+        Args:
+            column: Column to check for NULL.
+            value_if_not_null: Value to use if column is NOT NULL.
+            value_if_null: Value to use if column is NULL.
+
+        Returns:
+            CASE expression equivalent to NVL2.
+
+        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)
+
+        # 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
+    # ===================
+
+    @staticmethod
+    def bulk_insert(table_name: str, column_count: int, placeholder_style: str = "?") -> exp.Expression:
+        """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().
+
+        Args:
+            table_name: Name of the table to insert into
+            column_count: Number of columns (for placeholder generation)
+            placeholder_style: Placeholder style ("?" for SQLite/PostgreSQL, "%s" for MySQL, ":1" for Oracle)
+
+        Returns:
+            INSERT expression with proper 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)])
+                ]
+            ),
+        )
+
+    def truncate(self, table_name: str) -> "Truncate":
+        """Create a TRUNCATE TABLE builder.
+
+        Args:
+            table_name: Name of the table to truncate
+
+        Returns:
+            TruncateTable builder instance
+
+        Example:
+            ```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()
+                .restart_identity()
+                .build()
+                .sql
+            )
+            ```
+        """
+        builder = Truncate(dialect=self.dialect)
+        builder._table_name = table_name
+        return builder
 
     # ===================
     # Case Expressions
     # ===================
 
     @staticmethod
-    def case() -> "CaseExpressionBuilder":
+    def case() -> "Case":
         """Create a CASE expression builder.
 
         Returns:
             CaseExpressionBuilder for building CASE expressions.
         """
-        return CaseExpressionBuilder()
+        return Case()
 
     # ===================
     # Window Functions
@@ -911,7 +1373,8 @@ class SQLFactory:
         return exp.Window(this=func_expr, **over_args)
 
 
-class CaseExpressionBuilder:
+@trait
+class Case:
     """Builder for CASE expressions using the SQL factory.
 
     Example:
@@ -930,12 +1393,23 @@ class CaseExpressionBuilder:
 
     def __init__(self) -> None:
         """Initialize the CASE expression builder."""
-        self._conditions: list[exp.When] = []
+        self._conditions: list[exp.If] = []
         self._default: Optional[exp.Expression] = None
 
-    def when(
-        self, condition: Union[str, exp.Expression], value: Union[str, exp.Expression, Any]
-    ) -> "CaseExpressionBuilder":
+    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:
@@ -946,21 +1420,14 @@ class CaseExpressionBuilder:
             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)
 
-        if isinstance(value, str):
-            val_expr = exp.Literal.string(value)
-        elif isinstance(value, (int, float)):
-            val_expr = exp.Literal.number(value)
-        elif isinstance(value, exp.Expression):
-            val_expr = value  # type: ignore[assignment]
-        else:
-            val_expr = exp.Literal.string(str(value))
-
-        when_clause = exp.When(this=cond_expr, then=val_expr)
+        # 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]) -> "CaseExpressionBuilder":
+    def else_(self, value: Union[str, exp.Expression, Any]) -> "Case":
         """Add an ELSE clause.
 
         Args:
@@ -969,14 +1436,7 @@ class CaseExpressionBuilder:
         Returns:
             Self for method chaining.
         """
-        if isinstance(value, str):
-            self._default = exp.Literal.string(value)
-        elif isinstance(value, (int, float)):
-            self._default = exp.Literal.number(value)
-        elif isinstance(value, exp.Expression):
-            self._default = value
-        else:
-            self._default = exp.Literal.string(str(value))
+        self._default = SQLFactory._to_literal(value)
         return self
 
     def end(self) -> exp.Expression:
@@ -986,3 +1446,337 @@ class CaseExpressionBuilder:
             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.
+
+        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)
+
+
+# Create a default SQL factory instance
+sql = SQLFactory()