Work with legacy slot reservations

The BigQuery Reservation API lets you purchase dedicated slots (called commitments), create pools of slots (called reservations), and assign projects, folders, and organizations to those reservations.

Reservations allow you to assign a dedicated number of slots to a workload. For example, you might not want a production workload to compete with test workloads for slots. You could create a reservation named prod and assign your production workloads to this reservation. For more information, see Reservations.

Create reservations

Required permissions

To create a reservation, you need the following Identity and Access Management (IAM) permission:

bigquery.reservations.create on the administration project that maintains ownership of the commitments.

Each of the following predefined IAM roles includes this permission:

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

For more information about IAM roles in BigQuery, see Predefined roles and permissions.

Create a reservation with dedicated slots

Select one of the following options:

Console

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the navigation panel, go to the Capacity management section.
Click Create reservation.
In the Reservation name field, enter a name for the reservation.
In the Location drop-down list, select the location.
In the Capacity Model section, select the capacity model.
If you select the Flat-Rate option, under Baseline slots, enter the number of slots for the reservation.
1. In the Max reservation size selector list, select the maximum reservation size.
2. Optional: In the Baseline slots field, enter the number of baseline slots for the reservation. To use only the specified slot capacity, click the Ignore idle slots toggle.
  
  The amount of autoscaling slots available to you is determined by subtracting the baseline slots value from the maximum reservation size value. For example, if you create a reservation with 100 baseline slots and a max reservation size of 400, your reservation has 300 autoscaling slots. For more information about baseline slots, see Using reservations with baseline and autoscaling slots.
To disable idle slot sharing, click the Ignore idle slots toggle.
The breakdown of slots is displayed in the Cost estimate table. A summary of the reservation is displayed in the Capacity summary table.
Click Save.

The new reservation is visible in the Reservations tab.

SQL

To create a reservation, use the CREATE RESERVATION DDL statement.

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the query editor, enter the following statement:
```
CREATE RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
OPTIONS (
  slot_capacity = NUMBER_OF_SLOTS,
);
```
Replace the following:
- ADMIN_PROJECT_ID: the project ID of the administration project that owns the reservation resource
- LOCATION: the location of the reservation. If you select a BigQuery Omni location, your edition option is limited to Enterprise edition.
- RESERVATION_NAME: the name of the reservation
  
  It must start and end with a lowercase letter or a number and contain only lowercase letters, numbers, and dashes.
- NUMBER_OF_SLOTS: the number of slots to allocate to the reservation. There must be enough unallocated slots in the commitment. You cannot set the slot_capacity option and the edition option in the same reservation.
- EDITION: the edition of the reservation. Assigning a reservation to an edition comes with feature and pricing changes. For more information, see Introduction to BigQuery editions.
- NUMBER_OF_AUTOSCALING_SLOTS: the number of autoscaling slots assigned to the reservation. Only available when the edition option is specified.
Click Run.

For more information about how to run queries, see Run an interactive query.

bq

To create a reservation, use the bq mk command with the --reservation flag:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation \
    --slots=NUMBER_OF_SLOTS \
    --ignore_idle_slots=false \
    RESERVATION_NAME

Replace the following:

ADMIN_PROJECT_ID: the project ID
LOCATION: the location of the reservation. If you select a BigQuery Omni location, your edition option is limited to Enterprise edition.
NUMBER_OF_SLOTS: the number of slots to allocate to the reservation

There must be enough unallocated slots in the commitment.
RESERVATION_NAME: the name of the reservation
EDITION: the edition of the reservation. Assigning a reservation to an edition comes with feature and pricing changes. For more information, see Introduction to BigQuery editions.
NUMBER_OF_AUTOSCALING_SLOTS: the number of autoscaling slots assigned to the reservation. Only available when the edition option is specified.

For information about the --ignore_idle_slots flag, see Idle slots. The default value is false.

Python

Install the google-cloud-bigquery-reservation package before using this code sample. Construct a ReservationServiceClient. Describe the reservation you'd like to create with a Reservation. Create the reservation with the create_reservation method.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the number of slots in the
# reservation.
slot_capacity = 100

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)

parent = reservation_client.common_location_path(project_id, location)

reservation = reservation_types.Reservation(slot_capacity=slot_capacity)
reservation = reservation_client.create_reservation(
    parent=parent,
    reservation=reservation,
    reservation_id=reservation_id,
)

print(f"Created reservation: {reservation.name}")

Update reservations

You can make the following updates to a reservation:

Change the reservation size by adding or removing slots.
Configure whether queries in this reservation use idle slots.
Change the amount of baseline or autoscaling slots allocated to a reservation.

Required permissions

To update a reservation, you need the following Identity and Access Management (IAM) permission:

bigquery.reservations.update on the administration project that maintains ownership of the commitments.

Each of the following predefined IAM roles includes this permission:

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

For more information about IAM roles in BigQuery, see Predefined roles and permissions.

Change the size of a reservation

You can add or remove slots from an existing reservation.

Console

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the navigation panel, go to the Capacity Management section.
Click the Reservations tab.
Find the reservation you want to update.
Expand the Actions option.
Click Edit.
In the Max reservation size selector dialog, enter the max reservation size.
In the Baseline slots field, enter the number of baseline slots.
Click Save.

SQL

To change the size of a reservation, use the ALTER RESERVATION SET OPTIONS data definition language (DDL) statement.

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the query editor, enter the following statement:
```
ALTER RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`
SET OPTIONS (
  slot_capacity = NUMBER_OF_SLOTS,
);
```
Replace the following:
- ADMIN_PROJECT_ID: the project ID of the administration project that owns the reservation resource
- LOCATION: the location of the reservation, for example europe-west9.
- RESERVATION_NAME: the name of the reservation. It must start and end with a lowercase letter or a number and contain only lowercase letters, numbers, and dashes.
- NUMBER_OF_SLOTS: the number of slots to allocate to the reservation.
Click Run.

For more information about how to run queries, see Run an interactive query.

bq

To update the size of a reservation, use the bq update command with the --reservation flag:

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --slots=NUMBER_OF_SLOTS \
    --reservation RESERVATION_NAME

Replace the following:

ADMIN_PROJECT_ID: the project ID
LOCATION: the location of the reservation
NUMBER_OF_SLOTS: the number of slots to allocate to the reservation
RESERVATION_NAME: the name of the reservation

Python

Install the google-cloud-bigquery-reservation package before using this code sample. Construct a ReservationServiceClient. Describe the updated properties with a Reservation and the FieldMask.paths property. Update the reservation with the update_reservation method.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Set slot_capicity to the new number of slots in the
# reservation.
slot_capacity = 50

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service
from google.cloud.bigquery_reservation_v1.types import (
    reservation as reservation_types,
)
from google.protobuf import field_mask_pb2

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)

reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation = reservation_types.Reservation(
    name=reservation_name,
    slot_capacity=slot_capacity,
)
field_mask = field_mask_pb2.FieldMask(paths=["slot_capacity"])
reservation = reservation_client.update_reservation(
    reservation=reservation, update_mask=field_mask
)

print(f"Updated reservation: {reservation.name}")
print(f"\tslot_capacity: {reservation.slot_capacity}")

Configure whether queries use idle slots

The --ignore_idle_slots flag controls whether queries running in a reservation can use idle slots from other reservations. For more information, see Idle slots. You can update this configuration on an existing reservation.

To update a reservation, use the bq update command with the --reservation flag . The following example sets --ignore_idle_slots to true, meaning the reservation will only use slots allocated to the reservation.

bq update \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --ignore_idle_slots=true \
    --reservation RESERVATION_NAME

Replace the following:

ADMIN_PROJECT_ID: the project ID
LOCATION: the location of the reservation
RESERVATION_NAME: the name of the reservation

List the idle slot configuration

To list the idle slots setting for a reservation, do the following:

SQL

Query the ignore_idle_slots column of the INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT view.

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the query editor, enter the following statement:
```
SELECT
  reservation_name,
  ignore_idle_slots
FROM
  `ADMIN_PROJECT_ID.region-LOCATION`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT;
```
Replace the following:
- ADMIN_PROJECT_ID: the project ID of the administration project that owns the reservation resources
- LOCATION: the location of the reservations
Click Run.

For more information about how to run queries, see Run an interactive query.

bq

Use the bq ls command with the --reservation flag:

bq ls --reservation \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION

Replace the following:

ADMIN_PROJECT_ID: the project ID of the administration project that owns the reservation resources
LOCATION: the location of the reservations

The ignoreIdleSlots field contains the configuration setting.

Delete reservations

When you delete a reservation, any jobs that are currently executing with slots from that reservation will fail. To prevent errors, allow running jobs to complete before deleting the reservation.

Required permissions

To delete a reservation, you need the following Identity and Access Management (IAM) permission:

bigquery.reservations.delete on the administration project that maintains ownership of the commitments.

Each of the following predefined IAM roles includes this permission:

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor

For more information about IAM roles in BigQuery, see Predefined roles and permissions.

Delete a reservation

Console

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the navigation panel, go to the Capacity Management section.
Click the Reservations tab.
Find the reservation you want to delete.
Expand the Actions option.
Click Delete.
In the Delete reservation dialog, click Delete.

SQL

To delete a reservation, use the DROP RESERVATION DDL statement.

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the query editor, enter the following statement:
```
DROP RESERVATION
  `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`;
```
Replace the following:
- ADMIN_PROJECT_ID: the project ID of the administration project that owns the reservation resource
- LOCATION: the location of the reservation
- RESERVATION_NAME: the ID of the reservation
Click Run.

For more information about how to run queries, see Run an interactive query.

bq

To delete a reservation, use the bq rm command with the --reservation flag:

bq rm \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation RESERVATION_NAME

Replace the following:

ADMIN_PROJECT_ID: the project ID of the administration project that owns the reservation resource
LOCATION: the location of the reservation
RESERVATION_NAME: the name of the reservation

Python

Install the google-cloud-bigquery-reservation package before using this code sample. Construct a ReservationServiceClient. Delete the reservation with the delete_reservation method.

# TODO(developer): Set project_id to the project ID containing the
# reservation.
project_id = "your-project-id"

# TODO(developer): Set location to the location of the reservation.
# See: https://cloud.google.com/bigquery/docs/locations for a list of
# available locations.
location = "US"

# TODO(developer): Set reservation_id to a unique ID of the reservation.
reservation_id = "sample-reservation"

# TODO(developer): Choose a transport to use. Either 'grpc' or 'rest'
transport = "grpc"

# ...

from google.cloud.bigquery_reservation_v1.services import reservation_service

reservation_client = reservation_service.ReservationServiceClient(
    transport=transport
)
reservation_name = reservation_client.reservation_path(
    project_id, location, reservation_id
)
reservation_client.delete_reservation(name=reservation_name)

print(f"Deleted reservation: {reservation_name}")

Add BigQuery Reservation API to VPC Service Controls

The BigQuery Reservation API supports VPC Service Controls. To integrate the BigQuery Reservation API with VPC Service Controls, follow the instructions in Create a service perimeter, and add the BigQuery Reservation API to the protected services.

A service perimeter protects access to reservations, commitments, and assignments within administration projects that are specified in the perimeter. When creating an assignment, the VPC Service Controls protects the administration project and assignee project, folder, and organization.