Console
    Contact Us Start free

    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:

    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

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

      Go to BigQuery

    2. In the navigation menu, click Capacity management.

    3. Click Create reservation.

    4. In the Reservation namefield, enter a name for the reservation.

    5. In the Locationdrop-down list, select the location.

    6. In the Capacity Modelsection, select the capacity model.

    7. If you select the Flat-Rateoption, under Baseline slots, enter the number of slots for the reservation.

      1. In the Max reservation size selectorlist, select the maximum reservation size.

      2. Optional: In the Baseline slotsfield, enter the number of baseline slots for the reservation. To use only the specified slot capacity, click the Ignore idle slotstoggle.

        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 .

    8. To disable idle slot sharing , click the Ignore idle slotstoggle.

    9. The breakdown of slots is displayed in the Cost estimatetable. A summary of the reservation is displayed in the Capacity summarytable.

    10. Click Save.

    The new reservation is visible in the Reservationstab.

    SQL

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

    1. In the Google Cloud console, go to the BigQuerypage.

      Go to BigQuery

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

       CREATE 
  
  RESERVATION 
 
  
`  ADMIN_PROJECT_ID 
 
 . 
 region 
 - 
  LOCATION 
 
 . 
  RESERVATION_NAME 
 
` OPTIONS 
  
 ( 
  
 slot_capacity 
  
 = 
  
  NUMBER_OF_BASELINE_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 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 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. This is equal to the value of the max reservation size minus the number of baseline slots.

    3. 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_BASELINE_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 the Enterprise edition.

    • NUMBER_OF_BASELINE_SLOTS : the number of baseline slots to allocate 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, see Introduction 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, 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:

    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

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

      Go to BigQuery

    2. In the navigation menu, click Capacity management.

    3. Click the Reservationstab.

    4. Find the reservation you want to update.

    5. Expand the Actionsoption.

    6. Click Edit.

    7. In the Max reservation size selectordialog, enter the max reservation size.

    8. In the Baseline slotsfield, enter the number of baseline slots.

    9. Click Save.

    SQL

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

    1. In the Google Cloud console, go to the BigQuerypage.

      Go to BigQuery

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

       ALTER 
  
  RESERVATION 
 
  
`  ADMIN_PROJECT_ID 
 
 . 
 region 
 - 
  LOCATION 
 
 . 
  RESERVATION_NAME 
 
` SET 
  
 OPTIONS 
  
 ( 
  
 slot_capacity 
  
 = 
  
  NUMBER_OF_BASELINE_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_BASELINE_SLOTS : the number of baseline slots to allocate to the reservation.

    3. 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_BASELINE_SLOTS 
\
    --reservation RESERVATION_NAME

    Replace the following:

    • ADMIN_PROJECT_ID : the project ID
    • LOCATION : the location of the reservation
    • NUMBER_OF_BASELINE_SLOTS : the number of baseline 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 
 " 
 \t 
 slot_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 .

    1. In the Google Cloud console, go to the BigQuerypage.

      Go to BigQuery

    2. 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:

    3. 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:

    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:

    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

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

      Go to BigQuery

    2. In the navigation menu, click Capacity management.

    3. Click the Reservationstab.

    4. Find the reservation you want to delete.

    5. Expand the Actionsoption.

    6. Click Delete.

    7. In the Delete reservationdialog, click Delete.

    SQL

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

    1. In the Google Cloud console, go to the BigQuerypage.

      Go to BigQuery

    2. 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

    3. 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.

    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: