Manage workload commitments

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. Commitments cannot be moved between projects.

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.

Purchase commitments

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:

• bigquery.capacityCommitments.create on theadministration projectthat maintains ownership of the commitments.

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

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.Commitments cannot be moved between projects.

bq mk \    --project_id=ADMIN_PROJECT_ID \    --location=LOCATION \    --capacity_commitment=true \    --edition=EDITION \    --plan=PLAN_TYPE \    --renewal_plan=RENEWAL_PLAN_TYPE \    --slots=NUMBER_OF_SLOTS

View capacity commitments

The following sections describe how to view your existing capacity commitments.

Required permissions

To view commitments, you need the following Identity and Access Management (IAM)permission:

• bigquery.capacityCommitments.list on theadministration projectthat maintains ownership of the commitments.

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.

View capacity commitments by project

To view your capacity commitments by project:

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

Update capacity commitments

You can make the following updates to a capacity commitment:

• Update the renewal plan of the 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:

• bigquery.capacityCommitments.update on theadministration projectthat maintains ownership of the commitments.

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.

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

Convert a commitment to longer duration

You can choose to convert your commitment to a longer-duration commitment typeat any time. This works even if you want to convert from a legacy plan toan edition.

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 asANNUAL orTHREE_YEAR.

• RENEWAL_PLAN: therenewalplan

  This applies only if thePLAN_TYPE isANNUAL.

• 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 youhave an annual commitment of 1,000 slots, you could split off 300 slots into anew commitment, leaving 700 slots in the original commitment. You could thenrenew 700 slots at the annual rate, and convert 300 slots to a three-yearcommitment. You can split a commitment in increments of 50 slots.

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

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

Merge two commitments

You can merge multiple commitments into one commitment. The merging commitmentsmust all be of the same type (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.

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

Upgrade commitments to a new edition

You can't directly upgrade a commitment to a new edition. For example, you can'tupgrade a commitment from the Enterprise edition to theEnterprise Plus edition. Instead, follow these steps to upgrade acommitment:

1. Create a new commitment. Choose the appropriate upgradededition. Note that this new commitment has a different commitment end datethan your existing commitment.

2. Contact support to request a cancellationof your existing commitment.

Commitment expiration

Commitments expire at the end of their duration. You can't delete a commitmentwhile it is still active. If the renewal plan is set toNONE, the commitmentis automatically deleted. Otherwise it is renewed with an annual orthree-year commitment, depending on the renewal plan. To change the renewal plantoNONE, follow the steps inRenew a commitment.

After renewing a commitment, the value ofStart time isn't changed. Itrefers to the start time of the original commitment. The value ofEnd timeis the time the renewed commitment expires. For example, if you have one annualcommitment created on December 13, 2022, and it's renewed on December 13, 2023.If you view the commitment details on December 14, 2023, the value ofStart time would be December 13, 2022 and the value ofEnd timewould be December 12, 2024.

Baseline slots are always charged. If a capacity commitment expires you mightneed to manually adjust the amount of baseline slots in your reservations toavoid any unwanted charges. For example, consider that you have a 1-yearcommitment with 100 slots and a reservation with 100 baseline slots. Thecommitment expires and doesn't have a renewal plan. Once the commitment expires,you pay for 100 baseline slots at thepay as you gorate.

Control the creation of capacity commitments

You can useIAM deny policies for additional controlover who can create capacity commitments.

Deny policies can be created for a set of users or all, and they can beconfigured with exceptions and conditions.

For example, the following policy denies all users the permission to createcapacity commitments with the exception of the principal "lucian@example.com":

{"deniedPrincipals":["principalSet://goog/public:all"],"deniedPermissions":["bigquery.googleapis.com/capacityCommitments.create"],"exceptionPrincipals":["principal://goog/subject/lucian@example.com"]}

This policy can then be attached to an organization to control who can createthe commitments.

Note that these policies take precedence over the IAM roles, soeven a user with thebigquery.admin role wouldn't be able to create acommitment unless the policy is deleted or modified.

For more information, seeDeny access to resources.

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.