{"id":175,"library":"google-cloud-bigquery","title":"Google Cloud BigQuery","description":"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.","status":"active","version":"3.40.1","language":"python","source_language":"en","source_url":"https://github.com/googleapis/python-bigquery","tags":["bigquery","google-cloud","python","data","sql","analytics"],"install":[{"cmd":"pip install google-cloud-bigquery","lang":"bash","label":"Python (core)"},{"cmd":"pip install 'google-cloud-bigquery[pandas]'","lang":"bash","label":"Python (with pandas/to_dataframe support)"},{"cmd":"pip install 'google-cloud-bigquery[pandas,pyarrow]'","lang":"bash","label":"Python (with pandas + pyarrow — recommended)"}],"dependencies":[{"reason":"Required in v3.x (previously optional). Installed automatically.","package":"google-cloud-bigquery-storage","optional":false},{"reason":"Required in v3.x (previously optional). Needed for to_dataframe() and Arrow-based result reading.","package":"pyarrow","optional":false},{"reason":"Required for pandas extra — maps BigQuery types to pandas nullable dtypes.","package":"db-dtypes","optional":true}],"imports":[{"note":"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.","wrong":"from google.cloud import bigquery\n\nclient = bigquery.Client()\n# Wrong: using query result directly without .result()\nrows = client.query('SELECT 1')  # returns QueryJob not rows\nfor row in rows:  # iterates before job completes\n    print(row)","symbol":"Client (basic query)","correct":"from google.cloud import bigquery\n\n# ADC auth — uses GOOGLE_APPLICATION_CREDENTIALS env var\n# or gcloud CLI credentials locally\nclient = bigquery.Client(project='my-project')\n\n# query() returns a QueryJob — NOT results\nquery = \"\"\"\n    SELECT name, COUNT(*) as count\n    FROM `bigquery-public-data.usa_names.usa_1910_2013`\n    WHERE state = 'TX'\n    GROUP BY name\n    ORDER BY count DESC\n    LIMIT 10\n\"\"\"\nquery_job = client.query(query)  # starts job\nrows = query_job.result()       # BLOCKS until complete\n\nfor row in rows:\n    print(row.name, row.count)"},{"note":"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.","wrong":"# Expecting non-nullable pandas dtypes from to_dataframe\ndf = client.query('SELECT count FROM table').result().to_dataframe()\nassert df['count'].dtype == 'int64'  # fails in v3 — now Int64 (nullable)","symbol":"to_dataframe","correct":"from google.cloud import bigquery\n\nclient = bigquery.Client(project='my-project')\nquery = 'SELECT id, name, created_at FROM `myproject.mydataset.mytable` LIMIT 100'\n\n# to_dataframe() requires pandas + pyarrow + db-dtypes\ndf = client.query(query).result().to_dataframe()\nprint(df.dtypes)\n# id: Int64 (nullable) — not int64\n# name: object\n# created_at: dbdate"}],"quickstart":{"code":"# pip install 'google-cloud-bigquery[pandas]'\n# Set up ADC: gcloud auth application-default login\n# or set GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json\n\nfrom google.cloud import bigquery\n\nclient = bigquery.Client(project='my-gcp-project')\n\n# Query public dataset\nquery = \"\"\"\n    SELECT\n        name,\n        SUM(number) as total\n    FROM `bigquery-public-data.usa_names.usa_1910_2013`\n    WHERE state = 'CA'\n    GROUP BY name\n    ORDER BY total DESC\n    LIMIT 5\n\"\"\"\n\n# Run query and wait for results\nquery_job = client.query(query)\nrows = query_job.result()  # blocks until done\n\nfor row in rows:\n    print(f'{row.name}: {row.total}')\n\n# As DataFrame\ndf = rows.to_dataframe()\nprint(df.head())","lang":"python","description":"BigQuery Python client — query and to_dataframe with ADC auth."},"warnings":[{"fix":"pip install 'google-cloud-bigquery[pandas]' — installs all required deps including db-dtypes.","message":"google-cloud-bigquery-storage and pyarrow are now required dependencies in v3.x (previously optional). Installing v3 without them causes ImportError on to_dataframe().","severity":"breaking","affected_versions":">= 3.0"},{"fix":"Use pandas nullable dtypes in comparisons: df['col'].dtype == 'Int64' not 'int64'. Or use pd.api.types.is_integer_dtype().","message":"to_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.","severity":"breaking","affected_versions":">= 3.0"},{"fix":"rows = client.query(sql).result() — the .result() call is mandatory.","message":"client.query() returns a QueryJob — NOT results. It starts the job asynchronously. Must call .result() to block and wait for completion before iterating rows.","severity":"gotcha","affected_versions":"all"},{"fix":"Local: gcloud auth application-default login. Production: set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json or use Workload Identity.","message":"Authentication 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.","severity":"gotcha","affected_versions":"all"},{"fix":"SELECT * FROM `myproject.mydataset.mytable` — backticks required for fully qualified table names.","message":"BigQuery table references use backtick syntax in SQL: `project.dataset.table`. Using regular quotes raises BadRequest syntax error.","severity":"gotcha","affected_versions":"all"},{"fix":"from google.cloud.bigquery import StandardSqlDataType — not from google.cloud.bigquery_v2","message":"StandardSqlDataType and related types moved from google.cloud.bigquery_v2 to google.cloud.bigquery in v3. Old imports raise ImportError.","severity":"gotcha","affected_versions":">= 3.0"},{"fix":"Use Python 3.9+","message":"Python 3.7 and 3.8 support dropped in v3.x. New major version in Q4 2024 dropped these Python versions.","severity":"gotcha","affected_versions":">= 3.0"}],"env_vars":null,"last_verified":"2026-05-12T09:42:22.114Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed using pip: `pip install google-cloud-bigquery`","cause":"The `google-cloud-bigquery` Python package is not installed in the active environment or is not accessible on the Python path.","error":"ModuleNotFoundError: No module named 'google.cloud.bigquery'"},{"fix":"Authenticate by running `gcloud auth application-default login` in your terminal, or by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key JSON file.","cause":"The client library could not find valid Google Cloud credentials in the environment. This typically means Application Default Credentials (ADC) are not set up.","error":"google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials."},{"fix":"Verify that the `project` argument in `bigquery.Client(project='your-project-id')` is exactly the correct Google Cloud Project ID, and ensure your authenticated account or service account has the necessary BigQuery permissions for that project.","cause":"The specified Google Cloud project ID is incorrect, misspelled, or the authenticated principal lacks permissions to access it.","error":"google.api_core.exceptions.BadRequest: 400 GET ... Invalid project ID '`your-project-id`'."},{"fix":"Call `.result()` on the `QueryJob` first to get the results iterator, then call `.to_dataframe()` on that iterator. Also, ensure `google-cloud-bigquery-storage` and `pyarrow` are installed: `pip install google-cloud-bigquery-storage pyarrow`.\n\n`client = bigquery.Client()`\n`query_job = client.query(\"SELECT 1\")`\n`df = query_job.result().to_dataframe()`","cause":"The `to_dataframe()` method is called directly on the `QueryJob` object. The `to_dataframe()` method is available on the `QueryJob.result()` object (which is a `RowIterator`), and requires `google-cloud-bigquery-storage` and `pyarrow` to be installed.","error":"AttributeError: 'QueryJob' object has no attribute 'to_dataframe'"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.58,"mem_mb":50.9,"disk_size":"390.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.6,"mem_mb":50.9,"disk_size":"390.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":22.9,"disk_size":"71.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.77,"mem_mb":49.6,"disk_size":"357M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.79,"mem_mb":49.6,"disk_size":"357M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.86,"mem_mb":21.6,"disk_size":"69M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.81,"mem_mb":57.4,"disk_size":"417.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.83,"mem_mb":57.4,"disk_size":"417.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.18,"mem_mb":25.4,"disk_size":"76.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.79,"mem_mb":56.2,"disk_size":"383M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.79,"mem_mb":56.2,"disk_size":"383M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.42,"mem_mb":24.2,"disk_size":"74M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.75,"mem_mb":56.3,"disk_size":"410.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.82,"mem_mb":56.3,"disk_size":"410.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.06,"mem_mb":25.2,"disk_size":"67.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.41,"mem_mb":55.1,"disk_size":"376M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.42,"mem_mb":55.1,"disk_size":"376M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.72,"mem_mb":24,"disk_size":"65M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.59,"mem_mb":56.5,"disk_size":"409.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.64,"mem_mb":56.5,"disk_size":"409.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.06,"mem_mb":25.8,"disk_size":"67.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.35,"mem_mb":55.3,"disk_size":"375M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.27,"mem_mb":55.3,"disk_size":"375M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.72,"mem_mb":24.6,"disk_size":"65M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.38,"mem_mb":51.5,"disk_size":"385.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.39,"mem_mb":51.5,"disk_size":"385.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.24,"mem_mb":23.1,"disk_size":"71.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pandas,pyarrow","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.12,"mem_mb":50.3,"disk_size":"359M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pandas","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.08,"mem_mb":50.3,"disk_size":"359M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.02,"mem_mb":21.8,"disk_size":"69M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}