sqlspec 0.24.0__py3-none-any.whl → 0.25.0__py3-none-any.whl

sqlspec/_sql.py

@@ -137,21 +137,18 @@ class SQLFactory:
         self.dialect = dialect
 
     def __call__(self, statement: str, dialect: DialectType = None) -> "Any":
-        """Create a SelectBuilder from a SQL string, only allowing SELECT/CTE queries.
+        """Create a SelectBuilder from a SQL string, or SQL object for DML with RETURNING.
 
         Args:
             statement: The SQL statement string.
-            parameters: Optional parameters for the query.
-            *filters: Optional filters.
-            config: Optional config.
             dialect: Optional SQL dialect.
-            **kwargs: Additional parameters.
 
         Returns:
-            SelectBuilder instance.
+            SelectBuilder instance for SELECT/WITH statements,
+            SQL object for DML statements with RETURNING clause.
 
         Raises:
-            SQLBuilderError: If the SQL is not a SELECT/CTE statement.
+            SQLBuilderError: If the SQL is not a SELECT/CTE/DML+RETURNING statement.
         """
 
         try:
@@ -173,10 +170,15 @@ class SQLFactory:
             actual_type_str == "WITH" and parsed_expr.this and isinstance(parsed_expr.this, exp.Select)
         ):
             builder = Select(dialect=dialect or self.dialect)
-            builder._expression = parsed_expr
+            builder.set_expression(parsed_expr)
             return builder
+
+        if actual_type_str in {"INSERT", "UPDATE", "DELETE"} and parsed_expr.args.get("returning") is not None:
+            return SQL(statement)
+
         msg = (
-            f"sql(...) only supports SELECT statements. Detected type: {actual_type_str}. "
+            f"sql(...) only supports SELECT statements or DML statements with RETURNING clause. "
+            f"Detected type: {actual_type_str}. "
             f"Use sql.{actual_type_str.lower()}() instead."
         )
         raise SQLBuilderError(msg)
@@ -449,7 +451,7 @@ class SQLFactory:
             parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Insert):
-                builder._expression = parsed_expr
+                builder.set_expression(parsed_expr)
                 return builder
 
             if isinstance(parsed_expr, exp.Select):
@@ -468,7 +470,7 @@ class SQLFactory:
             parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Select):
-                builder._expression = parsed_expr
+                builder.set_expression(parsed_expr)
                 return builder
 
             logger.warning("Cannot create SELECT from %s statement", type(parsed_expr).__name__)
@@ -483,7 +485,7 @@ class SQLFactory:
             parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Update):
-                builder._expression = parsed_expr
+                builder.set_expression(parsed_expr)
                 return builder
 
             logger.warning("Cannot create UPDATE from %s statement", type(parsed_expr).__name__)
@@ -498,7 +500,7 @@ class SQLFactory:
             parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Delete):
-                builder._expression = parsed_expr
+                builder.set_expression(parsed_expr)
                 return builder
 
             logger.warning("Cannot create DELETE from %s statement", type(parsed_expr).__name__)
@@ -513,7 +515,7 @@ class SQLFactory:
             parsed_expr: exp.Expression = exp.maybe_parse(sql_string, dialect=self.dialect)
 
             if isinstance(parsed_expr, exp.Merge):
-                builder._expression = parsed_expr
+                builder.set_expression(parsed_expr)
                 return builder
 
             logger.warning("Cannot create MERGE from %s statement", type(parsed_expr).__name__)
@@ -722,19 +724,15 @@ class SQLFactory:
         if not parameters:
             try:
                 parsed: exp.Expression = exp.maybe_parse(sql_fragment)
-                return parsed
-                if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
-                    return exp.to_identifier(sql_fragment)
-                return exp.Literal.string(sql_fragment)
             except Exception as e:
                 msg = f"Failed to parse raw SQL fragment '{sql_fragment}': {e}"
                 raise SQLBuilderError(msg) from e
+            return parsed
 
         return SQL(sql_fragment, parameters)
 
-    @staticmethod
     def count(
-        column: Union[str, exp.Expression, "ExpressionWrapper", "Case", "Column"] = "*", distinct: bool = False
+        self, column: Union[str, exp.Expression, "ExpressionWrapper", "Case", "Column"] = "*", distinct: bool = False
     ) -> AggregateExpression:
         """Create a COUNT expression.
 
@@ -748,7 +746,7 @@ class SQLFactory:
         if isinstance(column, str) and column == "*":
             expr = exp.Count(this=exp.Star(), distinct=distinct)
         else:
-            col_expr = SQLFactory._extract_expression(column)
+            col_expr = self._extract_expression(column)
             expr = exp.Count(this=col_expr, distinct=distinct)
         return AggregateExpression(expr)
 
@@ -1066,11 +1064,11 @@ class SQLFactory:
         if isinstance(value, str):
             return exp.column(value)
         if isinstance(value, Column):
-            return value._expression
+            return value.sqlglot_expression
         if isinstance(value, ExpressionWrapper):
             return value.expression
         if isinstance(value, Case):
-            return exp.Case(ifs=value._conditions, default=value._default)
+            return exp.Case(ifs=value.conditions, default=value.default)
         if isinstance(value, exp.Expression):
             return value
         return exp.convert(value)

sqlspec/_typing.py

@@ -606,6 +606,7 @@ except ImportError:
 
 
 FSSPEC_INSTALLED = bool(find_spec("fsspec"))
+NUMPY_INSTALLED = bool(find_spec("numpy"))
 OBSTORE_INSTALLED = bool(find_spec("obstore"))
 PGVECTOR_INSTALLED = bool(find_spec("pgvector"))
 
@@ -617,6 +618,7 @@ __all__ = (
     "FSSPEC_INSTALLED",
     "LITESTAR_INSTALLED",
     "MSGSPEC_INSTALLED",
+    "NUMPY_INSTALLED",
     "OBSTORE_INSTALLED",
     "OPENTELEMETRY_INSTALLED",
     "PGVECTOR_INSTALLED",

sqlspec/adapters/adbc/driver.py

@@ -521,7 +521,7 @@ class AdbcDriver(SyncDriverAdapterBase):
 
         try:
             if not prepared_parameters:
-                cursor._rowcount = 0
+                cursor._rowcount = 0  # pyright: ignore[reportPrivateUsage]
                 row_count = 0
             elif isinstance(prepared_parameters, list) and prepared_parameters:
                 processed_params = []
@@ -596,7 +596,7 @@ class AdbcDriver(SyncDriverAdapterBase):
             Execution result with statement counts
         """
         if statement.is_script:
-            sql = statement._raw_sql
+            sql = statement.raw_sql
             prepared_parameters: list[Any] = []
         else:
             sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)

sqlspec/adapters/oracledb/driver.py

@@ -286,6 +286,11 @@ class OracleSyncDriver(SyncDriverAdapterBase):
             msg = "execute_many requires parameters"
             raise ValueError(msg)
 
+        # Oracle-specific fix: Ensure parameters are in list format for executemany
+        # Oracle expects a list of sequences, not a tuple of sequences
+        if isinstance(prepared_parameters, tuple):
+            prepared_parameters = list(prepared_parameters)
+
         cursor.executemany(sql, prepared_parameters)
 
         # Calculate affected rows based on parameter count

sqlspec/adapters/psycopg/config.py

@@ -173,8 +173,7 @@ class PsycopgSyncConfig(SyncDatabaseConfig[PsycopgSyncConnection, ConnectionPool
         logger.info("Closing Psycopg connection pool", extra={"adapter": "psycopg"})
 
         try:
-            if hasattr(self.pool_instance, "_closed"):
-                self.pool_instance._closed = True
+            self.pool_instance._closed = True  # pyright: ignore[reportPrivateUsage]
 
             self.pool_instance.close()
             logger.info("Psycopg connection pool closed successfully", extra={"adapter": "psycopg"})
@@ -350,8 +349,7 @@ class PsycopgAsyncConfig(AsyncDatabaseConfig[PsycopgAsyncConnection, AsyncConnec
             return
 
         try:
-            if hasattr(self.pool_instance, "_closed"):
-                self.pool_instance._closed = True
+            self.pool_instance._closed = True  # pyright: ignore[reportPrivateUsage]
 
             await self.pool_instance.close()
         finally:

sqlspec/base.py

@@ -15,9 +15,8 @@ from sqlspec.config import (
 )
 from sqlspec.core.cache import (
     CacheConfig,
-    CacheStatsAggregate,
     get_cache_config,
-    get_cache_stats,
+    get_cache_statistics,
     log_cache_stats,
     reset_cache_stats,
     update_cache_config,
@@ -532,13 +531,13 @@ class SQLSpec:
         update_cache_config(config)
 
     @staticmethod
-    def get_cache_stats() -> CacheStatsAggregate:
+    def get_cache_stats() -> "dict[str, Any]":
         """Get current cache statistics.
 
         Returns:
             Cache statistics object with detailed metrics.
         """
-        return get_cache_stats()
+        return get_cache_statistics()
 
     @staticmethod
     def reset_cache_stats() -> None:

sqlspec/builder/_base.py

@@ -13,7 +13,7 @@ from sqlglot.errors import ParseError as SQLGlotParseError
 from sqlglot.optimizer import optimize
 from typing_extensions import Self
 
-from sqlspec.core.cache import CacheKey, get_cache_config, get_default_cache
+from sqlspec.core.cache import get_cache, get_cache_config
 from sqlspec.core.hashing import hash_optimized_expression
 from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
 from sqlspec.core.statement import SQL, StatementConfig
@@ -91,6 +91,36 @@ class QueryBuilder(ABC):
                 "QueryBuilder._create_base_expression must return a valid sqlglot expression."
             )
 
+    def get_expression(self) -> Optional[exp.Expression]:
+        """Get expression reference (no copy).
+
+        Returns:
+            The current SQLGlot expression or None if not set
+        """
+        return self._expression
+
+    def set_expression(self, expression: exp.Expression) -> None:
+        """Set expression with validation.
+
+        Args:
+            expression: SQLGlot expression to set
+
+        Raises:
+            TypeError: If expression is not a SQLGlot Expression
+        """
+        if not isinstance(expression, exp.Expression):
+            msg = f"Expected Expression, got {type(expression)}"
+            raise TypeError(msg)
+        self._expression = expression
+
+    def has_expression(self) -> bool:
+        """Check if expression exists.
+
+        Returns:
+            True if expression is set, False otherwise
+        """
+        return self._expression is not None
+
     @abstractmethod
     def _create_base_expression(self) -> exp.Expression:
         """Create the base sqlglot expression for the specific query type.
@@ -307,12 +337,13 @@ class QueryBuilder(ABC):
         cte_select_expression: exp.Select
 
         if isinstance(query, QueryBuilder):
-            if query._expression is None:
+            query_expr = query.get_expression()
+            if query_expr is None:
                 self._raise_sql_builder_error("CTE query builder has no expression.")
-            if not isinstance(query._expression, exp.Select):
-                msg = f"CTE query builder expression must be a Select, got {type(query._expression).__name__}."
+            if not isinstance(query_expr, exp.Select):
+                msg = f"CTE query builder expression must be a Select, got {type(query_expr).__name__}."
                 self._raise_sql_builder_error(msg)
-            cte_select_expression = query._expression
+            cte_select_expression = query_expr
             param_mapping = self._merge_cte_parameters(alias, query.parameters)
             updated_expression = self._update_placeholders_in_expression(cte_select_expression, param_mapping)
             if not isinstance(updated_expression, exp.Select):
@@ -398,9 +429,8 @@ class QueryBuilder(ABC):
             expression, dialect=dialect_name, schema=self.schema, optimizer_settings=optimizer_settings
         )
 
-        cache_key_obj = CacheKey((cache_key,))
-        unified_cache = get_default_cache()
-        cached_optimized = unified_cache.get(cache_key_obj)
+        cache = get_cache()
+        cached_optimized = cache.get("optimized", cache_key)
         if cached_optimized:
             return cast("exp.Expression", cached_optimized)
 
@@ -409,7 +439,7 @@ class QueryBuilder(ABC):
                 expression, schema=self.schema, dialect=self.dialect_name, optimizer_settings=optimizer_settings
             )
 
-            unified_cache.put(cache_key_obj, optimized)
+            cache.put("optimized", cache_key, optimized)
 
         except Exception:
             return expression
@@ -430,15 +460,14 @@ class QueryBuilder(ABC):
             return self._to_statement(config)
 
         cache_key_str = self._generate_builder_cache_key(config)
-        cache_key = CacheKey((cache_key_str,))
 
-        unified_cache = get_default_cache()
-        cached_sql = unified_cache.get(cache_key)
+        cache = get_cache()
+        cached_sql = cache.get("builder", cache_key_str)
         if cached_sql is not None:
             return cast("SQL", cached_sql)
 
         sql_statement = self._to_statement(config)
-        unified_cache.put(cache_key, sql_statement)
+        cache.put("builder", cache_key_str, sql_statement)
 
         return sql_statement
 
@@ -531,3 +560,16 @@ class QueryBuilder(ABC):
     def parameters(self) -> dict[str, Any]:
         """Public access to query parameters."""
         return self._parameters
+
+    def set_parameters(self, parameters: dict[str, Any]) -> None:
+        """Set query parameters (public API)."""
+        self._parameters = parameters.copy()
+
+    @property
+    def with_ctes(self) -> "dict[str, exp.CTE]":
+        """Get WITH clause CTEs (public API)."""
+        return dict(self._with_ctes)
+
+    def generate_unique_parameter_name(self, base_name: str) -> str:
+        """Generate unique parameter name (public API)."""
+        return self._generate_unique_parameter_name(base_name)

sqlspec/builder/_column.py

@@ -254,6 +254,15 @@ class Column:
         """Hash based on table and column name."""
         return hash((self.table, self.name))
 
+    @property
+    def sqlglot_expression(self) -> exp.Expression:
+        """Get the underlying SQLGlot expression (public API).
+
+        Returns:
+            The SQLGlot expression for this column
+        """
+        return self._expression
+
 
 class FunctionColumn:
     """Represents the result of a SQL function call on a column."""

sqlspec/builder/_ddl.py

@@ -973,10 +973,10 @@ class CreateTableAsSelect(DDLBuilder):
             select_expr = self._select_query.expression
             select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, Select):
-            select_expr = self._select_query._expression
-            select_parameters = self._select_query._parameters
+            select_expr = self._select_query.get_expression()
+            select_parameters = self._select_query.parameters
 
-            with_ctes = self._select_query._with_ctes
+            with_ctes = self._select_query.with_ctes
             if with_ctes and select_expr and isinstance(select_expr, exp.Select):
                 for alias, cte in with_ctes.items():
                     if has_with_method(select_expr):
@@ -1100,8 +1100,8 @@ class CreateMaterializedView(DDLBuilder):
             select_expr = self._select_query.expression
             select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, Select):
-            select_expr = self._select_query._expression
-            select_parameters = self._select_query._parameters
+            select_expr = self._select_query.get_expression()
+            select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
             select_parameters = None
@@ -1198,8 +1198,8 @@ class CreateView(DDLBuilder):
             select_expr = self._select_query.expression
             select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, Select):
-            select_expr = self._select_query._expression
-            select_parameters = self._select_query._parameters
+            select_expr = self._select_query.get_expression()
+            select_parameters = self._select_query.parameters
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
             select_parameters = None

sqlspec/builder/_insert.py

@@ -90,6 +90,10 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
             raise SQLBuilderError(ERR_MSG_INTERNAL_EXPRESSION_TYPE)
         return self._expression
 
+    def get_insert_expression(self) -> exp.Insert:
+        """Get the insert expression (public API)."""
+        return self._get_insert_expression()
+
     def values(self, *values: Any, **kwargs: Any) -> "Self":
         """Adds a row of values to the INSERT statement.
 
@@ -129,7 +133,7 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
             if hasattr(values_0, "items") and hasattr(values_0, "keys"):
                 return self.values_from_dict(values_0)
 
-        insert_expr = self._get_insert_expression()
+        insert_expr = self.get_insert_expression()
 
         if self._columns and len(values) != len(self._columns):
             msg = ERR_MSG_VALUES_COLUMNS_MISMATCH.format(values_len=len(values), columns_len=len(self._columns))
@@ -160,9 +164,9 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
                 if self._columns and i < len(self._columns):
                     column_str = str(self._columns[i])
                     column_name = column_str.rsplit(".", maxsplit=1)[-1] if "." in column_str else column_str
-                    param_name = self._generate_unique_parameter_name(column_name)
+                    param_name = self.generate_unique_parameter_name(column_name)
                 else:
-                    param_name = self._generate_unique_parameter_name(f"value_{i + 1}")
+                    param_name = self.generate_unique_parameter_name(f"value_{i + 1}")
                 _, param_name = self.add_parameter(value, name=param_name)
                 value_placeholders.append(exp.Placeholder(this=param_name))
 
@@ -336,7 +340,7 @@ class ConflictBuilder:
             ).do_nothing()
             ```
         """
-        insert_expr = self._insert_builder._get_insert_expression()
+        insert_expr = self._insert_builder.get_insert_expression()
 
         # Create ON CONFLICT with proper structure
         conflict_keys = [exp.to_identifier(col) for col in self._columns] if self._columns else None
@@ -363,7 +367,7 @@ class ConflictBuilder:
             )
             ```
         """
-        insert_expr = self._insert_builder._get_insert_expression()
+        insert_expr = self._insert_builder.get_insert_expression()
 
         # Create SET expressions for the UPDATE
         set_expressions = []
@@ -394,7 +398,7 @@ class ConflictBuilder:
                 value_expr = val
             else:
                 # Create parameter for regular values
-                param_name = self._insert_builder._generate_unique_parameter_name(col)
+                param_name = self._insert_builder.generate_unique_parameter_name(col)
                 _, param_name = self._insert_builder.add_parameter(val, name=param_name)
                 value_expr = exp.Placeholder(this=param_name)
 

sqlspec/builder/_parsing_utils.py

@@ -18,6 +18,27 @@ from sqlspec.utils.type_guards import (
 )
 
 
+def extract_column_name(column: Union[str, exp.Column]) -> str:
+    """Extract column name from column expression for parameter naming.
+
+    Args:
+        column: Column expression (string or SQLGlot Column)
+
+    Returns:
+        Column name as string for use as parameter name
+    """
+    if isinstance(column, str):
+        if "." in column:
+            return column.split(".")[-1]
+        return column
+    if isinstance(column, exp.Column):
+        try:
+            return str(column.this.this)
+        except AttributeError:
+            return str(column.this) if column.this else "column"
+    return "column"
+
+
 def parse_column_expression(
     column_input: Union[str, exp.Expression, Any], builder: Optional[Any] = None
 ) -> exp.Expression:
@@ -139,10 +160,8 @@ def parse_condition_expression(
         if value is None:
             return exp.Is(this=column_expr, expression=exp.null())
         if builder and has_parameter_builder(builder):
-            from sqlspec.builder.mixins._where_clause import _extract_column_name
-
-            column_name = _extract_column_name(column)
-            param_name = builder._generate_unique_parameter_name(column_name)
+            column_name = extract_column_name(column)
+            param_name = builder.generate_unique_parameter_name(column_name)
             _, param_name = builder.add_parameter(value, name=param_name)
             return exp.EQ(this=column_expr, expression=exp.Placeholder(this=param_name))
         if isinstance(value, str):

sqlspec/builder/_update.py

@@ -131,7 +131,7 @@ class Update(
             subquery_exp = exp.paren(exp.maybe_parse(subquery.sql, dialect=self.dialect))
             table_expr = exp.alias_(subquery_exp, alias) if alias else subquery_exp
 
-            subquery_parameters = table._parameters
+            subquery_parameters = table.parameters
             if subquery_parameters:
                 for p_name, p_value in subquery_parameters.items():
                     self.add_parameter(p_value, name=p_name)

sqlspec/builder/mixins/_cte_and_set_ops.py

@@ -1,10 +1,11 @@
+# pyright: reportPrivateUsage=false
 """CTE and set operation mixins.
 
 Provides mixins for Common Table Expressions (WITH clause) and
 set operations (UNION, INTERSECT, EXCEPT).
 """
 
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 from mypy_extensions import trait
 from sqlglot import exp
@@ -12,6 +13,9 @@ from typing_extensions import Self
 
 from sqlspec.exceptions import SQLBuilderError
 
+if TYPE_CHECKING:
+    from sqlspec.builder._base import QueryBuilder
+
 __all__ = ("CommonTableExpressionMixin", "SetOperationMixin")
 
 
@@ -20,8 +24,10 @@ class CommonTableExpressionMixin:
     """Mixin providing WITH clause (Common Table Expressions) support for SQL builders."""
 
     __slots__ = ()
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
+
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
 
     _with_ctes: Any  # Provided by QueryBuilder
     dialect: Any  # Provided by QueryBuilder
@@ -60,12 +66,14 @@ class CommonTableExpressionMixin:
         Returns:
             The current builder instance for method chaining.
         """
-        if self._expression is None:
+        builder = cast("QueryBuilder", self)
+        expression = builder.get_expression()
+        if expression is None:
             msg = "Cannot add WITH clause: expression not initialized."
             raise SQLBuilderError(msg)
 
-        if not isinstance(self._expression, (exp.Select, exp.Insert, exp.Update, exp.Delete)):
-            msg = f"Cannot add WITH clause to {type(self._expression).__name__} expression."
+        if not isinstance(expression, (exp.Select, exp.Insert, exp.Update, exp.Delete)):
+            msg = f"Cannot add WITH clause to {type(expression).__name__} expression."
             raise SQLBuilderError(msg)
 
         cte_expr: Optional[exp.Expression] = None
@@ -103,19 +111,18 @@ class CommonTableExpressionMixin:
         else:
             cte_alias_expr = exp.alias_(cte_expr, name)
 
-        existing_with = self._expression.args.get("with")
+        existing_with = expression.args.get("with")
         if existing_with:
             existing_with.expressions.append(cte_alias_expr)
             if recursive:
                 existing_with.set("recursive", recursive)
         else:
             # Only SELECT, INSERT, UPDATE support WITH clauses
-            if hasattr(self._expression, "with_") and isinstance(
-                self._expression, (exp.Select, exp.Insert, exp.Update)
-            ):
-                self._expression = self._expression.with_(cte_alias_expr, as_=name, copy=False)
+            if hasattr(expression, "with_") and isinstance(expression, (exp.Select, exp.Insert, exp.Update)):
+                updated_expression = expression.with_(cte_alias_expr, as_=name, copy=False)
+                builder.set_expression(updated_expression)
                 if recursive:
-                    with_clause = self._expression.find(exp.With)
+                    with_clause = updated_expression.find(exp.With)
                     if with_clause:
                         with_clause.set("recursive", recursive)
             self._with_ctes[name] = exp.CTE(this=cte_expr, alias=exp.to_table(name))
@@ -128,10 +135,12 @@ class SetOperationMixin:
     """Mixin providing set operations (UNION, INTERSECT, EXCEPT) for SELECT builders."""
 
     __slots__ = ()
-    # Type annotation for PyRight - this will be provided by the base class
-    _expression: Optional[exp.Expression]
 
-    _parameters: dict[str, Any]
+    # Type annotations for PyRight - these will be provided by the base class
+    def get_expression(self) -> Optional[exp.Expression]: ...
+    def set_expression(self, expression: exp.Expression) -> None: ...
+    def set_parameters(self, parameters: "dict[str, Any]") -> None: ...
+
     dialect: Any = None
 
     def build(self) -> Any:
@@ -162,7 +171,7 @@ class SetOperationMixin:
         union_expr = exp.union(left_expr, right_expr, distinct=not all_)
         new_builder = type(self)()
         new_builder.dialect = self.dialect
-        new_builder._expression = union_expr
+        cast("QueryBuilder", new_builder).set_expression(union_expr)
         merged_parameters = dict(left_query.parameters)
         for param_name, param_value in right_query.parameters.items():
             if param_name in merged_parameters:
@@ -181,11 +190,11 @@ class SetOperationMixin:
 
                 right_expr = right_expr.transform(rename_parameter)
                 union_expr = exp.union(left_expr, right_expr, distinct=not all_)
-                new_builder._expression = union_expr
+                cast("QueryBuilder", new_builder).set_expression(union_expr)
                 merged_parameters[new_param_name] = param_value
             else:
                 merged_parameters[param_name] = param_value
-        new_builder._parameters = merged_parameters
+        new_builder.set_parameters(merged_parameters)
         return new_builder
 
     def intersect(self, other: Any) -> Self:
@@ -210,10 +219,10 @@ class SetOperationMixin:
         intersect_expr = exp.intersect(left_expr, right_expr, distinct=True)
         new_builder = type(self)()
         new_builder.dialect = self.dialect
-        new_builder._expression = intersect_expr
+        cast("QueryBuilder", new_builder).set_expression(intersect_expr)
         merged_parameters = dict(left_query.parameters)
         merged_parameters.update(right_query.parameters)
-        new_builder._parameters = merged_parameters
+        new_builder.set_parameters(merged_parameters)
         return new_builder
 
     def except_(self, other: Any) -> Self:
@@ -238,8 +247,8 @@ class SetOperationMixin:
         except_expr = exp.except_(left_expr, right_expr)
         new_builder = type(self)()
         new_builder.dialect = self.dialect
-        new_builder._expression = except_expr
+        cast("QueryBuilder", new_builder).set_expression(except_expr)
         merged_parameters = dict(left_query.parameters)
         merged_parameters.update(right_query.parameters)
-        new_builder._parameters = merged_parameters
+        new_builder.set_parameters(merged_parameters)
         return new_builder