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

sqlspec/{statement/builder/mixins/_merge_clauses.py → builder/mixins/_merge_operations.py}

@@ -1,5 +1,8 @@
+"""Merge operation mixins for SQL builders."""
+
 from typing import Any, Optional, Union
 
+from mypy_extensions import trait
 from sqlglot import exp
 from typing_extensions import Self
 
@@ -16,10 +19,12 @@ __all__ = (
 )
 
 
+@trait
 class MergeIntoClauseMixin:
     """Mixin providing INTO clause for MERGE builders."""
 
-    _expression: Optional[exp.Expression] = None
+    __slots__ = ()
+    _expression: Optional[exp.Expression]
 
     def into(self, table: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
         """Set the target table for the MERGE operation (INTO clause).
@@ -33,17 +38,24 @@ class MergeIntoClauseMixin:
             The current builder instance for method chaining.
         """
         if self._expression is None:
-            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))  # pyright: ignore
-        if not isinstance(self._expression, exp.Merge):  # pyright: ignore
-            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))  # pyright: ignore
+            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))
+        if not isinstance(self._expression, exp.Merge):
+            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))
         self._expression.set("this", exp.to_table(table, alias=alias) if isinstance(table, str) else table)
         return self
 
 
+@trait
 class MergeUsingClauseMixin:
     """Mixin providing USING clause for MERGE builders."""
 
-    _expression: Optional[exp.Expression] = None
+    __slots__ = ()
+    _expression: Optional[exp.Expression]
+
+    def add_parameter(self, value: Any, name: Optional[str] = None) -> tuple[Any, str]:
+        """Add parameter - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
 
     def using(self, source: Union[str, exp.Expression, Any], alias: Optional[str] = None) -> Self:
         """Set the source data for the MERGE operation (USING clause).
@@ -68,11 +80,10 @@ class MergeUsingClauseMixin:
         if isinstance(source, str):
             source_expr = exp.to_table(source, alias=alias)
         elif has_query_builder_parameters(source) and hasattr(source, "_expression"):
-            # Merge parameters from the SELECT builder or other builder
-            subquery_builder_params = source.parameters
-            if subquery_builder_params:
-                for p_name, p_value in subquery_builder_params.items():
-                    self.add_parameter(p_value, name=p_name)  # type: ignore[attr-defined]
+            subquery_builder_parameters = source.parameters
+            if subquery_builder_parameters:
+                for p_name, p_value in subquery_builder_parameters.items():
+                    self.add_parameter(p_value, name=p_name)
 
             subquery_exp = exp.paren(getattr(source, "_expression", exp.select()))
             source_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
@@ -88,10 +99,12 @@ class MergeUsingClauseMixin:
         return self
 
 
+@trait
 class MergeOnClauseMixin:
     """Mixin providing ON clause for MERGE builders."""
 
-    _expression: Optional[exp.Expression] = None
+    __slots__ = ()
+    _expression: Optional[exp.Expression]
 
     def on(self, condition: Union[str, exp.Expression]) -> Self:
         """Set the join condition for the MERGE operation (ON clause).
@@ -130,10 +143,22 @@ class MergeOnClauseMixin:
         return self
 
 
+@trait
 class MergeMatchedClauseMixin:
     """Mixin providing WHEN MATCHED THEN ... clauses for MERGE builders."""
 
-    _expression: Optional[exp.Expression] = None
+    __slots__ = ()
+    _expression: Optional[exp.Expression]
+
+    def add_parameter(self, value: Any, name: Optional[str] = None) -> tuple[Any, str]:
+        """Add parameter - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
+
+    def _generate_unique_parameter_name(self, base_name: str) -> str:
+        """Generate unique parameter name - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
 
     def _add_when_clause(self, when_clause: exp.When) -> None:
         """Helper to add a WHEN clause to the MERGE statement.
@@ -142,9 +167,9 @@ class MergeMatchedClauseMixin:
             when_clause: The WHEN clause to add.
         """
         if self._expression is None:
-            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))
+            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))  # type: ignore[misc]
         if not isinstance(self._expression, exp.Merge):
-            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))
+            self._expression = exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))  # type: ignore[misc]
 
         whens = self._expression.args.get("whens")
         if not whens:
@@ -154,14 +179,23 @@ class MergeMatchedClauseMixin:
         whens.append("expressions", when_clause)
 
     def when_matched_then_update(
-        self, set_values: dict[str, Any], condition: Optional[Union[str, exp.Expression]] = None
+        self,
+        set_values: Optional[dict[str, Any]] = None,
+        condition: Optional[Union[str, exp.Expression]] = None,
+        **kwargs: Any,
     ) -> Self:
         """Define the UPDATE action for matched rows.
 
+        Supports:
+        - when_matched_then_update({"column": value})
+        - when_matched_then_update(column=value, other_column=other_value)
+        - when_matched_then_update({"column": value}, other_column=other_value)
+
         Args:
             set_values: A dictionary of column names and their new values to set.
                         The values will be parameterized.
             condition: An optional additional condition for this specific action.
+            **kwargs: Column-value pairs to update on match.
 
         Raises:
             SQLBuilderError: If the condition type is unsupported.
@@ -169,10 +203,48 @@ class MergeMatchedClauseMixin:
         Returns:
             The current builder instance for method chaining.
         """
+        # Combine set_values dict and kwargs
+        all_values = dict(set_values or {}, **kwargs)
+
+        if not all_values:
+            msg = "No update values provided. Use set_values dict or kwargs."
+            raise SQLBuilderError(msg)
+
         update_expressions: list[exp.EQ] = []
-        for col, val in set_values.items():
-            param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
-            update_expressions.append(exp.EQ(this=exp.column(col), expression=exp.var(param_name)))
+        for col, val in all_values.items():
+            if hasattr(val, "expression") and hasattr(val, "sql"):
+                # Handle SQL objects (from sql.raw with parameters)
+                expression = getattr(val, "expression", None)
+                if expression is not None and isinstance(expression, exp.Expression):
+                    # Merge parameters from SQL object into builder
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    value_expr = expression
+                else:
+                    # If expression is None, fall back to parsing the raw SQL
+                    sql_text = getattr(val, "sql", "")
+                    # Merge parameters even when parsing raw SQL
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    # Check if sql_text is callable (like Expression.sql method)
+                    if callable(sql_text):
+                        sql_text = str(val)
+                    value_expr = exp.maybe_parse(sql_text) or exp.convert(str(sql_text))
+            elif isinstance(val, exp.Expression):
+                value_expr = val
+            else:
+                column_name = col if isinstance(col, str) else str(col)
+                if "." in column_name:
+                    column_name = column_name.split(".")[-1]
+                param_name = self._generate_unique_parameter_name(column_name)
+                param_name = self.add_parameter(val, name=param_name)[1]
+                value_expr = exp.Placeholder(this=param_name)
+
+            update_expressions.append(exp.EQ(this=exp.column(col), expression=value_expr))
 
         when_args: dict[str, Any] = {"matched": True, "then": exp.Update(expressions=update_expressions)}
 
@@ -233,10 +305,28 @@ class MergeMatchedClauseMixin:
         return self
 
 
+@trait
 class MergeNotMatchedClauseMixin:
     """Mixin providing WHEN NOT MATCHED THEN ... clauses for MERGE builders."""
 
-    _expression: Optional[exp.Expression] = None
+    __slots__ = ()
+
+    _expression: Optional[exp.Expression]
+
+    def add_parameter(self, value: Any, name: Optional[str] = None) -> tuple[Any, str]:
+        """Add parameter - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
+
+    def _generate_unique_parameter_name(self, base_name: str) -> str:
+        """Generate unique parameter name - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
+
+    def _add_when_clause(self, when_clause: exp.When) -> None:
+        """Helper to add a WHEN clause to the MERGE statement - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
 
     def when_not_matched_then_insert(
         self,
@@ -269,8 +359,12 @@ class MergeNotMatchedClauseMixin:
                 raise SQLBuilderError(msg)
 
             parameterized_values: list[exp.Expression] = []
-            for val in values:
-                param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
+            for i, val in enumerate(values):
+                column_name = columns[i] if isinstance(columns[i], str) else str(columns[i])
+                if "." in column_name:
+                    column_name = column_name.split(".")[-1]
+                param_name = self._generate_unique_parameter_name(column_name)
+                param_name = self.add_parameter(val, name=param_name)[1]
                 parameterized_values.append(exp.var(param_name))
 
             insert_args["this"] = exp.Tuple(expressions=[exp.column(c) for c in columns])
@@ -279,7 +373,6 @@ class MergeNotMatchedClauseMixin:
             msg = "Specifying columns without values for INSERT action is complex and not fully supported yet. Consider providing full expressions."
             raise SQLBuilderError(msg)
         elif not columns and not values:
-            # INSERT DEFAULT VALUES case
             pass
         else:
             msg = "Cannot specify values without columns for INSERT action."
@@ -308,25 +401,52 @@ class MergeNotMatchedClauseMixin:
             when_args["this"] = condition_expr
 
         when_clause = exp.When(**when_args)
-        self._add_when_clause(when_clause)  # type: ignore[attr-defined]
+        self._add_when_clause(when_clause)
         return self
 
 
+@trait
 class MergeNotMatchedBySourceClauseMixin:
     """Mixin providing WHEN NOT MATCHED BY SOURCE THEN ... clauses for MERGE builders."""
 
-    _expression: Optional[exp.Expression] = None
+    __slots__ = ()
+
+    _expression: Optional[exp.Expression]
+
+    def add_parameter(self, value: Any, name: Optional[str] = None) -> tuple[Any, str]:
+        """Add parameter - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
+
+    def _generate_unique_parameter_name(self, base_name: str) -> str:
+        """Generate unique parameter name - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
+
+    def _add_when_clause(self, when_clause: exp.When) -> None:
+        """Helper to add a WHEN clause to the MERGE statement - provided by QueryBuilder."""
+        msg = "Method must be provided by QueryBuilder subclass"
+        raise NotImplementedError(msg)
 
     def when_not_matched_by_source_then_update(
-        self, set_values: dict[str, Any], condition: Optional[Union[str, exp.Expression]] = None
+        self,
+        set_values: Optional[dict[str, Any]] = None,
+        condition: Optional[Union[str, exp.Expression]] = None,
+        **kwargs: Any,
     ) -> Self:
         """Define the UPDATE action for rows not matched by source.
 
         This is useful for handling rows that exist in the target but not in the source.
 
+        Supports:
+        - when_not_matched_by_source_then_update({"column": value})
+        - when_not_matched_by_source_then_update(column=value, other_column=other_value)
+        - when_not_matched_by_source_then_update({"column": value}, other_column=other_value)
+
         Args:
             set_values: A dictionary of column names and their new values to set.
             condition: An optional additional condition for this specific action.
+            **kwargs: Column-value pairs to update when not matched by source.
 
         Raises:
             SQLBuilderError: If the condition type is unsupported.
@@ -334,10 +454,48 @@ class MergeNotMatchedBySourceClauseMixin:
         Returns:
             The current builder instance for method chaining.
         """
+        # Combine set_values dict and kwargs
+        all_values = dict(set_values or {}, **kwargs)
+
+        if not all_values:
+            msg = "No update values provided. Use set_values dict or kwargs."
+            raise SQLBuilderError(msg)
+
         update_expressions: list[exp.EQ] = []
-        for col, val in set_values.items():
-            param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
-            update_expressions.append(exp.EQ(this=exp.column(col), expression=exp.var(param_name)))
+        for col, val in all_values.items():
+            if hasattr(val, "expression") and hasattr(val, "sql"):
+                # Handle SQL objects (from sql.raw with parameters)
+                expression = getattr(val, "expression", None)
+                if expression is not None and isinstance(expression, exp.Expression):
+                    # Merge parameters from SQL object into builder
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    value_expr = expression
+                else:
+                    # If expression is None, fall back to parsing the raw SQL
+                    sql_text = getattr(val, "sql", "")
+                    # Merge parameters even when parsing raw SQL
+                    if hasattr(val, "parameters"):
+                        sql_parameters = getattr(val, "parameters", {})
+                        for param_name, param_value in sql_parameters.items():
+                            self.add_parameter(param_value, name=param_name)
+                    # Check if sql_text is callable (like Expression.sql method)
+                    if callable(sql_text):
+                        sql_text = str(val)
+                    value_expr = exp.maybe_parse(sql_text) or exp.convert(str(sql_text))
+            elif isinstance(val, exp.Expression):
+                value_expr = val
+            else:
+                column_name = col if isinstance(col, str) else str(col)
+                if "." in column_name:
+                    column_name = column_name.split(".")[-1]
+                param_name = self._generate_unique_parameter_name(column_name)
+                param_name = self.add_parameter(val, name=param_name)[1]
+                value_expr = exp.Placeholder(this=param_name)
+
+            update_expressions.append(exp.EQ(this=exp.column(col), expression=value_expr))
 
         when_args: dict[str, Any] = {
             "matched": False,
@@ -363,7 +521,7 @@ class MergeNotMatchedBySourceClauseMixin:
             when_args["this"] = condition_expr
 
         when_clause = exp.When(**when_args)
-        self._add_when_clause(when_clause)  # type: ignore[attr-defined]
+        self._add_when_clause(when_clause)
         return self
 
     def when_not_matched_by_source_then_delete(self, condition: Optional[Union[str, exp.Expression]] = None) -> Self:
@@ -400,5 +558,5 @@ class MergeNotMatchedBySourceClauseMixin:
             when_args["this"] = condition_expr
 
         when_clause = exp.When(**when_args)
-        self._add_when_clause(when_clause)  # type: ignore[attr-defined]
+        self._add_when_clause(when_clause)
         return self

sqlspec/builder/mixins/_order_limit_operations.py

@@ -0,0 +1,135 @@
+"""Order, Limit, Offset and Returning operations mixins for SQL builders."""
+
+from typing import TYPE_CHECKING, Optional, Union, cast
+
+from mypy_extensions import trait
+from sqlglot import exp
+from typing_extensions import Self
+
+from sqlspec.builder._parsing_utils import parse_order_expression
+from sqlspec.exceptions import SQLBuilderError
+
+if TYPE_CHECKING:
+    from sqlspec.protocols import SQLBuilderProtocol
+
+__all__ = ("LimitOffsetClauseMixin", "OrderByClauseMixin", "ReturningClauseMixin")
+
+
+@trait
+class OrderByClauseMixin:
+    """Mixin providing ORDER BY clause."""
+
+    __slots__ = ()
+
+    # Type annotation for PyRight - this will be provided by the base class
+    _expression: Optional[exp.Expression]
+
+    def order_by(self, *items: Union[str, exp.Ordered], desc: bool = False) -> Self:
+        """Add ORDER BY clause.
+
+        Args:
+            *items: Columns to order by. Can be strings (column names) or sqlglot.exp.Ordered instances for specific directions (e.g., exp.column("name").desc()).
+            desc: Whether to order in descending order (applies to all items if they are strings).
+
+        Raises:
+            SQLBuilderError: If the current expression is not a SELECT statement or if the item type is unsupported.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SQLBuilderProtocol", self)
+        if not isinstance(builder._expression, exp.Select):
+            msg = "ORDER BY is only supported for SELECT statements."
+            raise SQLBuilderError(msg)
+
+        current_expr = builder._expression
+        for item in items:
+            if isinstance(item, str):
+                order_item = parse_order_expression(item)
+                if desc:
+                    order_item = order_item.desc()
+            else:
+                order_item = item
+            current_expr = current_expr.order_by(order_item, copy=False)
+        builder._expression = current_expr
+        return cast("Self", builder)
+
+
+@trait
+class LimitOffsetClauseMixin:
+    """Mixin providing LIMIT and OFFSET clauses."""
+
+    __slots__ = ()
+
+    # Type annotation for PyRight - this will be provided by the base class
+    _expression: Optional[exp.Expression]
+
+    def limit(self, value: int) -> Self:
+        """Add LIMIT clause.
+
+        Args:
+            value: The maximum number of rows to return.
+
+        Raises:
+            SQLBuilderError: If the current expression is not a SELECT statement.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SQLBuilderProtocol", self)
+        if not isinstance(builder._expression, exp.Select):
+            msg = "LIMIT is only supported for SELECT statements."
+            raise SQLBuilderError(msg)
+        builder._expression = builder._expression.limit(exp.convert(value), copy=False)
+        return cast("Self", builder)
+
+    def offset(self, value: int) -> Self:
+        """Add OFFSET clause.
+
+        Args:
+            value: The number of rows to skip before starting to return rows.
+
+        Raises:
+            SQLBuilderError: If the current expression is not a SELECT statement.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SQLBuilderProtocol", self)
+        if not isinstance(builder._expression, exp.Select):
+            msg = "OFFSET is only supported for SELECT statements."
+            raise SQLBuilderError(msg)
+        builder._expression = builder._expression.offset(exp.convert(value), copy=False)
+        return cast("Self", builder)
+
+
+@trait
+class ReturningClauseMixin:
+    """Mixin providing RETURNING clause."""
+
+    __slots__ = ()
+    # Type annotation for PyRight - this will be provided by the base class
+    _expression: Optional[exp.Expression]
+
+    def returning(self, *columns: Union[str, exp.Expression]) -> Self:
+        """Add RETURNING clause to the statement.
+
+        Args:
+            *columns: Columns to return. Can be strings or sqlglot expressions.
+
+        Raises:
+            SQLBuilderError: If the current expression is not INSERT, UPDATE, or DELETE.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        if self._expression is None:
+            msg = "Cannot add RETURNING: expression is not initialized."
+            raise SQLBuilderError(msg)
+        valid_types = (exp.Insert, exp.Update, exp.Delete)
+        if not isinstance(self._expression, valid_types):
+            msg = "RETURNING is only supported for INSERT, UPDATE, and DELETE statements."
+            raise SQLBuilderError(msg)
+        returning_exprs = [exp.column(c) if isinstance(c, str) else c for c in columns]
+        self._expression.set("returning", exp.Returning(expressions=returning_exprs))
+        return self

sqlspec/builder/mixins/_pivot_operations.py

@@ -0,0 +1,153 @@
+"""Pivot and Unpivot operations mixins for SQL builders."""
+
+from typing import TYPE_CHECKING, Optional, Union, cast
+
+from mypy_extensions import trait
+from sqlglot import exp
+
+if TYPE_CHECKING:
+    from sqlglot.dialects.dialect import DialectType
+
+    from sqlspec.builder._select import Select
+
+__all__ = ("PivotClauseMixin", "UnpivotClauseMixin")
+
+
+@trait
+class PivotClauseMixin:
+    """Mixin class to add PIVOT functionality to a Select."""
+
+    __slots__ = ()
+    # Type annotation for PyRight - this will be provided by the base class
+    _expression: Optional[exp.Expression]
+
+    dialect: "DialectType" = None
+
+    def pivot(
+        self: "PivotClauseMixin",
+        aggregate_function: Union[str, exp.Expression],
+        aggregate_column: Union[str, exp.Expression],
+        pivot_column: Union[str, exp.Expression],
+        pivot_values: list[Union[str, int, float, exp.Expression]],
+        alias: Optional[str] = None,
+    ) -> "Select":
+        """Adds a PIVOT clause to the SELECT statement.
+
+        Example:
+            `query.pivot(aggregate_function="SUM", aggregate_column="Sales", pivot_column="Quarter", pivot_values=["Q1", "Q2", "Q3", "Q4"], alias="PivotTable")`
+
+        Args:
+            aggregate_function: The aggregate function to use (e.g., "SUM", "AVG").
+            aggregate_column: The column to be aggregated.
+            pivot_column: The column whose unique values will become new column headers.
+            pivot_values: A list of specific values from the pivot_column to be turned into columns.
+            alias: Optional alias for the pivoted table/subquery.
+
+        Returns:
+            The SelectBuilder instance for chaining.
+        """
+        current_expr = self._expression
+        if not isinstance(current_expr, exp.Select):
+            msg = "Pivot can only be applied to a Select expression managed by SelectBuilder."
+            raise TypeError(msg)
+
+        agg_func_name = aggregate_function if isinstance(aggregate_function, str) else aggregate_function.name
+        agg_col_expr = exp.column(aggregate_column) if isinstance(aggregate_column, str) else aggregate_column
+        pivot_col_expr = exp.column(pivot_column) if isinstance(pivot_column, str) else pivot_column
+
+        pivot_agg_expr = exp.func(agg_func_name, agg_col_expr)
+
+        pivot_value_exprs: list[exp.Expression] = []
+        for val in pivot_values:
+            if isinstance(val, exp.Expression):
+                pivot_value_exprs.append(val)
+            elif isinstance(val, (str, int, float)):
+                pivot_value_exprs.append(exp.convert(val))
+            else:
+                pivot_value_exprs.append(exp.convert(str(val)))
+
+        in_expr = exp.In(this=pivot_col_expr, expressions=pivot_value_exprs)
+
+        pivot_node = exp.Pivot(expressions=[pivot_agg_expr], fields=[in_expr], unpivot=False)
+
+        if alias:
+            pivot_node.set("alias", exp.TableAlias(this=exp.to_identifier(alias)))
+
+        from_clause = current_expr.args.get("from")
+        if from_clause and isinstance(from_clause, exp.From):
+            table = from_clause.this
+            if isinstance(table, exp.Table):
+                existing_pivots = table.args.get("pivots", [])
+                existing_pivots.append(pivot_node)
+                table.set("pivots", existing_pivots)
+
+        return cast("Select", self)
+
+
+@trait
+class UnpivotClauseMixin:
+    """Mixin class to add UNPIVOT functionality to a Select."""
+
+    __slots__ = ()
+    # Type annotation for PyRight - this will be provided by the base class
+    _expression: Optional[exp.Expression]
+
+    dialect: "DialectType" = None
+
+    def unpivot(
+        self: "UnpivotClauseMixin",
+        value_column_name: str,
+        name_column_name: str,
+        columns_to_unpivot: list[Union[str, exp.Expression]],
+        alias: Optional[str] = None,
+    ) -> "Select":
+        """Adds an UNPIVOT clause to the SELECT statement.
+
+        Example:
+            `query.unpivot(value_column_name="Sales", name_column_name="Quarter", columns_to_unpivot=["Q1Sales", "Q2Sales"], alias="UnpivotTable")`
+
+        Args:
+            value_column_name: The name for the new column that will hold the values from the unpivoted columns.
+            name_column_name: The name for the new column that will hold the names of the original unpivoted columns.
+            columns_to_unpivot: A list of columns to be unpivoted into rows.
+            alias: Optional alias for the unpivoted table/subquery.
+
+        Raises:
+            TypeError: If the current expression is not a Select expression.
+
+        Returns:
+            The Select instance for chaining.
+        """
+        current_expr = self._expression
+        if not isinstance(current_expr, exp.Select):
+            msg = "Unpivot can only be applied to a Select expression managed by Select."
+            raise TypeError(msg)
+
+        value_col_ident = exp.to_identifier(value_column_name)
+        name_col_ident = exp.to_identifier(name_column_name)
+
+        unpivot_cols_exprs: list[exp.Expression] = []
+        for col_name_or_expr in columns_to_unpivot:
+            if isinstance(col_name_or_expr, exp.Expression):
+                unpivot_cols_exprs.append(col_name_or_expr)
+            elif isinstance(col_name_or_expr, str):
+                unpivot_cols_exprs.append(exp.column(col_name_or_expr))
+            else:
+                unpivot_cols_exprs.append(exp.column(str(col_name_or_expr)))
+
+        in_expr = exp.In(this=name_col_ident, expressions=unpivot_cols_exprs)
+
+        unpivot_node = exp.Pivot(expressions=[value_col_ident], fields=[in_expr], unpivot=True)
+
+        if alias:
+            unpivot_node.set("alias", exp.TableAlias(this=exp.to_identifier(alias)))
+
+        from_clause = current_expr.args.get("from")
+        if from_clause and isinstance(from_clause, exp.From):
+            table = from_clause.this
+            if isinstance(table, exp.Table):
+                existing_pivots = table.args.get("pivots", [])
+                existing_pivots.append(unpivot_node)
+                table.set("pivots", existing_pivots)
+
+        return cast("Select", self)