Purchase and manage slot commitments

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.

A capacity commitment is a purchase of BigQuery compute capacity for some minimum duration of time. Purchasing a capacity commitment is optional when creating a reservation with an edition, but can provide cost savings.

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

Enable the Reservations API

The BigQuery Reservation API is distinct from the existing BigQuery API and must be enabled independently. For more information, see Enabling and disabling APIs.

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

Purchase slots

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

Required permissions

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

bigquery.capacityCommitments.create on the administration project that maintains ownership of the commitments.

Each of the following predefined IAM roles includes this permission:

BigQuery Admin
BigQuery Resource Admin

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

Create a capacity commitment

Console

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

Go to BigQuery
In the navigation panel, go to the Capacity management section.
Click Create Commitment.
Under Configure:
1. Select the location.
2. In the Capacity model section, select the capacity model.
3. If you select the Autoscaling (Edition) option:
  1. In the Edition list, select the edition. Capacity commitments are only supported in the Enterprise and Enterprise Plus editions. Autoscaling is only available within an edition. For more information about editions, see Introduction to BigQuery editions.
4. Select the Commitment duration, which specifies your commitment plan.
5. If you are purchasing an Annual commitment, select the Renewal plan that you want to take effect when the commitment expires:
  1. Renew annually. When the annual commitment expires, it renews for another year as an annual commitment.
  For more information, see Commitments.
6. Enter the Number of slots you want to purchase.
7. Click Next.
Review the Cost estimate for your purchase.
Under Confirm and submit:
1. Type CONFIRM to confirm the purchase.
2. Click Purchase to purchase the slots.
To view the commitment, click View slot commitments. After the capacity is provisioned, the requested capacity commitment has a green status.

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

The first time you purchase capacity, a default reservation is created.

SQL

To create a capacity commitment, use the CREATE CAPACITY DDL statement.

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

Go to BigQuery
In the query editor, enter the following statement:
```
CREATE CAPACITY
  `ADMIN_PROJECT_ID.region-LOCATION.COMMITMENT_ID`
OPTIONS (
  slot_count = NUMBER_OF_SLOTS,
  edition = EDITION,
  plan = 'PLAN_TYPE');
```
Replace the following:
- ADMIN_PROJECT_ID: the project ID of the administration project that will maintain ownership of this commitment
- LOCATION: the location 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
- EDITION: the edition associated with the capacity commitment. You can only create a capacity commitment with the Enterprise or Enterprise Plus editions. To learn more about editions, see Introduction to BigQuery editions.
- PLAN_TYPE: the plan type, such as ANNUAL or THREE_YEAR.
Click Run.

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

bq

Use the bq mk command with the --capacity_commitment flag to purchase slots.

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

Replace the following:

ADMIN_PROJECT_ID: the project ID of the administration project that will maintain ownership this commitment
LOCATION: the location of the commitment
EDITION: the edition associated with the capacity commitment. You can only create a capacity commitment with the Enterprise or Enterprise Plus editions. To learn more about editions, see Introduction to BigQuery editions.
PLAN_TYPE: the plan type, such as ANNUAL or THREE_YEAR.
RENEWAL_PLAN_TYPE: the renewal plan type, such as NONE, ANNUAL or THREE_YEAR.
NUMBER_OF_SLOTS: the number of slots to purchase.

View capacity commitments

Required permissions

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

bigquery.capacityCommitments.list on the administration project that maintains ownership of the commitments.

Each of the following predefined IAM roles includes this permission:

BigQuery Admin
BigQuery Resource Admin
BigQuery Resource Editor
BigQuery Resource Viewer
BigQuery User

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

View capacity commitments by project

To view your capacity commitments by project:

Console

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

Go to BigQuery
In the navigation panel, go to the Capacity Management section.
Click the Slot commitments tab. Your capacity commitments are listed in the table under Commitments.

SQL

To view the commitments for an administration project, query the INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECT view.

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

Go to BigQuery
In the query editor, enter the following statement:
```
SELECT
  capacity_commitment_id
FROM
  `region-LOCATION`.INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECT
WHERE
  project_id = 'ADMIN_PROJECT_ID'
  AND slot_count = 100;
```
Replace the following:
- LOCATION: the location of the commitments
- ADMIN_PROJECT_ID: the project ID of the administration project that owns the commitments
Click Run.

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

bq

Use the bq ls command with the --capacity_commitment flag to list the commitments for an administration project.

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

Replace the following:

LOCATION: the location of the commitments
ADMIN_PROJECT_ID: the project ID of the administration project that owns the commitments

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 following Identity and Access Management (IAM) permission:

bigquery.capacityCommitments.update on the administration project that maintains ownership of the commitments.

Each of the following predefined IAM roles includes this permission:

BigQuery Admin
BigQuery Resource Admin

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

Renew a commitment

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

Console

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

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

Go to BigQuery
In the navigation panel, go to the Capacity Management section.
Click the Slot commitments tab.
Find the commitment you want to edit.
Click Actions, and then select the Edit renewal plan option.
Select the new renewal plan.

bq

To change the renewal plan choice for an annual commitment, use the bq update command with the --capacity_commitment flag and 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:

ADMIN_PROJECT_ID: the project ID of the administration project that will maintain ownership this commitment
LOCATION: the location of the commitment
PLAN_TYPE: the plan type, such as ANNUAL or THREE_YEAR.
COMMITMENT_ID: the ID of the commitment

To get the ID, see View purchased commitments.

Convert a commitment to longer duration

You can choose to convert your commitment to a longer-duration commitment type at any time.

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

To convert a commitment, use the bq update command with 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: the location of the commitment
PLAN_TYPE: the plan type, such as ANNUAL or THREE_YEAR.
RENEWAL_PLAN: the renewal plan

This applies only if the PLAN_TYPE is ANNUAL.
COMMITMENT_ID: the ID of the commitment

To get the ID, see View purchased commitments.

Split a commitment

You can split your commitment into two commitments. This can be useful if you want to renew part of a commitment. For example, if you have an annual commitment of 1,000 slots, you could split off 300 slots into a new commitment, leaving 700 slots in the original commitment. You could then renew 700 slots at the annual rate, and convert 300 slots to a three-year commitment. You can split a commitment in increments of 50 slots.

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

Console

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

Go to BigQuery
In the navigation panel, go to the Capacity Management section.
Click the Slot commitments tab.
Select the commitment that you want to split.
Click Split.
In the Split commitment page, use the Configure split slider to select how many slots go into each split, in increments of 50 slots.
Click Split to split the commitment. The new commitment is listed in the Slot commitments tab.

bq

To split commitments, use the bq 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: the location of the commitment
SLOTS_TO_SPLIT: the number of slots to split from the original commitment into a new commitment
COMMITMENT_ID: the ID of the commitment

To get the ID, see View purchased commitments.

Merge two commitments

You can merge multiple commitments into one commitment. The merging commitments must all be of the same type (ANNUAL or THREE_YEAR). The end date of the combined commitment is the maximum end date of the original commitments. If any of the commitments have an earlier end date, they are extended to the later date and you are charged a prorated amount for those slots.

Console

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

Go to BigQuery
In the navigation panel, go to the Capacity Management section.
Click the Slot commitments tab.
Select the commitments that you want to merge.
Click Merge.
In the Merge commitments page, review the details of the merge and click Merge. The new merged commitment is listed in the Slot commitments tab.

bq

To merge two commitments into one commitment, use the bq 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: the location of the commitments
COMMITMENT1: the first commitment to merge
COMMITMENT2: the second commitment to merge

Commitment expiration

Commitments expire at the end of their duration. You can't delete a commitment while it is still active. If the renewal plan is set to NONE, the commitment is automatically deleted. Otherwise it is renewed with an annual or three-year commitment, depending on the renewal plan. To change the renewal plan to NONE, follow the steps in Renew a commitment.

After renewing a commitment, the value of Start time isn't changed. It refers to the start time of the original commitment. The value of End time is the time the renewed commitment expires. For example, if you have one annual commitment 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 of Start time would be December 13, 2022 and the value of End time would be December 12, 2024.

Baseline slots are always charged. If a capacity commitment expires you might need to manually adjust the amount of baseline slots in your reservations to avoid any unwanted charges. For example, consider that you have a 1-year commitment with 100 slots and a reservation with 100 baseline slots. The commitment expires and doesn't have a renewal plan. Once the commitment expires, you pay for 100 baseline slots at the pay as you go rate.

Control the creation of capacity commitments

You can use IAM deny policies for additional control over who can create capacity commitments.

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

For example, the following policy denies all users the permission to create capacity 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 create the commitments.

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

For more information, see Deny access to resources.

Troubleshooting capacity commitments

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

Purchased slots are pending

Slots are subject to available capacity. When you purchase slot commitments and BigQuery allocates them, then the Status column shows a check mark. If BigQuery can't allocate the requested slots immediately, then the Status column remains pending. You might have to wait several hours for the slots to become available. If you need access to slots sooner, try the following:

Delete the pending commitment.
Purchase a new commitment for a smaller number of slots. Depending on capacity, the smaller commitment might become active immediately.
Purchase the remaining slots as a separate commitment. These slots might show as pending in the Status column, but they generally become active within a few hours.
Optional: When both commitments are available, you can merge them into a single commitment, as long as you purchased the same plan for both.

If a slot commitment fails or takes a long time to complete, consider using on-demand pricing temporarily. With this solution, you might need to run critical queries on a different project that's not assigned to any reservations, or you might need to remove the project assignment altogether.