Manage workload reservations

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, seeUnderstand reservations.

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 Resource Editor
  • BigQuery Resource Admin

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 list, select the location. If you select aBigQuery Omnilocation, your editionoption is limited to the Enterprise edition.

  6. In theEdition list, select the edition. BigQueryedition features such as autoscaling are only available within anedition. For more information, seeIntroduction to BigQuery editions.

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

  8. Optional: In theBaseline slots field, enter the number of baselineslots for the reservation.

    The number of available autoscaling slots is determined bysubtracting theBaseline slots value from theMax reservationsize. 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.

  9. To disableidle slot sharingand use only the specified slot capacity, click theIgnore idle slotstoggle.

  10. To expand theAdvanced settings section, click theexpander arrow.

  11. Optional: To set the target job concurrency, click theOverrideautomatic target job concurrency toggle to on and enter theTargetJob Concurrency.

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

  13. ClickSave.

The new reservation is visible in theSlot reservations 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,edition=EDITION,autoscale_max_slots=NUMBER_OF_AUTOSCALING_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

      The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

    • NUMBER_OF_BASELINE_SLOTS: the number baseline of slots to allocate to the reservation. You cannot set theslot_capacity option and thestandard 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, 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 \    --edition=EDITION \    --autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS \    --max_slots=MAXIMUM_NUMBER_OF_SLOTS    --scaling_mode=SCALING_MODERESERVATION_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. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

  • 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. This can't be configured with either the--max_slots or--scaling_mode flags.

  • MAXIMUM_NUMBER_OF_SLOTS: the maximum number of slots the reservation can consume. This value must be configured with the--scaling_mode flag (Preview).

  • SCALING_MODE: the scaling mode of the reservation. The options areALL_SLOTS,IDLE_SLOTS_ONLY, orAUTOSCALE_ONLY. This value must be configured with the--scaling_mode flag (Preview).

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

Terraform

Use thegoogle_bigquery_reservationresource.

Note: To create BigQuery objects using Terraform, you mustenable theCloud Resource Manager API.

To authenticate to BigQuery, set up Application DefaultCredentials. For more information, seeSet up authentication for client libraries.

The following example creates a reservation namedmy-reservation:

resource "google_bigquery_reservation" "default" {  name              = "my-reservation"  location          = "us-central1"  slot_capacity     = 100  edition           = "ENTERPRISE"  ignore_idle_slots = false # Use idle slots from other reservations  concurrency       = 0     # Automatically adjust query concurrency based on available resources  autoscale {    max_slots = 200 # Allow the reservation to scale up to 300 slots (slot_capacity + max_slots) if needed  }}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

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}")

Create a predictable reservation

Before you create a reservation with amaximum number ofslots, you mustfirst enablereservation-based fairness.

Enable reservation-based fairness

To enable reservation-based fairness, set theenable_reservation_based_fairnessflag totrue.

To update the reservation-based fairness on a project, you need thebigquery.config.updatepermission on theprojectthat maintains ownership of the reservations. The predefinedBigQuery Adminrole includes this permission.

For more information about updating the default configuration of a project, seeManage configuration settings.

ALTERPROJECT`PROJECT_NAME`SETOPTIONS(`region-LOCATION.enable_reservation_based_fairness`=true);

Replace the following:

Create a predictable reservation

To create a predictable reservation with a maximum number of slots, select oneof the following options:

Console

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

    Go to BigQuery

  2. In the navigation panel, go to theCapacity management section, andthen clickCreate reservation.

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

  4. In theLocation list, select the location. If you select aBigQuery Omnilocation, your editionoption is limited to the Enterprise edition.

  5. In theEdition list, select the edition. For more information, seeUnderstand BigQueryeditions.

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

  7. Optional: In theBaseline slots field, enter the number of baselineslots for the reservation.

    The number of available autoscaling slots is determined bysubtracting theBaseline slots value from theMax reservationsize. 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 sharingand use only the specified slot capacity, click theIgnore idle slotstoggle.

  9. To expand theAdvanced settings section, click theexpander arrow.

    1. In theHow to use idle slots? list, select the configuration option.

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

  11. ClickSave.

The new reservation is visible in theSlot reservations tab.

bq

To create a predictable reservation, use thebq mk command with the--reservationflag and set the value ofmax_slots andscaling_mode:

bq mk \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --reservation \    --slots=NUMBER_OF_BASELINE_SLOTS \    --ignore_idle_slots=false \    --edition=EDITION \    --max_slots=MAXIMUM_NUMBER_OF_SLOTS \    --scaling_mode=SCALING_MODERESERVATION_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.

  • MAXIMUM_NUMBER_OF_SLOTS: the maximum number of slots the reservation can consume. This value must be configured with the--scaling_mode flag.

  • SCALING_MODE:SCALING_MODE: the scaling mode of the reservation. The options areALL_SLOTS,IDLE_SLOTS_ONLY, orAUTOSCALE_ONLY. This value must be configured with themax_slots flag. This value must be aligned withignore_idle_slots flag. For details, seeReservation predictability.

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

SQL

To create a predictable 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,edition=EDITION,ignore_idle_slots=IGNORE_IDLE_SLOTSmax_slots=MAX_NUMBER_OF_SLOTS,scaling_mode=SCALING_MODE);

    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.The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

    • NUMBER_OF_BASELINE_SLOTS: the number baseline of slots to allocate to the reservation. You cannot set theslot_capacity option and thestandard 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, seeIntroduction to BigQuery editions.
    • IGNORE_IDLE_SLOTS: whether the reservation usesIdle slots or not. The default value isfalse.
    • MAX_NUMBER_OF_SLOTS: the maximum number of slots the reservation can consume. This value must be configured withscaling_mode option.
    • SCALING_MODE: the scaling mode of the reservation. The options areALL_SLOTS,IDLE_SLOTS_ONLY, orAUTOSCALE_ONLY. This value must be configured with themax_slots option. This value must be aligned withignore_idle_slots option. For details, seeReservation predictability.

  3. ClickRun.

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

To learn more about predictable reservations, seePredictablereservations.

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.
  • Set the target job concurrency.

To change the edition of a reservation, firstdelete the reservation, thencreate a reservation with the updated edition.

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 theSlot reservations 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. To expand theAdvanced settings section, click theexpander arrow.

  10. Optional: To set the target job concurrency, click theOverrideautomatic target job concurrency toggle to on and enter theTargetJob Concurrency.

  11. 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,autoscale_max_slots=NUMBER_OF_AUTOSCALING_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. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

    • NUMBER_OF_BASELINE_SLOTS: the number of baseline slots to allocate to the reservation.
    • 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 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 \    --autoscale_max_slots=NUMBER_OF_AUTOSCALING_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. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.
  • 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.

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. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

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

If you delete a reservation, any running jobs that use slots from thatreservation fail. To prevent errors, allow running jobs to complete beforeyou delete 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.

Caution: You can delete a reservation with active commitments, but you are still charged for the remaining duration of the commitment. Deleting the reservation or switching associated projects to on-demand pricing doesn't stop these charges. For more information about commitment expiration, seecommitment expiration. For additional help with reservations, commitments, or costs, contactGoogle Cloud Support.

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. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

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}")

Control access to reservations

You can control which users have access to specificreservations. For a user to override a reservation on their query, they musthave thereservations.use permission on that reservation.

Required permissions

To get the permission that you need to specify a particular reservation for your job, ask your administrator to grant you theResource Editor (roles/bigquery.resourceEditor) IAM role on the reservation resource. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the reservations.use permission, which is required to specify a particular reservation for your job.

You might also be able to get this permission withcustom roles or otherpredefined roles.

Control access to a reservation

To manage access to a specific reservation resource, use thebqset-iam-policycommand.

To manage access to multiple reservation resources, use the Google Cloud consoleto grant the BigQuery Resource Editor role on the project, folder, ororganization. When you grant the role, use anIAM conditionto allow access to the reservation resources when the specified conditions aremet.

To control access to reservations, do one of the following:

Console

In the Google Cloud console, you can allow access to multiple reservationresources by using a condition.

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

    Goto IAM

  2. Select a project, folder, or organization.

  3. To grant thebigquery.resourceEditor role to a principal who has a roleon the reservation resources:

    1. On theView by principals tab, navigate to the appropriateprincipal or use theFilter option to find the principal.

    2. ClickEdit principal.

    3. On theAssign roles page, clickAdd roles.

    4. In theSearch for roles field, enterbigquery.resourceEditor.

    5. Check theBigQuery Resource Editor option in the search resultsand then clickApply.

    6. ClickSave.

  4. Alternatively, to grant thebigquery.resourceEditor role to a principalwho doesn't have a role on the reservation resources:

    1. ClickGrant Access.

    2. On theAdd principals page, in theNew principals field, enterthe principal's identifier — for example,my-user@example.com.

    3. ClickAdd roles.

    4. In theSearch for roles field, enterbigquery.resourceEditor.

    5. Check theBigQuery Resource Editor option in the search resultsand then clickApply.

    6. In theBigQuery Resource Editor box, clickAdd condition.

    7. On theAdd condition page:

      1. Enter values in theTitle andDescription fields.

      2. In theCondition builder, add your condition. For example, toadd a condition that grants the role to all reservation names thatend with/reservation1, forCondition type, chooseName,forOperator, chooseEnds with, and forValue, enter/reservation1.

      3. ClickSave.

  5. ClickSave.

bq

In the bq command-line tool, you can grant access to an individual reservation resource.

To grant access to a reservation, use thebqset-iam-policycommand:

bq set-iam-policy --reservationRESOURCEFILE_NAME

Replace the following:

  • RESOURCE: the reservation identifier.For example,project1:US.reservation1.

  • FILE_NAME: the file that contains the policy inJSON format. The format should follow theIAM policy structurefor allow policies. For example:

    {"bindings":[{"members":["user:my-user@example.com"],"role":"roles/bigquery.resourceEditor"}],"etag":"BwUjMhCsNvY=","version":1}

For more information about IAM, seeManage access to otherresources.

Prioritize idle slots with reservation groups

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

To request support or provide feedback for this feature, contactbigquery-wlm-feedback@google.com.

You can control which reservations get priority access to idle slots by creating a reservation group.Reservations within a reservation group will share idle slots with each other before they are available to other reservations in the project.

Before you create a reservation group, you mustfirst enablereservation-based fairness.

Required permissions

To get the permissions that you need to update a particular reservation to set the reservation group, ask your administrator to grant you theReservation Editor (roles/bigquery.reservationEditor) IAM role on the reservation resource. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Create reservation group

To create a reservation group:

bq

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

bq mk \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --alpha=reservation_groups \    --reservation_group \RESERVATION_GROUP_NAME

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocation of the reservation.
  • RESERVATION_GROUP_NAME: the name of the reservation group. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

Add a reservation to a reservation group

To add a reservation to a reservation group, update thereservation_group property of the reservation:

bq

To update the reservation and set the reservation group, use thebq update command with the--reservation flag:

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --alpha=reservation_groups \    --reservation_group_name=RESERVATION_GROUP_NAME \    --reservationRESERVATION_NAME

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocation of the reservation
  • RESERVATION_GROUP_NAME: the name of the reservation group. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.
  • RESERVATION_NAME: the name of the reservation. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

Listing the reservations that have a reservation group

To list the reservation group information for your reservations, do the following:

bq

To list the reservations and include the reservation group information, use thebq ls command with the--reservation and--alpha=reservation_groups flags:

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

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocation of the reservation

Remove a reservation from a reservation group

To remove a reservation from a reservation group, update thereservation_group property of the reservation to be the empty string:

bq

To remove the reservation from the reservation group, use thebq update command with the--reservation flag:

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --alpha=reservation_groups \    --reservation_group_name="" \    --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. The name can contain only lowercase alphanumeric characters or dashes, must start with a letter and must not end with a dash, and the maximum length is 64 characters.

To learn more about reservation groups, seeReservation groups.

Troubleshoot

You might encounter the following errors when creating or updating a reservation:

Error:Max reservation size can only be configured in multiples of 50, except when covered by excess commitments.
Error:Baseline slots can only be configured in multiples of 50, except when covered by excess commitments.
Slots always autoscale to a multiple of 50. Scaling up is based on actual usage, and is rounded up to the nearest 50 slot increment. When there is no commitment or if the commitment cannot cover the increases, the baseline and autoscaling slots can only be increased in multiples of 50.

Ifreservation size - baseline slots isn't a multiple of 50, then the reservation can't scale up to the maximum reservations size, resulting in this error.

Resolution:

  • Purchase more capacity commitments to cover the slot increases.
  • Choose baseline and max slots that are increments of 50.

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-17 UTC.