sqlspec 0.10.1__py3-none-any.whl → 0.11.1__py3-none-any.whl

sqlspec/adapters/bigquery/driver.py

@@ -1,6 +1,7 @@
 import contextlib
 import datetime
-from collections.abc import Iterator, Sequence
+import logging
+from collections.abc import Iterator, Mapping, Sequence
 from decimal import Decimal
 from typing import (
     TYPE_CHECKING,
@@ -12,19 +13,21 @@ from typing import (
     overload,
 )
 
-import sqlglot
 from google.cloud import bigquery
 from google.cloud.bigquery import Client
 from google.cloud.bigquery.job import QueryJob, QueryJobConfig
 from google.cloud.exceptions import NotFound
 
 from sqlspec.base import SyncDriverAdapterProtocol
-from sqlspec.exceptions import NotFoundError, SQLSpecError
+from sqlspec.exceptions import NotFoundError, ParameterStyleMismatchError, SQLSpecError
+from sqlspec.filters import StatementFilter
 from sqlspec.mixins import (
+    ResultConverter,
     SQLTranslatorMixin,
     SyncArrowBulkOperationsMixin,
     SyncParquetExportMixin,
 )
+from sqlspec.statement import SQLStatement
 from sqlspec.typing import ArrowTable, ModelDTOT, StatementParameterType, T
 
 if TYPE_CHECKING:
@@ -35,12 +38,15 @@ __all__ = ("BigQueryConnection", "BigQueryDriver")
 
 BigQueryConnection = Client
 
+logger = logging.getLogger("sqlspec")
+
 
 class BigQueryDriver(
     SyncDriverAdapterProtocol["BigQueryConnection"],
     SyncArrowBulkOperationsMixin["BigQueryConnection"],
     SyncParquetExportMixin["BigQueryConnection"],
     SQLTranslatorMixin["BigQueryConnection"],
+    ResultConverter,
 ):
     """Synchronous BigQuery Driver Adapter."""
 
@@ -55,7 +61,7 @@ class BigQueryDriver(
         )
 
     @staticmethod
-    def _get_bq_param_type(value: Any) -> "tuple[Optional[str], Optional[str]]":  # noqa: PLR0911, PLR0912
+    def _get_bq_param_type(value: Any) -> "tuple[Optional[str], Optional[str]]":
         if isinstance(value, bool):
             return "BOOL", None
         if isinstance(value, int):
@@ -63,8 +69,6 @@ class BigQueryDriver(
         if isinstance(value, float):
             return "FLOAT64", None
         if isinstance(value, Decimal):
-            # Precision/scale might matter, but BQ client handles conversion.
-            # Defaulting to BIGNUMERIC, NUMERIC might be desired in some cases though (User change)
             return "BIGNUMERIC", None
         if isinstance(value, str):
             return "STRING", None
@@ -72,23 +76,17 @@ class BigQueryDriver(
             return "BYTES", None
         if isinstance(value, datetime.date):
             return "DATE", None
-        # DATETIME is for timezone-naive values
         if isinstance(value, datetime.datetime) and value.tzinfo is None:
             return "DATETIME", None
-        # TIMESTAMP is for timezone-aware values
         if isinstance(value, datetime.datetime) and value.tzinfo is not None:
             return "TIMESTAMP", None
         if isinstance(value, datetime.time):
             return "TIME", None
 
-        # Handle Arrays - Determine element type
         if isinstance(value, (list, tuple)):
             if not value:
-                # Cannot determine type of empty array, BQ requires type.
-                # Raise or default? Defaulting is risky. Let's raise.
                 msg = "Cannot determine BigQuery ARRAY type for empty sequence."
                 raise SQLSpecError(msg)
-            # Infer type from first element
             first_element = value[0]
             element_type, _ = BigQueryDriver._get_bq_param_type(first_element)
             if element_type is None:
@@ -96,19 +94,68 @@ class BigQueryDriver(
                 raise SQLSpecError(msg)
             return "ARRAY", element_type
 
-        # Handle Structs (basic dict mapping) - Requires careful handling
-        # if isinstance(value, dict):
-        #    # This requires recursive type mapping for sub-fields.
-        #    # For simplicity, users might need to construct StructQueryParameter manually.
-        #    # return "STRUCT", None # Placeholder if implementing  # noqa: ERA001
-        #    raise SQLSpecError("Automatic STRUCT mapping not implemented. Please use bigquery.StructQueryParameter.")  # noqa: ERA001
+        return None, None
+
+    def _process_sql_params(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        *filters: "StatementFilter",
+        **kwargs: Any,
+    ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
+        """Process SQL and parameters using SQLStatement with dialect support.
+
+        This method also handles the separation of StatementFilter instances that might be
+        passed in the 'parameters' argument.
+
+        Args:
+            sql: The SQL statement to process.
+            parameters: The parameters to bind to the statement. This can be a
+                        Mapping (dict), Sequence (list/tuple), a single StatementFilter, or None.
+            *filters: Additional statement filters to apply.
+            **kwargs: Additional keyword arguments (treated as named parameters for the SQL statement).
+
+        Raises:
+            ParameterStyleMismatchError: If pre-formatted BigQuery parameters are mixed with keyword arguments.
+
+        Returns:
+            A tuple of (processed_sql, processed_parameters) ready for execution.
+        """
+        passed_parameters: Optional[Union[Mapping[str, Any], Sequence[Any]]] = None
+        combined_filters_list: list[StatementFilter] = list(filters)
+
+        if parameters is not None:
+            if isinstance(parameters, StatementFilter):
+                combined_filters_list.insert(0, parameters)
+            else:
+                passed_parameters = parameters
+
+        if (
+            isinstance(passed_parameters, (list, tuple))
+            and passed_parameters
+            and all(
+                isinstance(p, (bigquery.ScalarQueryParameter, bigquery.ArrayQueryParameter)) for p in passed_parameters
+            )
+        ):
+            if kwargs:
+                msg = "Cannot mix pre-formatted BigQuery parameters with keyword arguments."
+                raise ParameterStyleMismatchError(msg)
+            return sql, passed_parameters
+
+        statement = SQLStatement(sql, passed_parameters, kwargs=kwargs, dialect=self.dialect)
+
+        for filter_obj in combined_filters_list:
+            statement = statement.apply_filter(filter_obj)
 
-        return None, None  # Unsupported type
+        processed_sql, processed_params, _ = statement.process()
 
-    def _run_query_job(  # noqa: C901, PLR0912, PLR0915 (User change)
+        return processed_sql, processed_params
+
+    def _run_query_job(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         is_script: bool = False,
@@ -116,131 +163,71 @@ class BigQueryDriver(
     ) -> "QueryJob":
         conn = self._connection(connection)
 
-        # Determine the final job config, creating a new one if necessary
-        # to avoid modifying a shared default config.
         if job_config:
-            final_job_config = job_config  # Use the provided config directly
+            final_job_config = job_config
         elif self._default_query_job_config:
-            final_job_config = QueryJobConfig()
+            final_job_config = QueryJobConfig.from_api_repr(self._default_query_job_config.to_api_repr())  # type: ignore[assignment]
         else:
-            final_job_config = QueryJobConfig()  # Create a fresh config
+            final_job_config = QueryJobConfig()
 
-        # --- Parameter Handling Logic --- Start
-        params: Union[dict[str, Any], list[Any], None] = None
-        param_style: Optional[str] = None  # 'named' (@), 'qmark' (?)
-        use_preformatted_params = False
-        final_sql = sql  # Default to original SQL
+        final_sql, processed_params = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
-        # Check for pre-formatted BQ parameters first
         if (
-            isinstance(parameters, (list, tuple))
-            and parameters
-            and all(isinstance(p, (bigquery.ScalarQueryParameter, bigquery.ArrayQueryParameter)) for p in parameters)
+            isinstance(processed_params, (list, tuple))
+            and processed_params
+            and all(
+                isinstance(p, (bigquery.ScalarQueryParameter, bigquery.ArrayQueryParameter)) for p in processed_params
+            )
         ):
-            if kwargs:
-                msg = "Cannot mix pre-formatted BigQuery parameters with keyword arguments."
-                raise SQLSpecError(msg)
-            use_preformatted_params = True
-            final_job_config.query_parameters = list(parameters)
-            # Keep final_sql = sql, as it should match the pre-formatted named params
-
-        # Determine parameter style and merge standard parameters ONLY if not preformatted
-        if not use_preformatted_params:
-            if isinstance(parameters, dict):
-                params = {**parameters, **kwargs}
-                param_style = "named"
-            elif isinstance(parameters, (list, tuple)):
-                if kwargs:
-                    msg = "Cannot mix positional parameters with keyword arguments."
-                    raise SQLSpecError(msg)
-                # Check if it's primitives for qmark style
-                if all(
-                    not isinstance(p, (bigquery.ScalarQueryParameter, bigquery.ArrayQueryParameter)) for p in parameters
-                ):
-                    params = list(parameters)
-                    param_style = "qmark"
-                else:
-                    # Mixed list or non-BQ parameter objects
-                    msg = "Invalid mix of parameter types in list. Use only primitive values or only BigQuery QueryParameter objects."
-                    raise SQLSpecError(msg)
-
-            elif kwargs:
-                params = kwargs
-                param_style = "named"
-            elif parameters is not None and not isinstance(
-                parameters, (bigquery.ScalarQueryParameter, bigquery.ArrayQueryParameter)
-            ):
-                # Could be a single primitive value for positional
-                params = [parameters]
-                param_style = "qmark"
-            elif parameters is not None:  # Single BQ parameter object
-                msg = "Single BigQuery QueryParameter objects should be passed within a list."
-                raise SQLSpecError(msg)
-
-        # Use sqlglot to transpile ONLY if not a script and not preformatted
-        if not is_script and not use_preformatted_params:
-            try:
-                # Transpile for syntax normalization/dialect conversion if needed
-                # Use BigQuery dialect for both reading and writing
-                final_sql = sqlglot.transpile(sql, read=self.dialect, write=self.dialect)[0]
-            except Exception as e:
-                # Catch potential sqlglot errors
-                msg = f"SQL transpilation failed using sqlglot: {e!s}"  # Adjusted message
-                raise SQLSpecError(msg) from e
-            # else: If preformatted_params, final_sql remains the original sql
-
-        # --- Parameter Handling Logic --- (Moved outside the transpilation try/except)
-        # Prepare BQ parameters based on style, ONLY if not preformatted
-        if not use_preformatted_params:
-            if param_style == "named" and params:
-                # Convert dict params to BQ ScalarQueryParameter
-                if isinstance(params, dict):
-                    final_job_config.query_parameters = [
-                        bigquery.ScalarQueryParameter(name, self._get_bq_param_type(value)[0], value)
-                        for name, value in params.items()
-                    ]
-                else:
-                    # This path should ideally not be reached if param_style logic is correct
-                    msg = f"Internal error: Parameter style is 'named' but parameters are not a dict: {type(params)}"
-                    raise SQLSpecError(msg)
-            elif param_style == "qmark" and params:
-                # Convert list params to BQ ScalarQueryParameter
-                final_job_config.query_parameters = [
-                    bigquery.ScalarQueryParameter(None, self._get_bq_param_type(value)[0], value) for value in params
-                ]
-
-        # --- Parameter Handling Logic --- End
+            final_job_config.query_parameters = list(processed_params)
+        elif isinstance(processed_params, dict):
+            final_job_config.query_parameters = [
+                bigquery.ScalarQueryParameter(name, self._get_bq_param_type(value)[0], value)
+                for name, value in processed_params.items()
+            ]
+        elif isinstance(processed_params, (list, tuple)):
+            final_job_config.query_parameters = [
+                bigquery.ScalarQueryParameter(None, self._get_bq_param_type(value)[0], value)
+                for value in processed_params
+            ]
 
-        # Determine which kwargs to pass to the actual query method.
-        # We only want to pass kwargs that were *not* treated as SQL parameters.
         final_query_kwargs = {}
-        if parameters is not None and kwargs:  # Params came via arg, kwargs are separate
+        if parameters is not None and kwargs:
             final_query_kwargs = kwargs
-        # Else: If params came via kwargs, they are already handled, so don't pass them again.
 
-        # Execute query
         return conn.query(
             final_sql,
-            job_config=final_job_config,
-            **final_query_kwargs,  # Pass only relevant kwargs
+            job_config=final_job_config,  # pyright: ignore
+            **final_query_kwargs,
         )
 
-    @staticmethod
+    @overload
     def _rows_to_results(
+        self,
+        rows: "Iterator[Row]",
+        schema: "Sequence[SchemaField]",
+        schema_type: "type[ModelDTOT]",
+    ) -> Sequence[ModelDTOT]: ...
+    @overload
+    def _rows_to_results(
+        self,
+        rows: "Iterator[Row]",
+        schema: "Sequence[SchemaField]",
+        schema_type: None = None,
+    ) -> Sequence[dict[str, Any]]: ...
+    def _rows_to_results(
+        self,
         rows: "Iterator[Row]",
         schema: "Sequence[SchemaField]",
         schema_type: "Optional[type[ModelDTOT]]" = None,
     ) -> Sequence[Union[ModelDTOT, dict[str, Any]]]:
         processed_results = []
-        # Create a quick lookup map for schema fields from the passed schema
         schema_map = {field.name: field for field in schema}
 
         for row in rows:
-            # row here is now a Row object from the iterator
             row_dict = {}
-            for key, value in row.items():  # Use row.items() on the Row object
+            for key, value in row.items():
                 field = schema_map.get(key)
-                # Workaround remains the same
                 if field and field.field_type == "TIMESTAMP" and isinstance(value, str) and "." in value:
                     try:
                         parsed_value = datetime.datetime.fromtimestamp(float(value), tz=datetime.timezone.utc)
@@ -249,22 +236,15 @@ class BigQueryDriver(
                         row_dict[key] = value  # type: ignore[assignment]
                 else:
                     row_dict[key] = value
-            # Use the processed dictionary for the final result
-            if schema_type:
-                processed_results.append(schema_type(**row_dict))
-            else:
-                processed_results.append(row_dict)  # type: ignore[arg-type]
-        if schema_type:
-            return cast("Sequence[ModelDTOT]", processed_results)
-        return cast("Sequence[dict[str, Any]]", processed_results)
+            processed_results.append(row_dict)
+        return self.to_schema(processed_results, schema_type=schema_type)
 
     @overload
     def select(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -274,8 +254,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -284,14 +263,15 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
     ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]":
-        query_job = self._run_query_job(sql, parameters, connection, job_config, **kwargs)
+        query_job = self._run_query_job(
+            sql, parameters, *filters, connection=connection, job_config=job_config, **kwargs
+        )
         return self._rows_to_results(query_job.result(), query_job.result().schema, schema_type)
 
     @overload
@@ -299,8 +279,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -310,8 +289,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -320,24 +298,19 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
     ) -> "Union[ModelDTOT, dict[str, Any]]":
-        query_job = self._run_query_job(sql, parameters, connection, job_config, **kwargs)
+        query_job = self._run_query_job(
+            sql, parameters, *filters, connection=connection, job_config=job_config, **kwargs
+        )
         rows_iterator = query_job.result()
         try:
-            # Pass the iterator containing only the first row to _rows_to_results
-            # This ensures the timestamp workaround is applied consistently.
-            # We need to pass the original iterator for schema access, but only consume one row.
             first_row = next(rows_iterator)
-            # Create a simple iterator yielding only the first row for processing
             single_row_iter = iter([first_row])
-            # We need RowIterator type for schema, create mock/proxy if needed, or pass schema
-            # Let's try passing schema directly to _rows_to_results (requires modifying it)
             results = self._rows_to_results(single_row_iter, rows_iterator.schema, schema_type)
             return results[0]
         except StopIteration:
@@ -349,8 +322,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -360,8 +332,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -370,20 +341,19 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]":
-        query_job = self._run_query_job(sql, parameters, connection, job_config, **kwargs)
+        query_job = self._run_query_job(
+            sql, parameters, *filters, connection=connection, job_config=job_config, **kwargs
+        )
         rows_iterator = query_job.result()
         try:
             first_row = next(rows_iterator)
-            # Create a simple iterator yielding only the first row for processing
             single_row_iter = iter([first_row])
-            # Pass schema directly
             results = self._rows_to_results(single_row_iter, rows_iterator.schema, schema_type)
             return results[0]
         except StopIteration:
@@ -394,8 +364,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
@@ -406,8 +375,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -416,22 +384,20 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
     ) -> Union[T, Any]:
         query_job = self._run_query_job(
-            sql=sql, parameters=parameters, connection=connection, job_config=job_config, **kwargs
+            sql, parameters, *filters, connection=connection, job_config=job_config, **kwargs
         )
         rows = query_job.result()
         try:
             first_row = next(iter(rows))
             value = first_row[0]
-            # Apply timestamp workaround if necessary
-            field = rows.schema[0]  # Get schema for the first column
+            field = rows.schema[0]
             if field and field.field_type == "TIMESTAMP" and isinstance(value, str) and "." in value:
                 with contextlib.suppress(ValueError):
                     value = datetime.datetime.fromtimestamp(float(value), tz=datetime.timezone.utc)
@@ -446,8 +412,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -457,8 +422,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -467,22 +431,25 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[T, Any]]":
         query_job = self._run_query_job(
-            sql=sql, parameters=parameters, connection=connection, job_config=job_config, **kwargs
+            sql,
+            parameters,
+            *filters,
+            connection=connection,
+            job_config=job_config,
+            **kwargs,
         )
         rows = query_job.result()
         try:
             first_row = next(iter(rows))
             value = first_row[0]
-            # Apply timestamp workaround if necessary
-            field = rows.schema[0]  # Get schema for the first column
+            field = rows.schema[0]
             if field and field.field_type == "TIMESTAMP" and isinstance(value, str) and "." in value:
                 with contextlib.suppress(ValueError):
                     value = datetime.datetime.fromtimestamp(float(value), tz=datetime.timezone.utc)
@@ -495,32 +462,23 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: Optional["BigQueryConnection"] = None,
         job_config: Optional[QueryJobConfig] = None,
         **kwargs: Any,
     ) -> int:
-        """Executes INSERT, UPDATE, DELETE and returns affected row count.
-
-        Returns:
-            int: The number of rows affected by the DML statement.
-        """
         query_job = self._run_query_job(
-            sql=sql, parameters=parameters, connection=connection, job_config=job_config, **kwargs
+            sql, parameters, *filters, connection=connection, job_config=job_config, **kwargs
         )
-        # DML statements might not return rows, check job properties
-        # num_dml_affected_rows might be None initially, wait might be needed
-        query_job.result()  # Ensure completion
-        return query_job.num_dml_affected_rows or 0  # Return 0 if None
+        query_job.result()
+        return query_job.num_dml_affected_rows or 0
 
     @overload
     def insert_update_delete_returning(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -530,8 +488,7 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -540,35 +497,26 @@ class BigQueryDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
     ) -> Union[ModelDTOT, dict[str, Any]]:
-        """BigQuery DML RETURNING equivalent is complex, often requires temp tables or scripting."""
         msg = "BigQuery does not support `RETURNING` clauses directly in the same way as some other SQL databases. Consider multi-statement queries or alternative approaches."
         raise NotImplementedError(msg)
 
     def execute_script(
         self,
-        sql: str,  # Expecting a script here
-        parameters: "Optional[StatementParameterType]" = None,  # Parameters might be complex in scripts
-        /,
-        *,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
         connection: "Optional[BigQueryConnection]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
     ) -> str:
-        """Executes a BigQuery script and returns the job ID.
-
-        Returns:
-            str: The job ID of the executed script.
-        """
         query_job = self._run_query_job(
-            sql=sql,
-            parameters=parameters,
+            sql,
+            parameters,
             connection=connection,
             job_config=job_config,
             is_script=True,
@@ -576,14 +524,11 @@ class BigQueryDriver(
         )
         return str(query_job.job_id)
 
-    # --- Mixin Implementations ---
-
-    def select_arrow(  # pyright: ignore  # noqa: PLR0912
+    def select_arrow(  # pyright: ignore
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[BigQueryConnection]" = None,
         job_config: "Optional[QueryJobConfig]" = None,
         **kwargs: Any,
@@ -591,41 +536,11 @@ class BigQueryDriver(
         conn = self._connection(connection)
         final_job_config = job_config or self._default_query_job_config or QueryJobConfig()
 
-        # Determine parameter style and merge parameters (Similar to _run_query_job)
-        params: Union[dict[str, Any], list[Any], None] = None
-        param_style: Optional[str] = None  # 'named' (@), 'qmark' (?)
-
-        if isinstance(parameters, dict):
-            params = {**parameters, **kwargs}
-            param_style = "named"
-        elif isinstance(parameters, (list, tuple)):
-            if kwargs:
-                msg = "Cannot mix positional parameters with keyword arguments."
-                raise SQLSpecError(msg)
-            params = list(parameters)
-            param_style = "qmark"
-        elif kwargs:
-            params = kwargs
-            param_style = "named"
-        elif parameters is not None:
-            params = [parameters]
-            param_style = "qmark"
-
-        # Use sqlglot to transpile and bind parameters
-        try:
-            transpiled_sql = sqlglot.transpile(sql, args=params or {}, read=None, write=self.dialect)[0]
-        except Exception as e:
-            msg = f"SQL transpilation/binding failed using sqlglot: {e!s}"
-            raise SQLSpecError(msg) from e
+        processed_sql, processed_params = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
-        # Prepare BigQuery specific parameters if named style was used
-        if param_style == "named" and params:
-            if not isinstance(params, dict):
-                # This should be logically impossible due to how param_style is set
-                msg = "Internal error: named parameter style detected but params is not a dict."
-                raise SQLSpecError(msg)
+        if isinstance(processed_params, dict):
             query_parameters = []
-            for key, value in params.items():
+            for key, value in processed_params.items():
                 param_type, array_element_type = self._get_bq_param_type(value)
 
                 if param_type == "ARRAY" and array_element_type:
@@ -636,15 +551,15 @@ class BigQueryDriver(
                     msg = f"Unsupported parameter type for BigQuery Arrow named parameter '{key}': {type(value)}"
                     raise SQLSpecError(msg)
             final_job_config.query_parameters = query_parameters
-        elif param_style == "qmark" and params:
-            # Positional params handled by client library
-            pass
+        elif isinstance(processed_params, (list, tuple)):
+            final_job_config.query_parameters = [
+                bigquery.ScalarQueryParameter(None, self._get_bq_param_type(value)[0], value)
+                for value in processed_params
+            ]
 
-        # Execute the query and get Arrow table
         try:
-            query_job = conn.query(transpiled_sql, job_config=final_job_config)
-            arrow_table = query_job.to_arrow()  # Waits for job completion
-
+            query_job = conn.query(processed_sql, job_config=final_job_config)
+            arrow_table = query_job.to_arrow()
         except Exception as e:
             msg = f"BigQuery Arrow query execution failed: {e!s}"
             raise SQLSpecError(msg) from e
@@ -652,31 +567,34 @@ class BigQueryDriver(
 
     def select_to_parquet(
         self,
-        sql: str,  # Expects table ID: project.dataset.table
+        sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         destination_uri: "Optional[str]" = None,
         connection: "Optional[BigQueryConnection]" = None,
         job_config: "Optional[bigquery.ExtractJobConfig]" = None,
         **kwargs: Any,
     ) -> None:
-        """Exports a BigQuery table to Parquet files in Google Cloud Storage.
-
-        Raises:
-            NotImplementedError: If the SQL is not a fully qualified table ID or if parameters are provided.
-            NotFoundError: If the source table is not found.
-            SQLSpecError: If the Parquet export fails.
-        """
         if destination_uri is None:
             msg = "destination_uri is required"
             raise SQLSpecError(msg)
         conn = self._connection(connection)
-        if "." not in sql or parameters is not None:
-            msg = "select_to_parquet currently expects a fully qualified table ID (project.dataset.table) as the `sql` argument and no `parameters`."
+
+        if parameters is not None:
+            msg = (
+                "select_to_parquet expects a fully qualified table ID (e.g., 'project.dataset.table') "
+                "as the `sql` argument and does not support `parameters`."
+            )
             raise NotImplementedError(msg)
 
-        source_table_ref = bigquery.TableReference.from_string(sql, default_project=conn.project)
+        try:
+            source_table_ref = bigquery.TableReference.from_string(sql, default_project=conn.project)
+        except ValueError as e:
+            msg = (
+                "select_to_parquet expects a fully qualified table ID (e.g., 'project.dataset.table') "
+                f"as the `sql` argument. Parsing failed for input '{sql}': {e!s}"
+            )
+            raise NotImplementedError(msg) from e
 
         final_extract_config = job_config or bigquery.ExtractJobConfig()  # type: ignore[no-untyped-call]
         final_extract_config.destination_format = bigquery.DestinationFormat.PARQUET
@@ -686,9 +604,8 @@ class BigQueryDriver(
                 source_table_ref,
                 destination_uri,
                 job_config=final_extract_config,
-                # Location is correctly inferred by the client library
             )
-            extract_job.result()  # Wait for completion
+            extract_job.result()
 
         except NotFound:
             msg = f"Source table not found for Parquet export: {source_table_ref}"
@@ -699,3 +616,6 @@ class BigQueryDriver(
         if extract_job.errors:
             msg = f"BigQuery Parquet export failed: {extract_job.errors}"
             raise SQLSpecError(msg)
+
+    def _connection(self, connection: "Optional[BigQueryConnection]" = None) -> "BigQueryConnection":
+        return connection or self.connection