Registry / gcp / google-cloud-bigquery

google-cloud-bigquery

library3.40.1pypypi✓ verified 50d ago

Official Python client for Google BigQuery. Current version: 3.40.1 (Mar 2026). v3.0 made google-cloud-bigquery-storage and pyarrow required dependencies. Authentication uses Application Default Credentials (ADC) — no explicit API key. query() returns a QueryJob — must call .result() to wait for completion. to_dataframe() dtype behavior changed in v3 (nullable pandas dtypes). Python 3.9+ required as of v3.x.

gcp database data serialization

pip install google-cloud-bigquery

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v3.41.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.975 runs

installs and imports cleanly · install 0.0s · import 2.668s · 72.5MB

glibc

py 3.10–3.975 runs

installs and imports cleanly · install 12.1s · import 2.200s · 70MB

71MB installed

● package 71MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bigquery

✓ import google.cloud.bigquery

✗ from google.cloud import bigquery

BigQuery Python client — query and to_dataframe with ADC auth.

# pip install 'google-cloud-bigquery[pandas]' # Set up ADC: gcloud auth application-default login # or set GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json from google.cloud import bigquery client = bigquery.Client(project='my-gcp-project') # Query public dataset query = """ SELECT name, SUM(number) as total FROM `bigquery-public-data.usa_names.usa_1910_2013` WHERE state = 'CA' GROUP BY name ORDER BY total DESC LIMIT 5 """ # Run query and wait for results query_job = client.query(query) rows = query_job.result() # blocks until done for row in rows: print(f'{row.name}: {row.total}') # As DataFrame df = rows.to_dataframe() print(df.head())

Debug

Known issues

breakinggoogle-cloud-bigquery-storage and pyarrow are now required dependencies in v3.x (previously optional). Installing v3 without them causes ImportError on to_dataframe().

fix

pip install 'google-cloud-bigquery[pandas]' — installs all required deps including db-dtypes.

affects: >= 3.0

breakingto_dataframe() dtype mappings changed in v3. INT64 → Int64 (nullable), BOOLEAN → boolean (nullable), DATE → dbdate. Code checking dtype == 'int64' or 'bool' will fail silently or raise.

fix

Use pandas nullable dtypes in comparisons: df['col'].dtype == 'Int64' not 'int64'. Or use pd.api.types.is_integer_dtype().

affects: >= 3.0

gotchaclient.query() returns a QueryJob — NOT results. It starts the job asynchronously. Must call .result() to block and wait for completion before iterating rows.

fix

rows = client.query(sql).result() — the .result() call is mandatory.

affects: all

gotchaAuthentication uses Application Default Credentials (ADC) — no API key. Locally: run 'gcloud auth application-default login'. In production: use service account key or Workload Identity. Missing credentials raises DefaultCredentialsError.

fix

Local: gcloud auth application-default login. Production: set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json or use Workload Identity.

affects: all

gotchaBigQuery table references use backtick syntax in SQL: `project.dataset.table`. Using regular quotes raises BadRequest syntax error.

fix

SELECT * FROM `myproject.mydataset.mytable` — backticks required for fully qualified table names.

affects: all

gotchaStandardSqlDataType and related types moved from google.cloud.bigquery_v2 to google.cloud.bigquery in v3. Old imports raise ImportError.

fix

from google.cloud.bigquery import StandardSqlDataType — not from google.cloud.bigquery_v2

affects: >= 3.0

gotchaPython 3.7 and 3.8 support dropped in v3.x. New major version in Q4 2024 dropped these Python versions.

fix

Use Python 3.9+

affects: >= 3.0

Upgrade

Version history

3.41.0latest on PyPI

Audit

Dependencies

google-cloud-bigquery-storagerequiredRequired in v3.x (previously optional). Installed automatically.

pyarrowrequiredRequired in v3.x (previously optional). Needed for to_dataframe() and Arrow-based result reading.

db-dtypesoptionalRequired for pandas extra — maps BigQuery types to pandas nullable dtypes.

Agent activity

98 hits · last 30 days

node

ahrefsbot

Amazon

seranking-bot