{"id":7253,"library":"gcloud-rest-bigquery","title":"Google Cloud BigQuery Client (Async)","description":"gcloud-rest-bigquery is an asynchronous Python client for Google Cloud BigQuery, built on top of the gcloud-aio client library. It provides an asyncio-native interface for interacting with BigQuery APIs, leveraging aiohttp for HTTP requests. The library is part of the gcloud-aio monorepo, which sees frequent updates across its various Google Cloud service clients. The current version is 7.1.0.","status":"active","version":"7.1.0","language":"en","source_language":"en","source_url":"https://github.com/talkiq/gcloud-aio","tags":["google cloud","bigquery","async","asyncio","aiohttp","cloud"],"install":[{"cmd":"pip install gcloud-rest-bigquery","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for Google Cloud authentication.","package":"gcloud-aio-auth","optional":false},{"reason":"Core dependency for common gcloud-aio functionality.","package":"gcloud-aio-core","optional":false}],"imports":[{"note":"The library uses 'gcloud_aio_bigquery' as its top-level module name for imports, not 'gcloud_rest_bigquery'.","wrong":"from gcloud_rest_bigquery import BigqueryClient","symbol":"BigqueryClient","correct":"from gcloud_aio_bigquery import BigqueryClient"},{"note":"Authentication utilities are provided by the separate 'gcloud-aio-auth' package.","wrong":"from gcloud_aio_bigquery.auth import build_default_credentials","symbol":"build_default_credentials","correct":"from gcloud_aio_auth import build_default_credentials"}],"quickstart":{"code":"import asyncio\nimport os\nfrom gcloud_aio_auth import build_default_credentials\nfrom gcloud_aio_bigquery import BigqueryClient\n\nasync def main():\n    project_id = os.environ.get(\"GCLOUD_PROJECT\", \"\")\n    if not project_id:\n        print(\"Please set the GCLOUD_PROJECT environment variable.\")\n        return\n\n    # Using default credentials (e.g., from gcloud CLI, service account JSON in GOOGLE_APPLICATION_CREDENTIALS)\n    async with build_default_credentials(\n        scopes=[\"https://www.googleapis.com/auth/cloud-platform\"]\n    ) as credentials:\n        async with BigqueryClient(\n            project=project_id, credentials=credentials\n        ) as client:\n            # Execute a simple query\n            print(f\"Running query in project: {project_id}\")\n            query_job = await client.query(\n                project_id=project_id,\n                query=\"SELECT 1 AS one, 'hello' AS greeting\",\n                use_legacy_sql=False,\n                location=\"US\" # Or your preferred dataset location\n            )\n\n            # Wait for the job to complete and fetch results\n            results = await client.get_job_results(\n                project_id=project_id,\n                job_id=query_job[\"jobReference\"][\"jobId\"],\n                location=query_job[\"jobReference\"][\"location\"]\n            )\n\n            print(\"Query results:\")\n            if results and \"rows\" in results:\n                for row in results[\"rows\"]:\n                    # Each 'f' element corresponds to a column, 'v' is the value\n                    print([col[\"v\"] for col in row[\"f\"]])\n            else:\n                print(\"No rows returned or unexpected result format.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to initialize the BigqueryClient using default Google Cloud credentials (e.g., `gcloud auth application-default login` or `GOOGLE_APPLICATION_CREDENTIALS`), run a simple SQL query, and fetch its results asynchronously. Ensure the `GCLOUD_PROJECT` environment variable is set to your Google Cloud project ID."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer, or pin your `gcloud-aio-auth` dependency to `<5.4.4` in your `requirements.txt`.","message":"`gcloud-aio-auth` (a core dependency) dropped support for Python 3.9 in version 5.4.4. While `gcloud-rest-bigquery` technically supports Python 3.9, installing `gcloud-aio-auth>=5.4.4` will cause issues.","severity":"breaking","affected_versions":"gcloud-aio-auth>=5.4.4 (which affects gcloud-rest-bigquery if installed on Python 3.9)"},{"fix":"Ensure `asyncio.run()` is called only once per thread. Use `async with` for client and credential objects to ensure proper resource cleanup. Always `await` coroutines and `async` functions.","message":"Incorrect `asyncio` event loop management (e.g., calling `asyncio.run()` multiple times in the same thread, or not awaiting coroutines) can lead to `RuntimeError: Event loop is closed` or deadlocks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the BigQuery API documentation for the required scopes for your specific operations (e.g., `https://www.googleapis.com/auth/bigquery`, `https://www.googleapis.com/auth/devstorage.read_only`). Pass these explicitly to `build_default_credentials` or `build_from_service_account_info`.","message":"Default authentication credentials might not include all necessary OAuth 2.0 scopes for every BigQuery API call, leading to `403 Permission denied` errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `asyncio.run()` is called only once per application execution. If you need to run multiple async functions, wrap them in a single `async def main():` and call `asyncio.run(main())`.","cause":"Attempting to run asyncio tasks or access the event loop after it has been explicitly closed, often by calling `asyncio.run()` more than once, or mixing sync and async code improperly.","error":"RuntimeError: Event loop is closed"},{"fix":"Verify your `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to a valid service account JSON file, or ensure `gcloud auth application-default login` has been run and is active. For service accounts, ensure the path to the JSON file is correct.","cause":"Google Cloud authentication failed. This can be due to missing `GOOGLE_APPLICATION_CREDENTIALS` environment variable, an invalid service account key, or `gcloud` not being logged in.","error":"gcloud_aio_auth.exceptions.AuthError: Failed to obtain credentials"},{"fix":"The correct import is `from gcloud_aio_bigquery import BigqueryClient`.","cause":"Incorrect import statement for `BigqueryClient`.","error":"AttributeError: module 'gcloud_aio_bigquery' has no attribute 'BigqueryClient'"},{"fix":"Review the IAM roles assigned to your service account or user in the Google Cloud Console. Ensure they have sufficient permissions (e.g., `BigQuery Data Editor`, `BigQuery User`, etc.). Also, check that the correct OAuth scopes are requested during credential building.","cause":"The authenticated service account or user lacks the necessary IAM permissions or OAuth scopes for the requested BigQuery operation.","error":"google.api_core.exceptions.Forbidden: 403 The caller does not have permission"}]}