Google Cloud BigQuery

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• Client (basic query)
  wrong

  from google.cloud import bigquery
  
  client = bigquery.Client()
  # Wrong: using query result directly without .result()
  rows = client.query('SELECT 1')  # returns QueryJob not rows
  for row in rows:  # iterates before job completes
      print(row)

  correct

  from google.cloud import bigquery
  
  # ADC auth — uses GOOGLE_APPLICATION_CREDENTIALS env var
  # or gcloud CLI credentials locally
  client = bigquery.Client(project='my-project')
  
  # query() returns a QueryJob — NOT results
  query = """
      SELECT name, COUNT(*) as count
      FROM `bigquery-public-data.usa_names.usa_1910_2013`
      WHERE state = 'TX'
      GROUP BY name
      ORDER BY count DESC
      LIMIT 10
  """
  query_job = client.query(query)  # starts job
  rows = query_job.result()       # BLOCKS until complete
  
  for row in rows:
      print(row.name, row.count)

  client.query() returns a QueryJob object — not results. Must call .result() to block and get rows. Iterating over QueryJob directly may work but is not guaranteed to be complete.

• to_dataframe
  wrong

  # Expecting non-nullable pandas dtypes from to_dataframe
  df = client.query('SELECT count FROM table').result().to_dataframe()
  assert df['count'].dtype == 'int64'  # fails in v3 — now Int64 (nullable)

  correct

  from google.cloud import bigquery
  
  client = bigquery.Client(project='my-project')
  query = 'SELECT id, name, created_at FROM `myproject.mydataset.mytable` LIMIT 100'
  
  # to_dataframe() requires pandas + pyarrow + db-dtypes
  df = client.query(query).result().to_dataframe()
  print(df.dtypes)
  # id: Int64 (nullable) — not int64
  # name: object
  # created_at: dbdate

  v3 changed to_dataframe() dtypes. INT64 now maps to pandas Int64 (nullable), BOOLEAN to boolean (nullable), DATE to dbdate. Code checking dtype == 'int64' or 'bool' will fail.

Quickstart stale last tested: 2026-04-23

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())