Google Cloud BigQuery Client (async)

Warnings

• gotcha 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.
  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.
• gotcha There can be confusion between `gcloud-aio-*` (asynchronous) and `gcloud-rest-*` (synchronous) client libraries, as they share a codebase and similar naming conventions. Ensure you are importing and using the correct `gcloud.aio.*` modules for asynchronous operations.
  Fix: Always explicitly import from `gcloud.aio.<service_name>` for asyncio-compatible clients and `gcloud.rest.<service_name>` for `requests`-based synchronous clients.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Always specify only the columns you need in your `SELECT` statements. Use `LIMIT` and `WHERE` clauses effectively to reduce data scanned.

Install

• pip install gcloud-aio-bigquery Install `gcloud-aio-bigquery`

Imports

• BigQuery

  from gcloud.aio.bigquery import BigQuery

  The top-level package `gcloud-aio-bigquery` exposes its main client through the `gcloud.aio.bigquery` module path.
• Token

  from gcloud.aio.auth import Token

  Required for asynchronous authentication with Google Cloud services.

Quickstart

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.

import asyncio
import os
import aiohttp
from gcloud.aio.auth import Token
from gcloud.aio.bigquery import BigQuery

async def main():
    # Ensure GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS
    # are set in your environment for authentication.
    project = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id') # Replace with your project ID
    
    async with aiohttp.ClientSession() as session:
        # Obtain Google Cloud credentials token
        token = await Token(session=session).get()
        
        # Initialize BigQuery client
        client = BigQuery(project=project, session=session, token=token)

        query = """
            SELECT name, SUM(number) as total_babies
            FROM `bigquery-public-data.usa_names.usa_1910_2013`
            WHERE state = 'TX'
            GROUP BY name
            ORDER BY total_babies DESC
            LIMIT 5
        """
        
        print(f"Executing query for project: {project}")
        job_id, result = await client.query_and_wait(query)
        
        print(f"Query Job ID: {job_id}")
        print("Top 5 baby names in Texas (1910-2013):")
        
        for row in result['rows']:
            print(f"- {row['name']}: {row['total_babies']}")

if __name__ == "__main__":
    asyncio.run(main())