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

sqlspec/statement/builder/{column.py → _column.py}

@@ -18,37 +18,37 @@ class ColumnExpression:
     """Base class for column expressions that can be combined with operators."""
 
     def __init__(self, expression: exp.Expression) -> None:
-        self._expr = expression
+        self._expression = expression
 
     def __and__(self, other: "ColumnExpression") -> "ColumnExpression":
         """Combine with AND operator (&)."""
         if not isinstance(other, ColumnExpression):
             return NotImplemented
-        return ColumnExpression(exp.And(this=self._expr, expression=other._expr))
+        return ColumnExpression(exp.And(this=self._expression, expression=other._expression))
 
     def __or__(self, other: "ColumnExpression") -> "ColumnExpression":
         """Combine with OR operator (|)."""
         if not isinstance(other, ColumnExpression):
             return NotImplemented
-        return ColumnExpression(exp.Or(this=self._expr, expression=other._expr))
+        return ColumnExpression(exp.Or(this=self._expression, expression=other._expression))
 
     def __invert__(self) -> "ColumnExpression":
         """Apply NOT operator (~)."""
-        return ColumnExpression(exp.Not(this=self._expr))
+        return ColumnExpression(exp.Not(this=self._expression))
 
     def __bool__(self) -> bool:
         """Prevent accidental use of 'and'/'or' keywords."""
         msg = (
             "Cannot use 'and'/'or' operators on ColumnExpression. "
             "Use '&'/'|' operators instead. "
-            f"Expression: {self._expr.sql()}"
+            f"Expression: {self._expression.sql()}"
         )
         raise TypeError(msg)
 
     @property
     def sqlglot_expression(self) -> exp.Expression:
         """Get the underlying SQLGlot expression."""
-        return self._expr
+        return self._expression
 
 
 class Column:
@@ -60,60 +60,60 @@ class Column:
 
         # Create SQLGlot column expression
         if table:
-            self._expr = exp.Column(this=exp.Identifier(this=name), table=exp.Identifier(this=table))
+            self._expression = exp.Column(this=exp.Identifier(this=name), table=exp.Identifier(this=table))
         else:
-            self._expr = exp.Column(this=exp.Identifier(this=name))
+            self._expression = exp.Column(this=exp.Identifier(this=name))
 
     # Comparison operators
     def __eq__(self, other: object) -> ColumnExpression:  # type: ignore[override]
         """Equal to (==)."""
         if other is None:
-            return ColumnExpression(exp.Is(this=self._expr, expression=exp.Null()))
-        return ColumnExpression(exp.EQ(this=self._expr, expression=exp.convert(other)))
+            return ColumnExpression(exp.Is(this=self._expression, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=self._expression, expression=exp.convert(other)))
 
     def __ne__(self, other: object) -> ColumnExpression:  # type: ignore[override]
         """Not equal to (!=)."""
         if other is None:
-            return ColumnExpression(exp.Not(this=exp.Is(this=self._expr, expression=exp.Null())))
-        return ColumnExpression(exp.NEQ(this=self._expr, expression=exp.convert(other)))
+            return ColumnExpression(exp.Not(this=exp.Is(this=self._expression, expression=exp.Null())))
+        return ColumnExpression(exp.NEQ(this=self._expression, expression=exp.convert(other)))
 
     def __gt__(self, other: Any) -> ColumnExpression:
         """Greater than (>)."""
-        return ColumnExpression(exp.GT(this=self._expr, expression=exp.convert(other)))
+        return ColumnExpression(exp.GT(this=self._expression, expression=exp.convert(other)))
 
     def __ge__(self, other: Any) -> ColumnExpression:
         """Greater than or equal (>=)."""
-        return ColumnExpression(exp.GTE(this=self._expr, expression=exp.convert(other)))
+        return ColumnExpression(exp.GTE(this=self._expression, expression=exp.convert(other)))
 
     def __lt__(self, other: Any) -> ColumnExpression:
         """Less than (<)."""
-        return ColumnExpression(exp.LT(this=self._expr, expression=exp.convert(other)))
+        return ColumnExpression(exp.LT(this=self._expression, expression=exp.convert(other)))
 
     def __le__(self, other: Any) -> ColumnExpression:
         """Less than or equal (<=)."""
-        return ColumnExpression(exp.LTE(this=self._expr, expression=exp.convert(other)))
+        return ColumnExpression(exp.LTE(this=self._expression, expression=exp.convert(other)))
 
     def __invert__(self) -> ColumnExpression:
         """Apply NOT operator (~)."""
-        return ColumnExpression(exp.Not(this=self._expr))
+        return ColumnExpression(exp.Not(this=self._expression))
 
     # SQL-specific methods
     def like(self, pattern: str, escape: Optional[str] = None) -> ColumnExpression:
         """SQL LIKE pattern matching."""
         if escape:
-            like_expr = exp.Like(this=self._expr, expression=exp.convert(pattern), escape=exp.convert(escape))
+            like_expr = exp.Like(this=self._expression, expression=exp.convert(pattern), escape=exp.convert(escape))
         else:
-            like_expr = exp.Like(this=self._expr, expression=exp.convert(pattern))
+            like_expr = exp.Like(this=self._expression, expression=exp.convert(pattern))
         return ColumnExpression(like_expr)
 
     def ilike(self, pattern: str) -> ColumnExpression:
         """Case-insensitive LIKE."""
-        return ColumnExpression(exp.ILike(this=self._expr, expression=exp.convert(pattern)))
+        return ColumnExpression(exp.ILike(this=self._expression, expression=exp.convert(pattern)))
 
     def in_(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL IN clause."""
         converted_values = [exp.convert(v) for v in values]
-        return ColumnExpression(exp.In(this=self._expr, expressions=converted_values))
+        return ColumnExpression(exp.In(this=self._expression, expressions=converted_values))
 
     def not_in(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL NOT IN clause."""
@@ -121,15 +121,15 @@ class Column:
 
     def between(self, start: Any, end: Any) -> ColumnExpression:
         """SQL BETWEEN clause."""
-        return ColumnExpression(exp.Between(this=self._expr, low=exp.convert(start), high=exp.convert(end)))
+        return ColumnExpression(exp.Between(this=self._expression, low=exp.convert(start), high=exp.convert(end)))
 
     def is_null(self) -> ColumnExpression:
         """SQL IS NULL."""
-        return ColumnExpression(exp.Is(this=self._expr, expression=exp.Null()))
+        return ColumnExpression(exp.Is(this=self._expression, expression=exp.Null()))
 
     def is_not_null(self) -> ColumnExpression:
         """SQL IS NOT NULL."""
-        return ColumnExpression(exp.Not(this=exp.Is(this=self._expr, expression=exp.Null())))
+        return ColumnExpression(exp.Not(this=exp.Is(this=self._expression, expression=exp.Null())))
 
     def not_like(self, pattern: str, escape: Optional[str] = None) -> ColumnExpression:
         """SQL NOT LIKE pattern matching."""
@@ -142,67 +142,97 @@ class Column:
     def any_(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL = ANY(...) clause."""
         converted_values = [exp.convert(v) for v in values]
-        return ColumnExpression(exp.EQ(this=self._expr, expression=exp.Any(expressions=converted_values)))
+        return ColumnExpression(exp.EQ(this=self._expression, expression=exp.Any(expressions=converted_values)))
 
     def not_any_(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL <> ANY(...) clause."""
         converted_values = [exp.convert(v) for v in values]
-        return ColumnExpression(exp.NEQ(this=self._expr, expression=exp.Any(expressions=converted_values)))
+        return ColumnExpression(exp.NEQ(this=self._expression, expression=exp.Any(expressions=converted_values)))
 
     # SQL Functions
     def lower(self) -> "FunctionColumn":
         """SQL LOWER() function."""
-        return FunctionColumn(exp.Lower(this=self._expr))
+        return FunctionColumn(exp.Lower(this=self._expression))
 
     def upper(self) -> "FunctionColumn":
         """SQL UPPER() function."""
-        return FunctionColumn(exp.Upper(this=self._expr))
+        return FunctionColumn(exp.Upper(this=self._expression))
 
     def length(self) -> "FunctionColumn":
         """SQL LENGTH() function."""
-        return FunctionColumn(exp.Length(this=self._expr))
+        return FunctionColumn(exp.Length(this=self._expression))
 
     def trim(self) -> "FunctionColumn":
         """SQL TRIM() function."""
-        return FunctionColumn(exp.Trim(this=self._expr))
+        return FunctionColumn(exp.Trim(this=self._expression))
 
     def abs(self) -> "FunctionColumn":
         """SQL ABS() function."""
-        return FunctionColumn(exp.Abs(this=self._expr))
+        return FunctionColumn(exp.Abs(this=self._expression))
 
     def round(self, decimals: int = 0) -> "FunctionColumn":
         """SQL ROUND() function."""
         if decimals == 0:
-            return FunctionColumn(exp.Round(this=self._expr))
-        return FunctionColumn(exp.Round(this=self._expr, expression=exp.Literal.number(decimals)))
+            return FunctionColumn(exp.Round(this=self._expression))
+        return FunctionColumn(exp.Round(this=self._expression, expression=exp.Literal.number(decimals)))
 
     def floor(self) -> "FunctionColumn":
         """SQL FLOOR() function."""
-        return FunctionColumn(exp.Floor(this=self._expr))
+        return FunctionColumn(exp.Floor(this=self._expression))
 
     def ceil(self) -> "FunctionColumn":
         """SQL CEIL() function."""
-        return FunctionColumn(exp.Ceil(this=self._expr))
+        return FunctionColumn(exp.Ceil(this=self._expression))
 
     def substring(self, start: int, length: Optional[int] = None) -> "FunctionColumn":
         """SQL SUBSTRING() function."""
         args = [exp.Literal.number(start)]
         if length is not None:
             args.append(exp.Literal.number(length))
-        return FunctionColumn(exp.Substring(this=self._expr, expressions=args))
+        return FunctionColumn(exp.Substring(this=self._expression, expressions=args))
 
     def coalesce(self, *values: Any) -> "FunctionColumn":
         """SQL COALESCE() function."""
-        expressions = [self._expr] + [exp.convert(v) for v in values]
+        expressions = [self._expression] + [exp.convert(v) for v in values]
         return FunctionColumn(exp.Coalesce(expressions=expressions))
 
     def cast(self, data_type: str) -> "FunctionColumn":
         """SQL CAST() function."""
-        return FunctionColumn(exp.Cast(this=self._expr, to=exp.DataType.build(data_type)))
+        return FunctionColumn(exp.Cast(this=self._expression, to=exp.DataType.build(data_type)))
+
+    # Aggregate functions
+    def count(self) -> "FunctionColumn":
+        """SQL COUNT() function."""
+        return FunctionColumn(exp.Count(this=self._expression))
+
+    def sum(self) -> "FunctionColumn":
+        """SQL SUM() function."""
+        return FunctionColumn(exp.Sum(this=self._expression))
+
+    def avg(self) -> "FunctionColumn":
+        """SQL AVG() function."""
+        return FunctionColumn(exp.Avg(this=self._expression))
+
+    def min(self) -> "FunctionColumn":
+        """SQL MIN() function."""
+        return FunctionColumn(exp.Min(this=self._expression))
+
+    def max(self) -> "FunctionColumn":
+        """SQL MAX() function."""
+        return FunctionColumn(exp.Max(this=self._expression))
+
+    def count_distinct(self) -> "FunctionColumn":
+        """SQL COUNT(DISTINCT column) function."""
+        return FunctionColumn(exp.Count(this=exp.Distinct(expressions=[self._expression])))
+
+    @staticmethod
+    def count_all() -> "FunctionColumn":
+        """SQL COUNT(*) function."""
+        return FunctionColumn(exp.Count(this=exp.Star()))
 
     def alias(self, alias_name: str) -> exp.Expression:
         """Create an aliased column expression."""
-        return exp.Alias(this=self._expr, alias=alias_name)
+        return exp.Alias(this=self._expression, alias=alias_name)
 
     def __repr__(self) -> str:
         if self.table:
@@ -218,25 +248,25 @@ class FunctionColumn:
     """Represents the result of a SQL function call on a column."""
 
     def __init__(self, expression: exp.Expression) -> None:
-        self._expr = expression
+        self._expression = expression
 
     def __eq__(self, other: object) -> ColumnExpression:  # type: ignore[override]
-        return ColumnExpression(exp.EQ(this=self._expr, expression=exp.convert(other)))
+        return ColumnExpression(exp.EQ(this=self._expression, expression=exp.convert(other)))
 
     def __ne__(self, other: object) -> ColumnExpression:  # type: ignore[override]
-        return ColumnExpression(exp.NEQ(this=self._expr, expression=exp.convert(other)))
+        return ColumnExpression(exp.NEQ(this=self._expression, expression=exp.convert(other)))
 
     def like(self, pattern: str) -> ColumnExpression:
-        return ColumnExpression(exp.Like(this=self._expr, expression=exp.convert(pattern)))
+        return ColumnExpression(exp.Like(this=self._expression, expression=exp.convert(pattern)))
 
     def ilike(self, pattern: str) -> ColumnExpression:
         """Case-insensitive LIKE."""
-        return ColumnExpression(exp.ILike(this=self._expr, expression=exp.convert(pattern)))
+        return ColumnExpression(exp.ILike(this=self._expression, expression=exp.convert(pattern)))
 
     def in_(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL IN clause."""
         converted_values = [exp.convert(v) for v in values]
-        return ColumnExpression(exp.In(this=self._expr, expressions=converted_values))
+        return ColumnExpression(exp.In(this=self._expression, expressions=converted_values))
 
     def not_in_(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL NOT IN clause."""
@@ -252,32 +282,32 @@ class FunctionColumn:
 
     def between(self, start: Any, end: Any) -> ColumnExpression:
         """SQL BETWEEN clause."""
-        return ColumnExpression(exp.Between(this=self._expr, low=exp.convert(start), high=exp.convert(end)))
+        return ColumnExpression(exp.Between(this=self._expression, low=exp.convert(start), high=exp.convert(end)))
 
     def is_null(self) -> ColumnExpression:
         """SQL IS NULL."""
-        return ColumnExpression(exp.Is(this=self._expr, expression=exp.Null()))
+        return ColumnExpression(exp.Is(this=self._expression, expression=exp.Null()))
 
     def is_not_null(self) -> ColumnExpression:
         """SQL IS NOT NULL."""
-        return ColumnExpression(exp.Not(this=exp.Is(this=self._expr, expression=exp.Null())))
+        return ColumnExpression(exp.Not(this=exp.Is(this=self._expression, expression=exp.Null())))
 
     def any_(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL = ANY(...) clause."""
         converted_values = [exp.convert(v) for v in values]
-        return ColumnExpression(exp.EQ(this=self._expr, expression=exp.Any(expressions=converted_values)))
+        return ColumnExpression(exp.EQ(this=self._expression, expression=exp.Any(expressions=converted_values)))
 
     def not_any_(self, values: Iterable[Any]) -> ColumnExpression:
         """SQL <> ANY(...) clause."""
         converted_values = [exp.convert(v) for v in values]
-        return ColumnExpression(exp.NEQ(this=self._expr, expression=exp.Any(expressions=converted_values)))
+        return ColumnExpression(exp.NEQ(this=self._expression, expression=exp.Any(expressions=converted_values)))
 
     def alias(self, alias_name: str) -> exp.Expression:
         """Create an aliased function expression."""
-        return exp.Alias(this=self._expr, alias=alias_name)
+        return exp.Alias(this=self._expression, alias=alias_name)
 
     # Add other operators as needed...
 
     def __hash__(self) -> int:
         """Hash based on the SQL expression."""
-        return hash(self._expr.sql() if has_sql_method(self._expr) else str(self._expr))
+        return hash(self._expression.sql() if has_sql_method(self._expression) else str(self._expression))

sqlspec/statement/builder/{ddl.py → _ddl.py}

@@ -7,12 +7,12 @@ from sqlglot import exp
 from sqlglot.dialects.dialect import DialectType
 from typing_extensions import Self
 
+from sqlspec.statement.builder._base import QueryBuilder, SafeQuery
 from sqlspec.statement.builder._ddl_utils import build_column_expression, build_constraint_expression
-from sqlspec.statement.builder.base import QueryBuilder, SafeQuery
 from sqlspec.statement.result import SQLResult
 
 if TYPE_CHECKING:
-    from sqlspec.statement.builder.column import ColumnExpression
+    from sqlspec.statement.builder._column import ColumnExpression
     from sqlspec.statement.sql import SQL, SQLConfig
 
 __all__ = (
@@ -792,7 +792,7 @@ class CreateTableAsSelect(DDLBuilder):
 
         select_expr = None
         select_params = None
-        from sqlspec.statement.builder.select import Select
+        from sqlspec.statement.builder._select import Select
         from sqlspec.statement.sql import SQL
 
         if isinstance(self._select_query, SQL):
@@ -909,7 +909,7 @@ class CreateMaterializedView(DDLBuilder):
 
         select_expr = None
         select_params = None
-        from sqlspec.statement.builder.select import Select
+        from sqlspec.statement.builder._select import Select
         from sqlspec.statement.sql import SQL
 
         if isinstance(self._select_query, SQL):
@@ -1008,7 +1008,7 @@ class CreateView(DDLBuilder):
 
         select_expr = None
         select_params = None
-        from sqlspec.statement.builder.select import Select
+        from sqlspec.statement.builder._select import Select
         from sqlspec.statement.sql import SQL
 
         if isinstance(self._select_query, SQL):

sqlspec/statement/builder/_ddl_utils.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, Optional
 from sqlglot import exp
 
 if TYPE_CHECKING:
-    from sqlspec.statement.builder.ddl import ColumnDefinition, ConstraintDefinition
+    from sqlspec.statement.builder._ddl import ColumnDefinition, ConstraintDefinition
 
 __all__ = ("build_column_expression", "build_constraint_expression")
 

sqlspec/statement/builder/{delete.py → _delete.py}

@@ -9,7 +9,7 @@ from typing import Any, Optional
 
 from sqlglot import exp
 
-from sqlspec.statement.builder.base import QueryBuilder, SafeQuery
+from sqlspec.statement.builder._base import QueryBuilder, SafeQuery
 from sqlspec.statement.builder.mixins import DeleteFromClauseMixin, ReturningClauseMixin, WhereClauseMixin
 from sqlspec.statement.result import SQLResult
 from sqlspec.typing import RowT

sqlspec/statement/builder/{insert.py → _insert.py}

@@ -11,7 +11,7 @@ from sqlglot import exp
 from typing_extensions import Self
 
 from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder.base import QueryBuilder
+from sqlspec.statement.builder._base import QueryBuilder
 from sqlspec.statement.builder.mixins import (
     InsertFromSelectMixin,
     InsertIntoClauseMixin,

sqlspec/statement/builder/{merge.py → _merge.py}

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 
 from sqlglot import exp
 
-from sqlspec.statement.builder.base import QueryBuilder
+from sqlspec.statement.builder._base import QueryBuilder
 from sqlspec.statement.builder.mixins import (
     MergeIntoClauseMixin,
     MergeMatchedClauseMixin,

sqlspec/statement/builder/_parsing_utils.py

@@ -9,6 +9,8 @@ from typing import Any, Optional, Union, cast
 
 from sqlglot import exp, maybe_parse, parse_one
 
+from sqlspec.utils.type_guards import has_expression_attr, has_parameter_builder
+
 
 def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> exp.Expression:
     """Parse a column input that might be a complex expression.
@@ -31,8 +33,8 @@ def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> ex
         return column_input
 
     # Handle our custom Column objects
-    if hasattr(column_input, "_expr"):
-        attr_value = getattr(column_input, "_expr", None)
+    if has_expression_attr(column_input):
+        attr_value = getattr(column_input, "_expression", None)
         if isinstance(attr_value, exp.Expression):
             return attr_value
 
@@ -109,7 +111,7 @@ def parse_condition_expression(
         if value is None:
             return exp.Is(this=column_expr, expression=exp.null())
         # Use builder's parameter system if available
-        if builder and hasattr(builder, "add_parameter"):
+        if builder and has_parameter_builder(builder):
             _, param_name = builder.add_parameter(value)
             return exp.EQ(this=column_expr, expression=exp.Placeholder(this=param_name))
         if isinstance(value, str):

sqlspec/statement/builder/{select.py → _select.py}

@@ -11,23 +11,18 @@ from typing import Any, Optional, Union, cast
 from sqlglot import exp
 from typing_extensions import Self
 
-from sqlspec.statement.builder.base import QueryBuilder, SafeQuery
+from sqlspec.statement.builder._base import QueryBuilder, SafeQuery
 from sqlspec.statement.builder.mixins import (
-    AggregateFunctionsMixin,
-    CaseBuilderMixin,
     CommonTableExpressionMixin,
-    FromClauseMixin,
-    GroupByClauseMixin,
     HavingClauseMixin,
     JoinClauseMixin,
     LimitOffsetClauseMixin,
     OrderByClauseMixin,
     PivotClauseMixin,
-    SelectColumnsMixin,
+    SelectClauseMixin,
     SetOperationMixin,
     UnpivotClauseMixin,
     WhereClauseMixin,
-    WindowFunctionsMixin,
 )
 from sqlspec.statement.result import SQLResult
 from sqlspec.typing import RowT
@@ -35,22 +30,21 @@ from sqlspec.typing import RowT
 __all__ = ("Select",)
 
 
+# This pattern is formatted with the table name and compiled for each hint.
+TABLE_HINT_PATTERN = r"\b{}\b(\s+AS\s+\w+)?"
+
+
 @dataclass
 class Select(
     QueryBuilder[RowT],
     WhereClauseMixin,
     OrderByClauseMixin,
     LimitOffsetClauseMixin,
-    SelectColumnsMixin,
+    SelectClauseMixin,
     JoinClauseMixin,
-    FromClauseMixin,
-    GroupByClauseMixin,
     HavingClauseMixin,
     SetOperationMixin,
     CommonTableExpressionMixin,
-    AggregateFunctionsMixin,
-    WindowFunctionsMixin,
-    CaseBuilderMixin,
     PivotClauseMixin,
     UnpivotClauseMixin,
 ):
@@ -95,14 +89,14 @@ class Select(
         """
         super().__init__(**kwargs)
 
-        # Initialize fields from dataclass
+        # Manually initialize dataclass fields here because a custom __init__ is defined.
+        # This is necessary to support the `Select("col1", "col2")` shorthand initialization.
         self._with_parts = {}
         self._expression = None
         self._schema = None
         self._hints = []
 
-        if self._expression is None:
-            self._create_base_expression()
+        self._create_base_expression()
 
         # Add columns if provided - just a shorthand for .select()
         if columns:
@@ -174,48 +168,52 @@ class Select(
         """
         safe_query = super().build()
 
-        if hasattr(self, "_hints") and self._hints:
-            modified_expr = self._expression.copy() if self._expression else None
-
-            if modified_expr and isinstance(modified_expr, exp.Select):
-                statement_hints = [h["hint"] for h in self._hints if h.get("location") == "statement"]
-                if statement_hints:
-                    # Parse each hint and create proper hint expressions
-                    hint_expressions = []
-                    for hint in statement_hints:
-                        try:
-                            # Try to parse hint as an expression (e.g., "INDEX(users idx_name)")
-                            hint_str = str(hint)  # Ensure hint is a string
-                            hint_expr: Optional[exp.Expression] = exp.maybe_parse(hint_str, dialect=self.dialect_name)
-                            if hint_expr:
-                                hint_expressions.append(hint_expr)
-                            else:
-                                hint_expressions.append(exp.Anonymous(this=hint_str))
-                        except Exception:  # noqa: PERF203
-                            hint_expressions.append(exp.Anonymous(this=str(hint)))
-
-                    if hint_expressions:
-                        hint_node = exp.Hint(expressions=hint_expressions)
-                        modified_expr.set("hint", hint_node)
-
-                # For table-level hints, we'll fall back to comment injection in SQL
-                # since SQLGlot doesn't have a standard way to attach hints to individual tables
-                modified_sql = modified_expr.sql(dialect=self.dialect_name, pretty=True)
-
-                table_hints = [h for h in self._hints if h.get("location") == "table" and h.get("table")]
-                if table_hints:
-                    for th in table_hints:
-                        table = str(th["table"])
-                        hint = th["hint"]
-                        # More precise regex that captures the table and optional alias
-                        pattern = rf"\b{re.escape(table)}\b(\s+AS\s+\w+)?"
-
-                        def replacement_func(match: re.Match[str]) -> str:
-                            alias_part = match.group(1) or ""
-                            return f"/*+ {hint} */ {table}{alias_part}"  # noqa: B023
-
-                        modified_sql = re.sub(pattern, replacement_func, modified_sql, flags=re.IGNORECASE, count=1)
-
-                return SafeQuery(sql=modified_sql, parameters=safe_query.parameters, dialect=safe_query.dialect)
-
-        return safe_query
+        if not self._hints:
+            return safe_query
+
+        modified_expr = self._expression.copy() if self._expression else self._create_base_expression()
+
+        if isinstance(modified_expr, exp.Select):
+            statement_hints = [h["hint"] for h in self._hints if h.get("location") == "statement"]
+            if statement_hints:
+                # Parse each hint and create proper hint expressions
+                hint_expressions = []
+
+                def parse_hint(hint: Any) -> exp.Expression:
+                    """Parse a single hint with error handling."""
+                    try:
+                        # Try to parse hint as an expression (e.g., "INDEX(users idx_name)")
+                        hint_str = str(hint)  # Ensure hint is a string
+                        hint_expr: Optional[exp.Expression] = exp.maybe_parse(hint_str, dialect=self.dialect_name)
+                        if hint_expr:
+                            return hint_expr
+                        return exp.Anonymous(this=hint_str)
+                    except Exception:
+                        return exp.Anonymous(this=str(hint))
+
+                hint_expressions = [parse_hint(hint) for hint in statement_hints]
+
+                if hint_expressions:
+                    hint_node = exp.Hint(expressions=hint_expressions)
+                    modified_expr.set("hint", hint_node)
+
+        # For table-level hints, we'll fall back to comment injection in SQL
+        # since SQLGlot doesn't have a standard way to attach hints to individual tables
+        modified_sql = modified_expr.sql(dialect=self.dialect_name, pretty=True)
+
+        table_hints = [h for h in self._hints if h.get("location") == "table" and h.get("table")]
+        if table_hints:
+            for th in table_hints:
+                table = str(th["table"])
+                hint = th["hint"]
+                # More precise regex that captures the table and optional alias
+                pattern = TABLE_HINT_PATTERN.format(re.escape(table))
+                compiled_pattern = re.compile(pattern, re.IGNORECASE)
+
+                def replacement_func(match: re.Match[str]) -> str:
+                    alias_part = match.group(1) or ""
+                    return f"/*+ {hint} */ {table}{alias_part}"  # noqa: B023
+
+                modified_sql = compiled_pattern.sub(replacement_func, modified_sql, count=1)
+
+        return SafeQuery(sql=modified_sql, parameters=safe_query.parameters, dialect=safe_query.dialect)

sqlspec/statement/builder/{update.py → _update.py}

@@ -11,7 +11,7 @@ from sqlglot import exp
 from typing_extensions import Self
 
 from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder.base import QueryBuilder, SafeQuery
+from sqlspec.statement.builder._base import QueryBuilder, SafeQuery
 from sqlspec.statement.builder.mixins import (
     ReturningClauseMixin,
     UpdateFromClauseMixin,
@@ -23,7 +23,7 @@ from sqlspec.statement.result import SQLResult
 from sqlspec.typing import RowT
 
 if TYPE_CHECKING:
-    from sqlspec.statement.builder.select import Select
+    from sqlspec.statement.builder._select import Select
 
 __all__ = ("Update",)