bigquery Adapter¶

from sqlspec.adapters.bigquery import (
    BigQueryConfig,
    BigQueryConnectionParams,
    BigQueryDriver,
    BigQueryDriverFeatures,
    BigQueryExceptionHandler,
)

Google Cloud BigQuery analytical adapter built on google-cloud-bigquery and google-cloud-bigquery-storage for high-throughput Arrow result streaming. Inherited execution methods are documented on SyncDriverAdapterBase. See the BigQuery Setup Guide for authentication and Storage Read API configuration.

Configuration & Parameters¶

BigQueryConfig ¶

Bases: NoPoolSyncConfig[BigQueryConnection, BigQueryDriver]

BigQuery configuration.

Configuration for Google Cloud BigQuery connections.

`BigQueryConnectionParams` ¶

Bases: TypedDict

Google Cloud BigQuery client and default QueryJobConfig parameters.

Attributes:

Name	Type	Description
`project`	`NotRequired[str]`	Billing and default job execution Google Cloud project ID.
`project_id`	`NotRequired[str]`	Alias normalized to `project` when `project` is unset.
`location`	`NotRequired[str]`	Default geographic region or multi-region (such as `'US'` or `'EU'`) for jobs and datasets.
`credentials`	`NotRequired[BigQueryCredentials]`	Explicit `google.auth.credentials.Credentials` instance overriding ADC.
`client_options`	`NotRequired[BigQueryClientOptions]`	GAPIC `ClientOptions` configuring custom endpoints, quota project, or scopes.
`client_info`	`NotRequired[BigQueryClientInfo]`	Custom `ClientInfo` user-agent metadata attached to BigQuery API requests.
`default_query_job_config`	`NotRequired[BigQueryQueryJobConfig]`	Base `QueryJobConfig` cloned and overlaid with top-level query governance fields.
`default_load_job_config`	`NotRequired[BigQueryLoadJobConfig]`	Base `LoadJobConfig` passed to the BigQuery `Client` for load jobs.
`default_job_creation_mode`	`NotRequired[str]`	Client job creation mode (such as `'JOB_CREATION_OPTIONAL'` for stateless short queries).
`dataset_id`	`NotRequired[str]`	Default dataset (`dataset` or `project.dataset`) used to resolve unqualified table names.
`dataset`	`NotRequired[str]`	Alias normalized to `dataset_id` when `dataset_id` is unset.
`database`	`NotRequired[str]`	Alias normalized to `dataset_id` when `dataset_id` is unset.
`db`	`NotRequired[str]`	Short alias normalized to `dataset_id` when `dataset_id` is unset.
`use_query_cache`	`NotRequired[bool]`	Read from BigQuery cached query results when unmodified (defaults to `True`).
`maximum_bytes_billed`	`NotRequired[int]`	Per-query cost guard failing queries estimated to scan above this byte limit.
`query_timeout_ms`	`NotRequired[int]`	Server-side query execution timeout in milliseconds applied to `job_timeout_ms`.
`job_timeout_ms`	`NotRequired[int]`	Server-side BigQuery job execution timeout in milliseconds.
`labels`	`NotRequired[dict[str, str]]`	Billing and governance key-value labels attached to executed query jobs.
`priority`	`NotRequired[Literal['INTERACTIVE', 'BATCH']]`	BigQuery query scheduling priority (`'INTERACTIVE'` or `'BATCH'`).
`reservation`	`NotRequired[str]`	BigQuery Editions slot reservation resource path assigned to query jobs.
`max_slots`	`NotRequired[int]`	Maximum slot concurrency cap applied to individual query jobs.
`extra`	`NotRequired[dict[str, Any]]`	Additional keyword metadata retained in normalized connection configuration.

`BigQueryDriverFeatures` ¶

Bases: TypedDict

BigQuery driver feature flags controlling query execution, Storage Write API, and EXPORT DATA.

Attributes:

Name	Type	Description
`connection_instance`	`NotRequired[BigQueryConnection]`	Pre-created `google.cloud.bigquery.Client` reused without transferring lifecycle ownership.
`on_connection_create`	`NotRequired[Callable[[Any], None]]`	Callback invoked with the `bigquery.Client` when instantiated by the config.
`json_serializer`	`NotRequired[Callable[[Any], str]]`	Serializer converting dict/list parameters to JSON strings (defaults to `sqlspec.utils.serializers.to_json`).
`enable_uuid_conversion`	`NotRequired[bool]`	Automatically coerce `UUID` strings and parameters (defaults to `True`).
`enable_events`	`NotRequired[bool]`	Enable SQLSpec table-backed event channel support.
`events_backend`	`NotRequired[Literal['poll_queue']]`	Event queue backend name (`'poll_queue'`).
`job_retry_deadline`	`NotRequired[float]`	Total seconds to retry transient query failures (defaults to `60.0`; `<= 0` disables retries).
`job_result_timeout`	`NotRequired[float]`	Maximum seconds to poll `QueryJob.result()` before raising a timeout error.
`use_query_and_wait`	`NotRequired[bool]`	Execute single-statement queries via low-latency `Client.query_and_wait()` outside transactions (defaults to `True`).
`request_timeout`	`NotRequired[float]`	Per-request HTTP transport timeout in seconds for job submission calls (defaults to `job_result_timeout` or `120.0`).
`query_page_size`	`NotRequired[int]`	Page size forwarded to `QueryJob.result()` when fetching `SELECT` rows.
`query_max_results`	`NotRequired[int]`	Maximum total rows fetched from `QueryJob.result()`.
`enable_storage_write_api`	`NotRequired[bool]`	Route append `load_from_arrow` calls through the BigQuery Storage Write API with Parquet load fallback (defaults to `False`).
`storage_write_stream_type`	`NotRequired[Literal['COMMITTED', 'PENDING']]`	Storage Write API stream mode (`'PENDING'` default atomic commit or `'COMMITTED'` immediate visibility).
`enable_native_storage`	`NotRequired[bool]`	Route eligible remote object-store exports through server-side `EXPORT DATA` (defaults to `True`).
`native_export_connection`	`NotRequired[str]`	BigQuery Cloud Resource connection ID (`project.location.connection`) required for cross-cloud S3/Azure `EXPORT DATA`.

Driver & Pool¶

BigQueryDriver ¶

Bases: SyncDriverAdapterBase

BigQuery driver implementation.

Provides Google Cloud BigQuery connectivity with parameter style conversion, type coercion, error handling, and query job management.

BigQueryExceptionHandler ¶

Bases: BaseSyncExceptionHandler

Context manager for handling BigQuery API exceptions.

Maps HTTP status codes and API error reasons to SQLSpec exceptions stored on pending_exception.

Extension Stores¶

BigQueryStore ¶

Bases: BaseSQLSpecStore['BigQueryConfig']

BigQuery session store using synchronous BigQuery driver.

Implements server-side session storage for Litestar using Google BigQuery. Uses Litestar's sync_to_thread utility to provide an async interface compatible with the Store protocol.

Provides efficient session management with

Sync operations wrapped for async compatibility
MERGE for UPSERT functionality
Native TIMESTAMP type support
Automatic expiration handling
Efficient cleanup of expired sessions
Table clustering on session_id for optimized lookups

Parameters:

Name	Type	Description	Default
`config`	`BigQueryConfig`	BigQueryConfig instance.	required

BigQueryADKStore ¶

Bases: BaseSyncADKStore[BigQueryConfig]

BigQuery ADK session/event/scoped-state store.

The store exposes the synchronous ADK store contract because BigQuery is a synchronous SQLSpec adapter. SQLSpecSessionService provides async bridging when Google ADK calls it from async service methods.

BigQueryEventQueueStore ¶

Bases: BaseEventQueueStore[BigQueryConfig]

BigQuery-specific event queue store with clustering optimization.

Generates DDL optimized for BigQuery. BigQuery does not support traditional indexes, so the table uses CLUSTER BY for query optimization instead.