Google Cloud BigQuery Reservation

1.23.0 · active · verified Fri Apr 17

The `google-cloud-bigquery-reservation` library provides a Python client for the Google Cloud BigQuery Reservation API. This API allows users to manage BigQuery reservations, which are dedicated slots for running queries. The library is currently at version 1.23.0 and is part of the `google-cloud-python` monorepo, receiving frequent updates, often daily, alongside other Google Cloud client libraries.

Common errors

```
google.api_core.exceptions.PermissionDenied: 403 Permission denied: The caller does not have permission
```
cause The authenticated service account or user lacks the necessary IAM permissions to perform the requested operation on BigQuery Reservations.

fix Grant the appropriate IAM roles (e.g., `BigQuery Resource Admin`, `BigQuery Reservation User`) to the service account or user used for authentication. Verify the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to the correct key file.
```
google.api_core.exceptions.NotFound: 404 Not Found: Requested entity was not found
```
cause The specified project, location, reservation, or assignment ID does not exist, or the authenticated principal does not have permission to view it.

fix Double-check the project ID, location, and the name/ID of the reservation or assignment resource in your API call. Ensure the resource actually exists and is accessible from the specified location.
```
ImportError: cannot import name 'ReservationServiceClient' from 'google.cloud.bigquery_reservation'
```
cause Incorrect import path. Google Cloud client libraries often include API versioning in their module structure.

fix Use the versioned import path: `from google.cloud.bigquery_reservation_v1 import ReservationServiceClient`.

Warnings

gotcha Google Cloud client libraries require appropriate authentication. If `GOOGLE_APPLICATION_CREDENTIALS` isn't set or `gcloud auth application-default login` hasn't been run, operations will fail with permission errors.
Fix: Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file, or authenticate via `gcloud auth application-default login` for local development. Ensure the principal has `BigQuery Resource Admin` or equivalent IAM roles for reservation management.
breaking Python version support changes across the `google-cloud-python` ecosystem. While `google-cloud-bigquery-reservation==1.23.0` requires Python `>=3.9`, other related libraries may drop support for older Python versions (e.g., Python 3.9) in recent releases.
Fix: Always check the `requires_python` metadata on PyPI for the specific version of `google-cloud-bigquery-reservation` you intend to use. Upgrade to a supported Python version (e.g., 3.10 or newer) to ensure compatibility across all Google Cloud libraries.
gotcha The BigQuery Reservation API is regional. Resources like reservations and assignment must be created and accessed within a specific location. Attempting to access a reservation from the wrong location will result in 'Not Found' errors.
Fix: Always specify the correct region (e.g., `us-central1`, `eu-west1`) when listing, creating, or managing BigQuery reservation resources. Ensure the `parent` path in your API calls accurately reflects the resource's location.

Install

pip install google-cloud-bigquery-reservation Install latest version

Imports

ReservationServiceClient
wrong:
```
from google.cloud.bigquery_reservation import ReservationServiceClient
```
correct:
```
from google.cloud.bigquery_reservation_v1 import ReservationServiceClient
```
Google Cloud client libraries are often versioned (e.g., `_v1`) to distinguish different API versions. Omitting the version suffix will lead to an ImportError.

Quickstart

This quickstart demonstrates how to instantiate the `ReservationServiceClient` and list existing BigQuery reservations within a specified Google Cloud project and location. Ensure your `GOOGLE_APPLICATION_CREDENTIALS` are set or you are authenticated via `gcloud` and have the necessary IAM permissions (e.g., `bigquery.reservations.list`).

import os
from google.cloud.bigquery_reservation_v1 import ReservationServiceClient

# Instantiate a client. The client will automatically pick up credentials
# from GOOGLE_APPLICATION_CREDENTIALS environment variable or gcloud CLI.
client = ReservationServiceClient()

# Replace with your actual GCP project ID
# You can also set this as an environment variable: export GCP_PROJECT_ID='your-project-id'
project_id = os.environ.get("GCP_PROJECT_ID", "your-project-id")
location = "us-central1" # Example location
parent = f"projects/{project_id}/locations/{location}"

print(f"Attempting to list reservations in {parent}...")

try:
    # List reservations for a given project and location
    reservations = client.list_reservations(parent=parent)
    
    found_reservations = False
    for reservation in reservations:
        print(f"- Reservation found: {reservation.name} (Slots: {reservation.slot_capacity})")
        found_reservations = True
    
    if not found_reservations:
        print("No reservations found. You might need to create one first.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure you have correct project ID, location, and permissions.")

view raw JSON →