Work with legacy slot reservations

Note: Legacy reservations, including access to flat-rate billing or certain commitment lengths, are only available to allow-listed customers. To determine if you have access to these legacy features, contact your administrator. The flat-rate billing model defines how you are billed for compute, but flat-rate reservations and commitments function as Enterprise edition slots.

The BigQuery Reservation API lets you purchase dedicated slots (calledcommitments), create poolsof slots (calledreservations),and assign projects, folders, and organizations to those reservations.

Reservations allow you to assign a dedicated number of slotsto a workload. For example, you might not wanta production workload to compete with test workloads for slots. You couldcreate a reservation namedprod and assign your production workloads to thisreservation. For more information, seeReservations.

Create reservations

Required permissions

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

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

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

Create a reservation with dedicated slots

Select one of the following options:

Console

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

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. ClickCreate reservation.

  4. In theReservation name field, enter a name for the reservation.

  5. In theLocation drop-down list, select the location.

  6. In theCapacity Model section, select the capacity model.

  7. If you select theFlat-Rate option, underBaseline slots, enterthe number of slots for the reservation.

    1. In theMax reservation size selector list, select the maximum reservation size.

    2. Optional: In theBaseline slots field, enter the number of baselineslots for the reservation. To use only the specified slot capacity,click theIgnore idle slots toggle.

      The amount of autoscaling slots available to you is determined bysubtracting the baseline slots value from the maximum reservationsize value. For example, if you create a reservation with 100 baselineslots and a max reservation size of 400, your reservation has 300autoscaling slots. For more information about baseline slots, seeUsing reservations with baseline and autoscalingslots.

  8. To disableidle slot sharing, click theIgnore idle slots toggle.

  9. The breakdown of slots is displayed in theCost estimate table.A summary of the reservation is displayed in theCapacity summary table.

  10. ClickSave.

The new reservation is visible in theReservations tab.

SQL

To create a reservation, use theCREATE RESERVATION DDL statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    CREATERESERVATION`ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`OPTIONS(slot_capacity=NUMBER_OF_BASELINE_SLOTS,);

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of theadministration project that owns the reservation resource
    • LOCATION: thelocation of the reservation. If you select aBigQuery Omni location, your edition option is limited to the 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_BASELINE_SLOTS: the number of baseline slots to allocate to the reservation. You cannot set theslot_capacity option and theedition 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, seeIntroduction to BigQuery editions.
    • NUMBER_OF_AUTOSCALING_SLOTS: the number of autoscaling slots assigned to the reservation. This is equal to the value of the max reservation size minus the number of baseline slots.

  3. ClickRun.

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

bq

To create a reservation, use thebq mk command with the--reservationflag:

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

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocation of the reservation. If you select aBigQuery Omnilocation, your editionoption is limited to the Enterprise edition.

  • NUMBER_OF_BASELINE_SLOTS: the number of baseline slots toallocate to the reservation

  • 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, seeIntroduction to BigQuery editions.

  • NUMBER_OF_AUTOSCALING_SLOTS: the number of autoscaling slots assigned to the reservation. This is equal to the value of the max reservation size minus the number of baseline slots.

For information about the--ignore_idle_slots flag, seeIdle slots. The defaultvalue isfalse.

Python

Install thegoogle-cloud-bigquery-reservation packagebefore using this code sample. Construct aReservationServiceClient. Describe the reservation you'd like to create with aReservation.Create the reservation with thecreate_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"# ...fromgoogle.cloud.bigquery_reservation_v1.servicesimportreservation_servicefromgoogle.cloud.bigquery_reservation_v1.typesimport(reservationasreservation_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:

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

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

Change the size of a reservation

You can add or remove slots from an existing reservation.

Console

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

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theReservations tab.

  4. Find the reservation you want to update.

  5. Expand theActions option.

  6. ClickEdit.

  7. In theMax reservation size selector dialog, enter the max reservation size.

  8. In theBaseline slots field, enter the number of baseline slots.

  9. ClickSave.

SQL

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

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    ALTERRESERVATION`ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`SETOPTIONS(slot_capacity=NUMBER_OF_BASELINE_SLOTS,);

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of theadministration project that owns the reservation resource
    • LOCATION: thelocation of the reservation, for exampleeurope-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_BASELINE_SLOTS: the number of baseline slots to allocate to the reservation.

  3. ClickRun.

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

bq

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

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --slots=NUMBER_OF_BASELINE_SLOTS \    --reservationRESERVATION_NAME

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocation of the reservation
  • NUMBER_OF_BASELINE_SLOTS: the number of baseline slots toallocate to the reservation
  • RESERVATION_NAME: the name of the reservation

Python

Install thegoogle-cloud-bigquery-reservation packagebefore using this code sample. Construct aReservationServiceClient. Describe the updated properties with aReservationand theFieldMask.paths property.Update the reservation with theupdate_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"# ...fromgoogle.cloud.bigquery_reservation_v1.servicesimportreservation_servicefromgoogle.cloud.bigquery_reservation_v1.typesimport(reservationasreservation_types,)fromgoogle.protobufimportfield_mask_pb2reservation_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 reservationcan use idle slots from other reservations. For more information, seeIdle slots. You can update thisconfiguration on an existing reservation.

To update a reservation, use thebq update command with the--reservationflag . The following example sets--ignore_idle_slots totrue,meaning the reservation will only use slots allocated to the reservation.

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --ignore_idle_slots=true \    --reservationRESERVATION_NAME

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocationof the reservation
  • RESERVATION_NAME: the name of the reservation

List the idle slot configuration

To list theidle slots settingfor a reservation, do the following:

SQL

Query theignore_idle_slots column of theINFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT view.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    SELECTreservation_name,ignore_idle_slotsFROM`ADMIN_PROJECT_ID.region-LOCATION`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT;

    Replace the following:

  3. ClickRun.

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

bq

Use thebq ls command with the--reservation flag:

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

Replace the following:

TheignoreIdleSlots field contains the configuration setting.

Delete reservations

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

Required permissions

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

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor

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

Delete a reservation

Console

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

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theReservations tab.

  4. Find the reservation you want to delete.

  5. Expand theActions option.

  6. ClickDelete.

  7. In theDelete reservation dialog, clickDelete.

SQL

To delete a reservation, use theDROP RESERVATION DDL statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    DROPRESERVATION`ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME`;

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of theadministration project that owns the reservation resource
    • LOCATION: thelocation of the reservation
    • RESERVATION_NAME: the ID of the reservation

  3. ClickRun.

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

bq

To delete a reservation, use thebq rm command with the--reservationflag:

bq rm \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --reservationRESERVATION_NAME

Replace the following:

  • ADMIN_PROJECT_ID: the project ID of theadministration projectthat owns the reservation resource
  • LOCATION: thelocation of the reservation
  • RESERVATION_NAME: the name of the reservation

Python

Install thegoogle-cloud-bigquery-reservation packagebefore using this code sample. Construct aReservationServiceClient.Delete the reservation with thedelete_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"# ...fromgoogle.cloud.bigquery_reservation_v1.servicesimportreservation_servicereservation_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

Note: This feature may not be available when using reservations that are created with certain BigQuery editions. For more information about which features are enabled in each edition, seeIntroduction to BigQuery editions.

The BigQuery Reservation API supportsVPC Service Controls.To integrate the BigQuery Reservation API with VPC Service Controls, follow theinstructions inCreate a service perimeter,and add the BigQuery Reservation API to the protected services.

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.