{"id":1065,"library":"gcloud-aio-bigquery","title":"Google Cloud BigQuery Client (async)","description":"gcloud-aio-bigquery is an asynchronous Python client for Google Cloud BigQuery, built on `asyncio` and `aiohttp`. It's part of the `gcloud-aio-*` family, providing an asynchronous HTTP implementation of Google Cloud client libraries. The current version is 7.1.0 and it maintains an active release cadence.","status":"active","version":"7.1.0","language":"python","source_language":"en","source_url":"https://github.com/talkiq/gcloud-aio","tags":["google cloud","bigquery","async","aiohttp","gcp"],"install":[{"cmd":"pip install gcloud-aio-bigquery","lang":"bash","label":"Install `gcloud-aio-bigquery`"}],"dependencies":[{"reason":"Core HTTP client library for asynchronous operations.","package":"aiohttp"},{"reason":"Provides asynchronous authentication mechanisms for Google Cloud services.","package":"gcloud-aio-auth"}],"imports":[{"note":"The top-level package `gcloud-aio-bigquery` exposes its main client through the `gcloud.aio.bigquery` module path.","wrong":"from gcloud_aio_bigquery import BigQuery","symbol":"BigQuery","correct":"from gcloud.aio.bigquery import BigQuery"},{"note":"Required for asynchronous authentication with Google Cloud services.","symbol":"Token","correct":"from gcloud.aio.auth import Token"}],"quickstart":{"code":"import asyncio\nimport os\nimport aiohttp\nfrom gcloud.aio.auth import Token\nfrom gcloud.aio.bigquery import BigQuery\n\nasync def main():\n    # Ensure GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS\n    # are set in your environment for authentication.\n    project = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id') # Replace with your project ID\n    \n    async with aiohttp.ClientSession() as session:\n        # Obtain Google Cloud credentials token\n        token = await Token(session=session).get()\n        \n        # Initialize BigQuery client\n        client = BigQuery(project=project, session=session, token=token)\n\n        query = \"\"\"\n            SELECT name, SUM(number) as total_babies\n            FROM `bigquery-public-data.usa_names.usa_1910_2013`\n            WHERE state = 'TX'\n            GROUP BY name\n            ORDER BY total_babies DESC\n            LIMIT 5\n        \"\"\"\n        \n        print(f\"Executing query for project: {project}\")\n        job_id, result = await client.query_and_wait(query)\n        \n        print(f\"Query Job ID: {job_id}\")\n        print(\"Top 5 baby names in Texas (1910-2013):\")\n        \n        for row in result['rows']:\n            print(f\"- {row['name']}: {row['total_babies']}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to initialize the `BigQuery` client, authenticate using `gcloud-aio-auth`, and execute a simple SQL query against a public BigQuery dataset. Ensure your `GOOGLE_CLOUD_PROJECT` environment variable is set to your Google Cloud project ID, and `GOOGLE_APPLICATION_CREDENTIALS` points to your service account key file for local execution."},"warnings":[{"fix":"Use BigQuery DML statements (e.g., `DELETE FROM ... WHERE ...`) via the client's query method, or consider using the synchronous `google-cloud-bigquery` client for direct `delete` API calls if available there.","message":"The `gcloud-aio-bigquery` library currently does not support deleting rows from a table via its API. Users requiring this functionality may need to use alternative methods like the standard `google-cloud-bigquery` library or BigQuery's DML statements directly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always explicitly import from the correct full path for the client class. For `gcloud-aio-*` clients, this often means `from gcloud.aio.<service_name>.<service_name> import <ClientClassName>` (e.g., `from gcloud.aio.bigquery.bigquery import BigqueryClient`), and for `gcloud-rest-*` clients, `from gcloud.rest.<service_name> import <ClientClassName>`. Consult the specific library's documentation or source code for exact import paths.","message":"There can be confusion between `gcloud-aio-*` (asynchronous) and `gcloud-rest-*` (synchronous) client libraries, as they share a codebase and similar naming conventions. Additionally, the main client classes within `gcloud.aio.<service_name>` modules may not be directly exposed at the top level of the service module (e.g., `gcloud.aio.bigquery`), requiring deeper imports.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When dealing with nullable fields, especially integers, implement robust error handling or explicitly cast/check for `None` values before processing. Consider inspecting the raw `result` structure before using helper functions if this issue occurs.","message":"The `query_response_to_dict` utility may raise exceptions when processing nullable integer fields that contain `None` values. This can lead to data parsing errors for queries returning sparse data.","severity":"gotcha","affected_versions":"Prior to 7.1.0, potentially still present"},{"fix":"Always specify only the columns you need in your `SELECT` statements. Use `LIMIT` and `WHERE` clauses effectively to reduce data scanned.","message":"Overusing `SELECT *` in BigQuery queries can significantly increase query costs and execution time, as BigQuery charges based on the amount of data scanned. This is a fundamental BigQuery best practice that applies to `gcloud-aio-bigquery` as well.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the exact class name and import path for the BigQuery client. Common patterns for `gcloud-aio` libraries include importing `Client` (e.g., `from gcloud.aio.bigquery import Client`) or `BigqueryClient` from a submodule (e.g., `from gcloud.aio.bigquery.client import BigqueryClient`). Refer to the library's documentation for the correct import statement.","message":"The `BigQuery` client class cannot be imported directly using `from gcloud.aio.bigquery import BigQuery`. The primary client class might be named differently (e.g., `Client` or `BigqueryClient`) or reside in a deeper submodule within `gcloud.aio.bigquery`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T23:26:12.605Z","next_check":"2026-06-30T00:00:00.000Z","problems":[{"fix":"pip install gcloud-aio-bigquery","cause":"The 'gcloud-aio-bigquery' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'gcloud-aio-bigquery'"},{"fix":"pip install google-cloud-bigquery","cause":"The 'google-cloud-bigquery' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'google.cloud'"},{"fix":"from gcloud.aio.bigquery import BigQueryClient","cause":"Incorrect import statement; 'BigQuery' is not a valid import from 'gcloud.aio.bigquery'.","error":"ImportError: cannot import name 'BigQuery' from 'gcloud.aio.bigquery'"},{"fix":"Install the library using pip: `pip install gcloud-aio-bigquery`","cause":"The 'gcloud-aio-bigquery' library is not installed in your Python environment or is not accessible in your current Python path.","error":"ModuleNotFoundError: No module named 'gcloud.aio.bigquery'"},{"fix":"A possible workaround is to obtain an access token using Google's official `google-auth` library and then pass this token manually to the `gcloud-aio-bigquery` client.","cause":"This error occurs when using Workload Identity Federation (WIF) credentials, as the `gcloud-aio-auth` library (a dependency of `gcloud-aio-bigquery`) does not yet natively support the 'external_account' credential type.","error":"ValueError: 'external_account' is not a valid Type"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"7.1.0","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","installed_version":"7.1.0","pypi_latest":"7.1.0","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"60.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.3,"import_time_s":null,"mem_mb":null,"disk_size":"62M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"68.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":5.1,"import_time_s":null,"mem_mb":null,"disk_size":"71M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"62.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.5,"import_time_s":null,"mem_mb":null,"disk_size":"65M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"62.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.6,"import_time_s":null,"mem_mb":null,"disk_size":"64M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"45.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.9,"import_time_s":null,"mem_mb":null,"disk_size":"48M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gcloud-aio-bigquery","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"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}]}}