Purchase and manage legacy slot commitments

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.

Acapacity commitment is a purchase of BigQuery compute capacity forsome minimum duration of time. Purchasing a capacity commitment is optional whencreating a reservation with anedition, but canprovide cost savings.

Commitments are a regional resource. Commitments purchased in one region ormulti-region cannot be used in any other regions or multi-regions.Commitments cannot be moved between regions or between regions andmulti-regions.

Enable the Reservations API

The BigQuery Reservation API is distinct from the existingBigQuery API and must be enabled independently. For moreinformation, seeEnabling and disabling APIs.

  • The name of the API is "BigQuery Reservations API"
  • The endpoint for the BigQuery Reservation API isbigqueryreservation.googleapis.com.

Enable API.

Note: If you want to prevent anyone in your organization from enabling theBigQuery Reservation API,contact support.

Purchase slots

To reserve capacity for some minimum amount of time, you can purchase acapacity commitment.This provides a discount and saves on costs. For more information about the specific costs, seeBigQuery pricing.

Required permissions

To create a capacity commitment, you need the followingIdentity and Access Management (IAM) permission:

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin

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

Create a capacity commitment

Caution: Before creating a capacity commitment, understand the details of thecommitment plans andpricing.

Commitments are a regional resource. Commitments purchased in one region ormulti-region cannot be used in any other regions or multi-regions. Commitmentscannot be moved between regions or between regions and multi-regions.

Console

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

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. ClickCreate Commitment.

  4. UnderConfigure:

    1. Select the location.
    2. In theCapacity model section, select the capacity model.
    3. Select theCommitment duration, which specifies your commitmentplan.

    4. If you are purchasing anAnnual commitment, select theRenewalplan that you want to take effect when the commitment expires:

      1. Do not renew and convert to a monthly commitment (Default).When the annual commitment expires, it converts to a monthlycommitment.
      2. Renew annually. When the annual commitment expires, it renewsfor another year as an annual commitment.
      3. Do not renew and convert to flex slots.When the annual commitment expires, it converts to a flex slotscommitment.

      For more information, seeSlot commitments.

    5. Enter theNumber of slots you want to purchase.

    6. ClickNext.

  5. Review theCost estimate for your purchase.

  6. UnderConfirm and submit:

    1. TypeCONFIRM to confirm the purchase.
    2. ClickPurchase to purchase the slots.

  7. To view the commitment, clickView slot commitments. After thecapacity is provisioned, the requested capacity commitment has a greenstatus.

    Note: Slots are usually provisioned quickly, but in rare cases it cantake several hours. If you have a critical workload where you expect tohave increased demand, reserve your slots at least one day inadvance.

The first time you purchase capacity, adefault reservation is created.

SQL

To create a capacity commitment, use theCREATE CAPACITY DDL statement.

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

    Go to BigQuery

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

    CREATECAPACITY`ADMIN_PROJECT_ID.region-LOCATION.COMMITMENT_ID`OPTIONS(slot_count=NUMBER_OF_SLOTS,plan='PLAN_TYPE');

    Replace the following:

    • ADMIN_PROJECT_ID: the project ID of theadministration project that will maintain ownership of this commitment
    • LOCATION: thelocation of the commitment

    • COMMITMENT_ID: the ID of the commitment

      It must be unique to the project and location. 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 purchase
    • PLAN_TYPE: theplan type, such asFLEX,MONTHLY, orANNUAL.

  3. ClickRun.

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

bq

Use thebq mk commandwith the--capacity_commitment flagto purchase slots.

bq mk \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --capacity_commitment=true \    --plan=PLAN_TYPE \    --slots=NUMBER_OF_SLOTS

Replace the following:

  • ADMIN_PROJECT_ID: the project ID of theadministration projectthat will maintain ownership this commitment
  • LOCATION: thelocationof the commitment
  • PLAN_TYPE: theplan type, suchasFLEX,MONTHLY, orANNUAL.
  • NUMBER_OF_SLOTS: the number of slots topurchase.

View capacity commitments

Required permissions

To view commitments, 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
  • BigQuery Resource Viewer
  • BigQuery User

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

Note: When you view legacy capacity commitments, the value of theCapacity Model column isFlat-Rate. The value of theEdition column isEnterprise. The value of theEdition column doesn't indicate that that you have purchased a commitment associated with an edition.

View capacity commitments by project

To view your capacity commitments by project:

Console

It's not possible to view legacy capacity commitments using the Google Cloud console.

SQL

To view the commitments for an administration project, query theINFORMATION_SCHEMA.CAPACITY_COMMITMENTS_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:

    SELECTcapacity_commitment_idFROM`region-LOCATION`.INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECTWHEREproject_id='ADMIN_PROJECT_ID'ANDslot_count=100;

    Replace the following:

  3. ClickRun.

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

bq

Use thebq ls commandwith the--capacity_commitment flagto list the commitments for an administration project.

bq ls \    --capacity_commitment=true \    --location=LOCATION \    --project_id=ADMIN_PROJECT_ID

Replace the following:

Update capacity commitments

You can make the following updates to a capacity commitment:

  • Renew an existing commitment.
  • Convert a commitment to a commitment plan with a longer duration.
  • Split a commitment into two commitments.
  • Merge two commitments into a single commitment.

Required permissions

To update capacity commitments, you need the followingIdentity and Access Management (IAM) permission:

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin

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

Renew a commitment

Annual commitments have a renewal plan, which you specify when youcreate or convert to an annual commitment. You can change yourannual commitment's renewal planat any time before the commitment end date.

Console

You can change your renewal plan for an annual commitment as follows:

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

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theSlot commitments tab.

  4. Find the commitment you want to edit.

  5. ClickActions, and then select theEdit renewal plan option.

  6. Select the new renewal plan.

bq

To change the renewal plan choice for an annual commitment, use thebq update commandwith the--capacity_commitment flagand the--renewal_plan flag.

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --renewal_plan=PLAN_TYPE \    --capacity_commitment=true \COMMITMENT_ID

Replace the following:

Convert a commitment to longer duration

You can choose to convert your commitment to a longer-duration commitment typeat any time:

  • You can convert your flex slots commitment to a monthly or annual commitment.
  • You can convert your monthly commitment to an annual commitment.

As soon as you update your commitment, you are charged the rateassociated with the new plan, and the end date resets.

To convert a commitment, use thebq update commandwith the--plan flag.

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --plan=PLAN_TYPE \    --renewal_plan=RENEWAL_PLAN \    --capacity_commitment=true \COMMITMENT_ID

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocationof the commitment
  • PLAN_TYPE: theplan type, such asFLEX,MONTHLY, orANNUAL.

  • RENEWAL_PLAN: therenewalplan

    This applies only if thePLAN_TYPE isANNUAL. If thePLAN_TYPE isMONTHLY, omit thisflag.

  • COMMITMENT_ID: the ID of the commitment

    To get the ID, seeView purchased commitments.

Split a commitment

You can split your commitment into two commitments. This can be useful if youwant torenew part of a commitment. For example, if you have anannual commitment of 1,000 slots, you could split off 300 slots into a newcommitment, leaving 700 slots in the original commitment. You could then renew700 slots at theannual rate, and convert 300 slots to flex slots after the end date.

When you split a commitment, the new commitment has the same plan and the samecommitment end date as the original commitment.

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 commitments tab.

  4. Select the commitment that you want to split.

  5. ClickSplit.

  6. In theSplit commitment page, use theConfigure split slider toselect how many slots go into each split, in increments of 100 slots.

  7. ClickSplit to split the commitment. The new commitment is listed intheSlot commitments tab.

bq

To split commitments, use thebq update command.

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --split \    --slots=SLOTS_TO_SPLIT \    --capacity_commitment=true \COMMITMENT_ID

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocationof the commitment
  • SLOTS_TO_SPLIT: the number of slots to splitfrom the original commitment into a new commitment

  • COMMITMENT_ID: the ID of the commitment

    To get the ID, seeView purchased commitments.

Merge two commitments

You can merge multiple commitments into one commitment. The merging commitmentsmust all be of the same type (FLEX,MONTHLY,ANNUAL, orTHREE_YEAR). The enddate of the combined commitment is the maximum end date of the originalcommitments. If any of the commitments have an earlier end date,they are extended to the later date and you are charged a prorated amount forthose slots.

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 commitments tab.

  4. Select the commitments that you want to merge.

  5. ClickMerge.

  6. In theMerge commitments page, review the details of the merge andclickMerge. The new merged commitment is listed in theSlot commitments tab.

bq

To merge two commitments into one commitment, use thebq update command:

bq update \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --merge=true \    --capacity_commitment=true \COMMITMENT1,COMMITMENT2

Replace the following:

  • ADMIN_PROJECT_ID: the project ID
  • LOCATION: thelocationof the commitments
  • COMMITMENT1: the first commitment to merge
  • COMMITMENT2: the second commitment to merge

Delete a commitment

You can delete a capacity commitment if its end date is in the past.The commitment end date is shown in the Google Cloud console.Before you delete a commitment, make sure there are enoughunallocated slots. If not, you must decrease the number of slots in areservation or remove reservations entirely.

Required permissions

To delete capacity commitments, you need the followingIdentity and Access Management (IAM) permission:

Each of the following predefined IAM roles includes thispermission:

  • BigQuery Admin
  • BigQuery Resource Admin

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

Deleting a capacity commitment

Caution: This operation cannot be undone.

Console

To delete a capacity commitment, complete the following steps:

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

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theSlot commitments tab.

  4. In theLocation drop-down list, select the appropriate location.

  5. Find the commitment you want to delete.

  6. Expand theActions option.

  7. ClickDelete.

  8. Type "REMOVE" and clickProceed.

SQL

To delete a capacity commitment, use theDROP CAPACITY DDL statement.

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

    Go to BigQuery

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

    DROPCAPACITY`ADMIN_PROJECT_ID.region-LOCATION.COMMITMENT_ID`;

    Replace the following:

    • ADMIN_PROJECT_ID: the project that owns the commitment
    • LOCATION: thelocation of the commitment

    • COMMITMENT_ID: the ID of the commitment

      To get the ID, seeView purchased commitments.

  3. ClickRun.

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

bq

To delete a capacity commitment, use thebq rm command with the--capacity_commitment flag:

bq rm \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --capacity_commitment=true \COMMITMENT_ID

Replace the following:

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

  • COMMITMENT_ID: the ID of the commitment youwant to delete

    To get the ID, seeView purchased commitments.

Troubleshooting capacity commitments

This section describes troubleshooting steps that you might find helpful if yourun into problems using BigQuery Reservations.

Purchased slots are pending

Slots are subject to available capacity. When you purchase slot commitments andBigQuery allocates them, then theStatus column shows a checkmark. If BigQuery can't allocate the requested slots immediately,then theStatus column remains pending. You might have to wait several hoursfor the slots to become available. If you need access to slots sooner, try thefollowing:

  1. Delete the pending commitment.
  2. Purchase a new commitment for a smaller number of slots. Depending oncapacity, the smaller commitment might become active immediately.
  3. Purchase the remaining slots as a separate commitment. These slots mightshow as pending in theStatus column, but they generally become activewithin a few hours.
  4. Optional: When both commitments are available, you canmerge them into a single commitment, as long as youpurchased the same plan for both.

If a slot commitment fails or takes a long time to complete, consider usingon-demand pricing temporarily. With thissolution, you might need to run critical queries on a different project that'snot assigned to any reservations, or you might need to remove the projectassignment altogether.

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.