SQLAlchemy BigQuery Dialect (sqlalchemy-bigquery) is a Python library that provides a SQLAlchemy dialect for connecting to and interacting with Google BigQuery. It enables users to leverage SQLAlchemy's Core and ORM functionalities to query, manipulate, and manage BigQuery data, treating it like a traditional relational database. The library is actively maintained by Google Cloud, with regular releases, and its current version is 1.16.0.
pip install sqlalchemy-bigqueryVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to establish a connection to Google BigQuery using `sqlalchemy-bigquery` and perform basic queries using both raw SQL and SQLAlchemy Core expressions. It assumes Google Cloud authentication is configured, typically via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable or `gcloud` CLI.
Upgrade Python to version 3.9 or newer. The current PyPI metadata indicates support up to `<3.15`.
Ensure your SQLAlchemy installation is version 1.4.x or 2.0.x.
Use the full path in your connection string or `Table` definition, e.g., `Table('my_table', metadata, schema='project_id.dataset_id')` or `engine = create_engine('bigquery://project_id/dataset_id')`.Install with `pip install sqlalchemy-bigquery[bqstorage]`.
Currently, a workaround is necessary, such as defining JSON columns as `String` or `LargeBinary` and handling serialization/deserialization at the application level, or awaiting future dialect updates for native JSON type compilation.
Ensure Application Default Credentials are configured. This typically involves setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file, running `gcloud auth application-default login` for local development, or deploying to a Google Cloud environment where service accounts are automatically available. Consult the Google Cloud documentation on ADC for detailed setup instructions.
Ensure your environment is properly authenticated for Google Cloud. This typically involves setting `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file path, running `gcloud auth application-default login`, or deploying in an environment with managed identities (e.g., GCE, Cloud Run, GKE) where credentials are automatically provided.
pip install sqlalchemy-bigquery
pip install google-cloud-bigquery
Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path, or authenticate via `gcloud auth application-default login`.
Verify the dataset and table names are correct and match BigQuery's case-sensitivity, and ensure the service account or user has BigQuery Data Viewer role or similar permissions.
Use a compatible SQLAlchemy type that maps correctly to BigQuery (e.g., `String` for UUID or ENUM), or implement a custom type with BigQuery-specific compilation rules.