sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/adapters/bigquery/driver.py

@@ -7,7 +7,7 @@ type coercion, error handling, and query job management.
 import datetime
 import logging
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, Optional, Union
+from typing import TYPE_CHECKING, Any
 
 import sqlglot
 import sqlglot.expressions as exp
@@ -16,29 +16,44 @@ from google.cloud.exceptions import GoogleCloudError
 
 from sqlspec.adapters.bigquery._types import BigQueryConnection
 from sqlspec.adapters.bigquery.type_converter import BigQueryTypeConverter
-from sqlspec.core.cache import get_cache_config
-from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
-from sqlspec.core.statement import StatementConfig
-from sqlspec.driver import SyncDriverAdapterBase
-from sqlspec.driver._common import ExecutionResult
-from sqlspec.exceptions import SQLParsingError, SQLSpecError
+from sqlspec.core import ParameterStyle, ParameterStyleConfig, StatementConfig, get_cache_config
+from sqlspec.driver import ExecutionResult, SyncDriverAdapterBase
+from sqlspec.exceptions import (
+    DatabaseConnectionError,
+    DataError,
+    NotFoundError,
+    OperationalError,
+    SQLParsingError,
+    SQLSpecError,
+    UniqueViolationError,
+)
 from sqlspec.utils.serializers import to_json
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
     from contextlib import AbstractContextManager
 
-    from sqlspec.core.result import SQLResult
-    from sqlspec.core.statement import SQL
-    from sqlspec.driver._sync import SyncDataDictionaryBase
+    from sqlspec.builder import QueryBuilder
+    from sqlspec.core import SQL, SQLResult, Statement, StatementFilter
+    from sqlspec.core.result import ArrowResult
+    from sqlspec.driver import SyncDataDictionaryBase
+    from sqlspec.typing import StatementParameters
 
 logger = logging.getLogger(__name__)
 
 __all__ = ("BigQueryCursor", "BigQueryDriver", "BigQueryExceptionHandler", "bigquery_statement_config")
 
-_type_converter = BigQueryTypeConverter()
+HTTP_CONFLICT = 409
+HTTP_NOT_FOUND = 404
+HTTP_BAD_REQUEST = 400
+HTTP_FORBIDDEN = 403
+HTTP_SERVER_ERROR = 500
+
 
+_default_type_converter = BigQueryTypeConverter()
 
-_BQ_TYPE_MAP: dict[type, tuple[str, Optional[str]]] = {
+
+_BQ_TYPE_MAP: dict[type, tuple[str, str | None]] = {
     bool: ("BOOL", None),
     int: ("INT64", None),
     float: ("FLOAT64", None),
@@ -51,7 +66,134 @@ _BQ_TYPE_MAP: dict[type, tuple[str, Optional[str]]] = {
 }
 
 
-def _get_bq_param_type(value: Any) -> tuple[Optional[str], Optional[str]]:
+def _create_array_parameter(name: str, value: Any, array_type: str) -> ArrayQueryParameter:
+    """Create BigQuery ARRAY parameter.
+
+    Args:
+        name: Parameter name.
+        value: Array value (converted to list, empty list if None).
+        array_type: BigQuery array element type.
+
+    Returns:
+        ArrayQueryParameter instance.
+    """
+    return ArrayQueryParameter(name, array_type, [] if value is None else list(value))
+
+
+def _create_json_parameter(name: str, value: Any, json_serializer: "Callable[[Any], str]") -> ScalarQueryParameter:
+    """Create BigQuery JSON parameter as STRING type.
+
+    Args:
+        name: Parameter name.
+        value: JSON-serializable value.
+        json_serializer: Function to serialize to JSON string.
+
+    Returns:
+        ScalarQueryParameter with STRING type.
+    """
+    return ScalarQueryParameter(name, "STRING", json_serializer(value))
+
+
+def _create_scalar_parameter(name: str, value: Any, param_type: str) -> ScalarQueryParameter:
+    """Create BigQuery scalar parameter.
+
+    Args:
+        name: Parameter name.
+        value: Scalar value.
+        param_type: BigQuery parameter type (INT64, FLOAT64, etc.).
+
+    Returns:
+        ScalarQueryParameter instance.
+    """
+    return ScalarQueryParameter(name, param_type, value)
+
+
+def _create_literal_node(value: Any, json_serializer: "Callable[[Any], str]") -> "exp.Expression":
+    """Create a SQLGlot literal expression from a Python value.
+
+    Args:
+        value: Python value to convert to SQLGlot literal.
+        json_serializer: Function to serialize dict/list to JSON string.
+
+    Returns:
+        SQLGlot expression representing the literal value.
+    """
+    if value is None:
+        return exp.Null()
+    if isinstance(value, bool):
+        return exp.Boolean(this=value)
+    if isinstance(value, (int, float)):
+        return exp.Literal.number(str(value))
+    if isinstance(value, str):
+        return exp.Literal.string(value)
+    if isinstance(value, (list, tuple)):
+        items = [_create_literal_node(item, json_serializer) for item in value]
+        return exp.Array(expressions=items)
+    if isinstance(value, dict):
+        json_str = json_serializer(value)
+        return exp.Literal.string(json_str)
+
+    return exp.Literal.string(str(value))
+
+
+def _replace_placeholder_node(
+    node: "exp.Expression",
+    parameters: Any,
+    placeholder_counter: dict[str, int],
+    json_serializer: "Callable[[Any], str]",
+) -> "exp.Expression":
+    """Replace placeholder or parameter nodes with literal values.
+
+    Handles both positional placeholders (?) and named parameters (@name, :name).
+    Converts values to SQLGlot literal expressions for safe embedding in SQL.
+
+    Args:
+        node: SQLGlot expression node to check and potentially replace.
+        parameters: Parameter values (dict, list, or tuple).
+        placeholder_counter: Mutable counter dict for positional placeholders.
+        json_serializer: Function to serialize dict/list to JSON string.
+
+    Returns:
+        Literal expression if replacement made, otherwise original node.
+    """
+    if isinstance(node, exp.Placeholder):
+        if isinstance(parameters, (list, tuple)):
+            current_index = placeholder_counter["index"]
+            placeholder_counter["index"] += 1
+            if current_index < len(parameters):
+                return _create_literal_node(parameters[current_index], json_serializer)
+        return node
+
+    if isinstance(node, exp.Parameter):
+        param_name = str(node.this) if hasattr(node.this, "__str__") else node.this
+
+        if isinstance(parameters, dict):
+            possible_names = [param_name, f"@{param_name}", f":{param_name}", f"param_{param_name}"]
+            for name in possible_names:
+                if name in parameters:
+                    actual_value = getattr(parameters[name], "value", parameters[name])
+                    return _create_literal_node(actual_value, json_serializer)
+            return node
+
+        if isinstance(parameters, (list, tuple)):
+            try:
+                if param_name.startswith("param_"):
+                    param_index = int(param_name[6:])
+                    if param_index < len(parameters):
+                        return _create_literal_node(parameters[param_index], json_serializer)
+
+                if param_name.isdigit():
+                    param_index = int(param_name)
+                    if param_index < len(parameters):
+                        return _create_literal_node(parameters[param_index], json_serializer)
+            except (ValueError, IndexError, AttributeError):
+                pass
+        return node
+
+    return node
+
+
+def _get_bq_param_type(value: Any) -> tuple[str | None, str | None]:
     """Determine BigQuery parameter type from Python value.
 
     Args:
@@ -84,20 +226,30 @@ def _get_bq_param_type(value: Any) -> tuple[Optional[str], Optional[str]]:
     return None, None
 
 
-_BQ_PARAM_CREATOR_MAP: dict[str, Any] = {
-    "ARRAY": lambda name, value, array_type: ArrayQueryParameter(
-        name, array_type, [] if value is None else list(value)
-    ),
-    "JSON": lambda name, value, _: ScalarQueryParameter(name, "STRING", to_json(value)),
-    "SCALAR": lambda name, value, param_type: ScalarQueryParameter(name, param_type, value),
-}
+def _get_bq_param_creator_map(json_serializer: "Callable[[Any], str]") -> dict[str, Any]:
+    """Get BigQuery parameter creator map with configurable JSON serializer.
+
+    Args:
+        json_serializer: Function to serialize dict/list to JSON string.
+
+    Returns:
+        Dictionary mapping parameter types to creator functions.
+    """
+    return {
+        "ARRAY": _create_array_parameter,
+        "JSON": lambda name, value, _: _create_json_parameter(name, value, json_serializer),
+        "SCALAR": _create_scalar_parameter,
+    }
 
 
-def _create_bq_parameters(parameters: Any) -> "list[Union[ArrayQueryParameter, ScalarQueryParameter]]":
+def _create_bq_parameters(
+    parameters: Any, json_serializer: "Callable[[Any], str]"
+) -> "list[ArrayQueryParameter | ScalarQueryParameter]":
     """Create BigQuery QueryParameter objects from parameters.
 
     Args:
         parameters: Dict of named parameters or list of positional parameters
+        json_serializer: Function to serialize dict/list to JSON string
 
     Returns:
         List of BigQuery QueryParameter objects
@@ -105,7 +257,8 @@ def _create_bq_parameters(parameters: Any) -> "list[Union[ArrayQueryParameter, S
     if not parameters:
         return []
 
-    bq_parameters: list[Union[ArrayQueryParameter, ScalarQueryParameter]] = []
+    bq_parameters: list[ArrayQueryParameter | ScalarQueryParameter] = []
+    param_creator_map = _get_bq_param_creator_map(json_serializer)
 
     if isinstance(parameters, dict):
         for name, value in parameters.items():
@@ -114,13 +267,13 @@ def _create_bq_parameters(parameters: Any) -> "list[Union[ArrayQueryParameter, S
             param_type, array_element_type = _get_bq_param_type(actual_value)
 
             if param_type == "ARRAY" and array_element_type:
-                creator = _BQ_PARAM_CREATOR_MAP["ARRAY"]
+                creator = param_creator_map["ARRAY"]
                 bq_parameters.append(creator(param_name_for_bq, actual_value, array_element_type))
             elif param_type == "JSON":
-                creator = _BQ_PARAM_CREATOR_MAP["JSON"]
+                creator = param_creator_map["JSON"]
                 bq_parameters.append(creator(param_name_for_bq, actual_value, None))
             elif param_type:
-                creator = _BQ_PARAM_CREATOR_MAP["SCALAR"]
+                creator = param_creator_map["SCALAR"]
                 bq_parameters.append(creator(param_name_for_bq, actual_value, param_type))
             else:
                 msg = f"Unsupported BigQuery parameter type for value of param '{name}': {type(actual_value)}"
@@ -133,21 +286,33 @@ def _create_bq_parameters(parameters: Any) -> "list[Union[ArrayQueryParameter, S
     return bq_parameters
 
 
-bigquery_type_coercion_map = {
-    tuple: list,
-    bool: lambda x: x,
-    int: lambda x: x,
-    float: lambda x: x,
-    str: _type_converter.convert_if_detected,
-    bytes: lambda x: x,
-    datetime.datetime: lambda x: x,
-    datetime.date: lambda x: x,
-    datetime.time: lambda x: x,
-    Decimal: lambda x: x,
-    dict: lambda x: x,
-    list: lambda x: x,
-    type(None): lambda _: None,
-}
+def _get_bigquery_type_coercion_map(type_converter: BigQueryTypeConverter) -> dict[type, Any]:
+    """Get BigQuery type coercion map with configurable type converter.
+
+    Args:
+        type_converter: BigQuery type converter instance
+
+    Returns:
+        Type coercion map for BigQuery
+    """
+    return {
+        tuple: list,
+        bool: lambda x: x,
+        int: lambda x: x,
+        float: lambda x: x,
+        str: type_converter.convert_if_detected,
+        bytes: lambda x: x,
+        datetime.datetime: lambda x: x,
+        datetime.date: lambda x: x,
+        datetime.time: lambda x: x,
+        Decimal: lambda x: x,
+        dict: lambda x: x,
+        list: lambda x: x,
+        type(None): lambda _: None,
+    }
+
+
+bigquery_type_coercion_map = _get_bigquery_type_coercion_map(_default_type_converter)
 
 
 bigquery_statement_config = StatementConfig(
@@ -176,7 +341,7 @@ class BigQueryCursor:
 
     def __init__(self, connection: "BigQueryConnection") -> None:
         self.connection = connection
-        self.job: Optional[QueryJob] = None
+        self.job: QueryJob | None = None
 
     def __enter__(self) -> "BigQueryConnection":
         return self.connection
@@ -195,7 +360,11 @@ class BigQueryCursor:
 
 
 class BigQueryExceptionHandler:
-    """Custom sync context manager for handling BigQuery database exceptions."""
+    """Context manager for handling BigQuery API exceptions.
+
+    Maps HTTP status codes and error reasons to specific SQLSpec exceptions
+    for better error handling in application code.
+    """
 
     __slots__ = ()
 
@@ -203,28 +372,82 @@ class BigQueryExceptionHandler:
         return None
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        _ = exc_tb
         if exc_type is None:
             return
-
         if issubclass(exc_type, GoogleCloudError):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "syntax" in error_msg or "invalid" in error_msg:
-                msg = f"BigQuery SQL syntax error: {e}"
-                raise SQLParsingError(msg) from e
-            if "permission" in error_msg or "access" in error_msg:
-                msg = f"BigQuery access error: {e}"
-                raise SQLSpecError(msg) from e
-            msg = f"BigQuery cloud error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, Exception):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "parse" in error_msg or "syntax" in error_msg:
-                msg = f"SQL parsing failed: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"Unexpected BigQuery operation error: {e}"
-            raise SQLSpecError(msg) from e
+            self._map_bigquery_exception(exc_val)
+
+    def _map_bigquery_exception(self, e: Any) -> None:
+        """Map BigQuery exception to SQLSpec exception.
+
+        Args:
+            e: Google API exception instance
+        """
+        status_code = getattr(e, "code", None)
+        error_msg = str(e).lower()
+
+        if status_code == HTTP_CONFLICT or "already exists" in error_msg:
+            self._raise_unique_violation(e, status_code)
+        elif status_code == HTTP_NOT_FOUND or "not found" in error_msg:
+            self._raise_not_found_error(e, status_code)
+        elif status_code == HTTP_BAD_REQUEST:
+            self._handle_bad_request(e, status_code, error_msg)
+        elif status_code == HTTP_FORBIDDEN:
+            self._raise_connection_error(e, status_code)
+        elif status_code and status_code >= HTTP_SERVER_ERROR:
+            self._raise_operational_error(e, status_code)
+        else:
+            self._raise_generic_error(e, status_code)
+
+    def _handle_bad_request(self, e: Any, code: "int | None", error_msg: str) -> None:
+        """Handle 400 Bad Request errors.
+
+        Args:
+            e: Exception instance
+            code: HTTP status code
+            error_msg: Lowercase error message
+        """
+        if "syntax" in error_msg or "invalid query" in error_msg:
+            self._raise_parsing_error(e, code)
+        elif "type" in error_msg or "format" in error_msg:
+            self._raise_data_error(e, code)
+        else:
+            self._raise_generic_error(e, code)
+
+    def _raise_unique_violation(self, e: Any, code: "int | None") -> None:
+        code_str = f"[HTTP {code}]" if code else ""
+        msg = f"BigQuery resource already exists {code_str}: {e}"
+        raise UniqueViolationError(msg) from e
+
+    def _raise_not_found_error(self, e: Any, code: "int | None") -> None:
+        code_str = f"[HTTP {code}]" if code else ""
+        msg = f"BigQuery resource not found {code_str}: {e}"
+        raise NotFoundError(msg) from e
+
+    def _raise_parsing_error(self, e: Any, code: "int | None") -> None:
+        code_str = f"[HTTP {code}]" if code else ""
+        msg = f"BigQuery query syntax error {code_str}: {e}"
+        raise SQLParsingError(msg) from e
+
+    def _raise_data_error(self, e: Any, code: "int | None") -> None:
+        code_str = f"[HTTP {code}]" if code else ""
+        msg = f"BigQuery data error {code_str}: {e}"
+        raise DataError(msg) from e
+
+    def _raise_connection_error(self, e: Any, code: "int | None") -> None:
+        code_str = f"[HTTP {code}]" if code else ""
+        msg = f"BigQuery permission denied {code_str}: {e}"
+        raise DatabaseConnectionError(msg) from e
+
+    def _raise_operational_error(self, e: Any, code: "int | None") -> None:
+        code_str = f"[HTTP {code}]" if code else ""
+        msg = f"BigQuery operational error {code_str}: {e}"
+        raise OperationalError(msg) from e
+
+    def _raise_generic_error(self, e: Any, code: "int | None") -> None:
+        msg = f"BigQuery error [HTTP {code}]: {e}" if code else f"BigQuery error: {e}"
+        raise SQLSpecError(msg) from e
 
 
 class BigQueryDriver(SyncDriverAdapterBase):
@@ -234,29 +457,53 @@ class BigQueryDriver(SyncDriverAdapterBase):
     type coercion, error handling, and query job management.
     """
 
-    __slots__ = ("_data_dictionary", "_default_query_job_config")
+    __slots__ = ("_data_dictionary", "_default_query_job_config", "_json_serializer", "_type_converter")
     dialect = "bigquery"
 
     def __init__(
         self,
         connection: BigQueryConnection,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
     ) -> None:
+        features = driver_features or {}
+
+        json_serializer = features.get("json_serializer")
+        if json_serializer is None:
+            json_serializer = to_json
+
+        self._json_serializer: Callable[[Any], str] = json_serializer
+
+        enable_uuid_conversion = features.get("enable_uuid_conversion", True)
+        self._type_converter = BigQueryTypeConverter(enable_uuid_conversion=enable_uuid_conversion)
+
         if statement_config is None:
             cache_config = get_cache_config()
-            statement_config = bigquery_statement_config.replace(
-                enable_caching=cache_config.compiled_cache_enabled,
+            type_coercion_map = _get_bigquery_type_coercion_map(self._type_converter)
+
+            param_config = ParameterStyleConfig(
+                default_parameter_style=ParameterStyle.NAMED_AT,
+                supported_parameter_styles={ParameterStyle.NAMED_AT, ParameterStyle.QMARK},
+                default_execution_parameter_style=ParameterStyle.NAMED_AT,
+                supported_execution_parameter_styles={ParameterStyle.NAMED_AT},
+                type_coercion_map=type_coercion_map,
+                has_native_list_expansion=True,
+                needs_static_script_compilation=False,
+                preserve_original_params_for_many=True,
+            )
+
+            statement_config = StatementConfig(
+                dialect="bigquery",
+                parameter_config=param_config,
                 enable_parsing=True,
                 enable_validation=True,
-                dialect="bigquery",
+                enable_caching=cache_config.compiled_cache_enabled,
+                enable_parameter_type_wrapping=True,
             )
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
-        self._default_query_job_config: Optional[QueryJobConfig] = (driver_features or {}).get(
-            "default_query_job_config"
-        )
-        self._data_dictionary: Optional[SyncDataDictionaryBase] = None
+        self._default_query_job_config: QueryJobConfig | None = (driver_features or {}).get("default_query_job_config")
+        self._data_dictionary: SyncDataDictionaryBase | None = None
 
     def with_cursor(self, connection: "BigQueryConnection") -> "BigQueryCursor":
         """Create context manager for cursor management.
@@ -279,20 +526,39 @@ class BigQueryDriver(SyncDriverAdapterBase):
         """Handle database-specific exceptions and wrap them appropriately."""
         return BigQueryExceptionHandler()
 
+    def _should_copy_attribute(self, attr: str, source_config: QueryJobConfig) -> bool:
+        """Check if attribute should be copied between job configs.
+
+        Args:
+            attr: Attribute name to check.
+            source_config: Source configuration object.
+
+        Returns:
+            True if attribute should be copied, False otherwise.
+        """
+        if attr.startswith("_"):
+            return False
+
+        try:
+            value = getattr(source_config, attr)
+            return value is not None and not callable(value)
+        except (AttributeError, TypeError):
+            return False
+
     def _copy_job_config_attrs(self, source_config: QueryJobConfig, target_config: QueryJobConfig) -> None:
         """Copy non-private attributes from source config to target config.
 
         Args:
-            source_config: Configuration to copy attributes from
-            target_config: Configuration to copy attributes to
+            source_config: Configuration to copy attributes from.
+            target_config: Configuration to copy attributes to.
         """
         for attr in dir(source_config):
-            if attr.startswith("_"):
+            if not self._should_copy_attribute(attr, source_config):
                 continue
+
             try:
                 value = getattr(source_config, attr)
-                if value is not None and not callable(value):
-                    setattr(target_config, attr, value)
+                setattr(target_config, attr, value)
             except (AttributeError, TypeError):
                 continue
 
@@ -300,8 +566,8 @@ class BigQueryDriver(SyncDriverAdapterBase):
         self,
         sql_str: str,
         parameters: Any,
-        connection: Optional[BigQueryConnection] = None,
-        job_config: Optional[QueryJobConfig] = None,
+        connection: BigQueryConnection | None = None,
+        job_config: QueryJobConfig | None = None,
     ) -> QueryJob:
         """Execute a BigQuery job with configuration support.
 
@@ -324,7 +590,7 @@ class BigQueryDriver(SyncDriverAdapterBase):
         if job_config:
             self._copy_job_config_attrs(job_config, final_job_config)
 
-        bq_parameters = _create_bq_parameters(parameters)
+        bq_parameters = _create_bq_parameters(parameters, self._json_serializer)
         final_job_config.query_parameters = bq_parameters
 
         return conn.query(sql_str, job_config=final_job_config)
@@ -341,7 +607,7 @@ class BigQueryDriver(SyncDriverAdapterBase):
         """
         return [dict(row) for row in rows_iterator]
 
-    def _try_special_handling(self, cursor: "Any", statement: "SQL") -> "Optional[SQLResult]":
+    def _try_special_handling(self, cursor: "Any", statement: "SQL") -> "SQLResult | None":
         """Hook for BigQuery-specific special operations.
 
         BigQuery doesn't have complex special operations like PostgreSQL COPY,
@@ -360,12 +626,15 @@ class BigQueryDriver(SyncDriverAdapterBase):
     def _transform_ast_with_literals(self, sql: str, parameters: Any) -> str:
         """Transform SQL AST by replacing placeholders with literal values.
 
+        Used for BigQuery script execution and execute_many operations where
+        parameter binding is not supported. Safely embeds values as SQL literals.
+
         Args:
-            sql: SQL string to transform
-            parameters: Parameters to embed as literals
+            sql: SQL string to transform.
+            parameters: Parameters to embed as literals.
 
         Returns:
-            Transformed SQL string with literals embedded
+            Transformed SQL string with literals embedded.
         """
         if not parameters:
             return sql
@@ -377,70 +646,12 @@ class BigQueryDriver(SyncDriverAdapterBase):
 
         placeholder_counter = {"index": 0}
 
-        def replace_placeholder(node: exp.Expression) -> exp.Expression:
-            """Replace placeholder nodes with literal values."""
-            if isinstance(node, exp.Placeholder):
-                if isinstance(parameters, (list, tuple)):
-                    current_index = placeholder_counter["index"]
-                    placeholder_counter["index"] += 1
-                    if current_index < len(parameters):
-                        return self._create_literal_node(parameters[current_index])
-                return node
-            if isinstance(node, exp.Parameter):
-                param_name = str(node.this) if hasattr(node.this, "__str__") else node.this
-                if isinstance(parameters, dict):
-                    possible_names = [param_name, f"@{param_name}", f":{param_name}", f"param_{param_name}"]
-                    for name in possible_names:
-                        if name in parameters:
-                            actual_value = getattr(parameters[name], "value", parameters[name])
-                            return self._create_literal_node(actual_value)
-                    return node
-                if isinstance(parameters, (list, tuple)):
-                    try:
-                        if param_name.startswith("param_"):
-                            param_index = int(param_name[6:])
-                            if param_index < len(parameters):
-                                return self._create_literal_node(parameters[param_index])
-
-                        if param_name.isdigit():
-                            param_index = int(param_name)
-                            if param_index < len(parameters):
-                                return self._create_literal_node(parameters[param_index])
-                    except (ValueError, IndexError, AttributeError):
-                        pass
-                return node
-            return node
-
-        transformed_ast = ast.transform(replace_placeholder)
+        transformed_ast = ast.transform(
+            lambda node: _replace_placeholder_node(node, parameters, placeholder_counter, self._json_serializer)
+        )
 
         return transformed_ast.sql(dialect="bigquery")
 
-    def _create_literal_node(self, value: Any) -> "exp.Expression":
-        """Create a SQLGlot literal expression from a Python value.
-
-        Args:
-            value: Python value to convert to SQLGlot literal
-
-        Returns:
-            SQLGlot expression representing the literal value
-        """
-        if value is None:
-            return exp.Null()
-        if isinstance(value, bool):
-            return exp.Boolean(this=value)
-        if isinstance(value, (int, float)):
-            return exp.Literal.number(str(value))
-        if isinstance(value, str):
-            return exp.Literal.string(value)
-        if isinstance(value, (list, tuple)):
-            items = [self._create_literal_node(item) for item in value]
-            return exp.Array(expressions=items)
-        if isinstance(value, dict):
-            json_str = to_json(value)
-            return exp.Literal.string(json_str)
-
-        return exp.Literal.string(str(value))
-
     def _execute_script(self, cursor: Any, statement: "SQL") -> ExecutionResult:
         """Execute SQL script with statement splitting and parameter handling.
 
@@ -550,3 +761,137 @@ class BigQueryDriver(SyncDriverAdapterBase):
 
             self._data_dictionary = BigQuerySyncDataDictionary()
         return self._data_dictionary
+
+    def _storage_api_available(self) -> bool:
+        """Check if BigQuery Storage API is available.
+
+        Returns:
+            True if Storage API is available and working, False otherwise
+        """
+        try:
+            from google.cloud import bigquery_storage_v1  # type: ignore[attr-defined]
+
+            # Try to create client (will fail if API not enabled or credentials missing)
+            _ = bigquery_storage_v1.BigQueryReadClient()
+        except ImportError:
+            # Package not installed
+            return False
+        except Exception:
+            # API not enabled or permissions issue
+            return False
+        else:
+            return True
+
+    def select_to_arrow(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        return_format: str = "table",
+        native_only: bool = False,
+        batch_size: int | None = None,
+        arrow_schema: Any = None,
+        **kwargs: Any,
+    ) -> "ArrowResult":
+        """Execute query and return results as Apache Arrow (BigQuery native with Storage API).
+
+        BigQuery provides native Arrow via Storage API (query_job.to_arrow()).
+        Requires google-cloud-bigquery-storage package and API enabled.
+        Falls back to dict conversion if Storage API not available.
+
+        Args:
+            statement: SQL statement, string, or QueryBuilder
+            *parameters: Query parameters or filters
+            statement_config: Optional statement configuration override
+            return_format: "table" for pyarrow.Table (default), "batch" for RecordBatch
+            native_only: If True, raise error if Storage API unavailable (default: False)
+            batch_size: Batch size hint (for future streaming implementation)
+            arrow_schema: Optional pyarrow.Schema for type casting
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            ArrowResult with native Arrow data (if Storage API available) or converted data
+
+        Raises:
+            MissingDependencyError: If pyarrow not installed, or if Storage API not available and native_only=True
+            SQLExecutionError: If query execution fails
+
+        Example:
+            >>> # Will use native Arrow if Storage API available, otherwise converts
+            >>> result = driver.select_to_arrow(
+            ...     "SELECT * FROM dataset.users WHERE age > @age",
+            ...     {"age": 18},
+            ... )
+            >>> df = result.to_pandas()
+
+            >>> # Force native Arrow (raises if Storage API unavailable)
+            >>> result = driver.select_to_arrow(
+            ...     "SELECT * FROM dataset.users", native_only=True
+            ... )
+        """
+        from sqlspec.utils.module_loader import ensure_pyarrow
+
+        ensure_pyarrow()
+
+        # Check Storage API availability
+        if not self._storage_api_available():
+            if native_only:
+                from sqlspec.exceptions import MissingDependencyError
+
+                msg = (
+                    "BigQuery native Arrow requires Storage API.\n"
+                    "1. Install: pip install google-cloud-bigquery-storage\n"
+                    "2. Enable API: https://console.cloud.google.com/apis/library/bigquerystorage.googleapis.com\n"
+                    "3. Grant permissions: roles/bigquery.dataViewer"
+                )
+                raise MissingDependencyError(
+                    package="google-cloud-bigquery-storage", install_package="google-cloud-bigquery-storage"
+                ) from RuntimeError(msg)
+
+            # Fallback to conversion path
+            result: ArrowResult = super().select_to_arrow(
+                statement,
+                *parameters,
+                statement_config=statement_config,
+                return_format=return_format,
+                native_only=native_only,
+                batch_size=batch_size,
+                arrow_schema=arrow_schema,
+                **kwargs,
+            )
+            return result
+
+        # Use native path with Storage API
+        import pyarrow as pa
+
+        from sqlspec.core.result import create_arrow_result
+
+        # Prepare statement
+        config = statement_config or self.statement_config
+        prepared_statement = self.prepare_statement(statement, parameters, statement_config=config, kwargs=kwargs)
+
+        # Get compiled SQL and parameters
+        sql, driver_params = self._get_compiled_sql(prepared_statement, config)
+
+        # Execute query using existing _run_query_job method
+        with self.handle_database_exceptions():
+            query_job = self._run_query_job(sql, driver_params)
+            query_job.result()  # Wait for completion
+
+            # Native Arrow via Storage API
+            arrow_table = query_job.to_arrow()
+
+            # Apply schema casting if requested
+            if arrow_schema is not None:
+                arrow_table = arrow_table.cast(arrow_schema)
+
+            # Convert to batch if requested
+            if return_format == "batch":
+                batches = arrow_table.to_batches()
+                arrow_data: Any = batches[0] if batches else pa.RecordBatch.from_pydict({})
+            else:
+                arrow_data = arrow_table
+
+        # Create ArrowResult
+        return create_arrow_result(statement=prepared_statement, data=arrow_data, rows_affected=arrow_data.num_rows)