Slot Commitments

Masthead checks whether a BigQuery capacity commitment would lower your Enterprise or Enterprise Plus compute costs, and how many slots it should have.

Commitment groups

Committed slots and reservation baselines are shared within one reservation admin project, location and edition. Masthead calls this a commitment group. A group can have commitments, or only reservations.

Where to find it

• Costs overview → Commitments: every commitment group with its status, committed slots, cost for the selected date range, and savings.
• Commitment group page: utilization and cost charts, the group’s reservations, and a Saving options widget when the group has a recommendation.
• Recommendation page: the recommendation with its estimated savings and cost per slot-hour, charts of the estimate, and Actions with the SQL to apply it.

The insights table carries the same recommendations with their actions.

How recommendations work

Every day, Masthead takes each group’s slot demand over the last 30 days and prices commitment sizes in steps of 50 slots. Committed slots cost the commitment price, and demand above them costs the pay-as-you-go autoscale price, adjusted for how efficiently your reservations autoscale. The cheapest size is the recommendation. Recommendations are rebuilt every morning (UTC) from the previous day’s data, so a purchase, a renewal change or a baseline change shows in the next day’s recommendation.

Type	When	Actions
Buy commitment	A commitment, or more committed slots next to the active one, costs less than the current reservations.	Buy the commitment, then set baselines.
Decrease commitment at renewal	A smaller commitment, or none, costs less. Savings start after the active commitment ends.	Change what renews, then lower baselines.
Set baseline	The commitment size is right, or a smaller size is already scheduled to renew, but the reservation baselines don’t match it.	Set baselines.

Apply a recommendation

Caution

• Buying a commitment is a purchase. A commitment can’t be cancelled or reduced before it ends.
• Recommendations refresh once a day and don’t show a purchase made since. Before buying, check that your live commitments still match the recommendation’s active committed slots.
• Baseline slots are always billed. Baseline above your committed slots is billed at pay-as-you-go rates, including after a commitment ends.

Buy a commitment

1. Check your live commitments in the BigQuery console (Workload management → Slot commitments), or with bq:

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

2. Buy the commitment in the admin project. Choose the renewal plan now: NONE ends the commitment after its term, ANNUAL or THREE_YEAR renews it.

   CREATE CAPACITY `ADMIN_PROJECT_ID.region-LOCATION.COMMITMENT_ID`
   OPTIONS (
     slot_count = 500,
     edition = 'ENTERPRISE',
     plan = 'ANNUAL',
     renewal_plan = 'NONE');

   COMMITMENT_ID can use lowercase letters, numbers and dashes, and must be unique in the project and location.

3. Set baselines, as below.

Set baselines

Split the recommended committed slots across the group’s reservations, giving baseline to the reservations that run steadily:

ALTER RESERVATION `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_ID`
SET OPTIONS (
  slot_capacity = 250,
  autoscale_max_slots = GREATEST(0, 400 - 250));

• Set baselines after the commitment exists. Baseline that committed slots don’t cover must be a multiple of 50.
• When a smaller size is already scheduled to renew, lower the baselines to it on or before the commitment’s end date. The savings start when the commitment ends.
• Committed slots that aren’t given out as baseline are idle slots. Reservations with ignore_idle_slots = false use them before autoscaling.
• A reservation with ignore_idle_slots = true doesn’t use committed slots it has no baseline for. Give it a baseline, or set ignore_idle_slots to false.
• Keep autoscaling on: it covers demand above the commitment.
• Keep each reservation’s maximum size (baseline plus autoscale_max_slots) as it is: set autoscale_max_slots to GREATEST(0, MAXIMUM - BASELINE), the old maximum minus the new baseline, or 0 if the new baseline is above the old maximum. Use baselines in steps of 50: BigQuery accepts only multiples of 50 for autoscale_max_slots. The recommendation’s savings assume the same maximum. For example, a reservation with no baseline and 400 autoscale slots keeps its 400-slot maximum with a baseline of 250: GREATEST(0, 400 - 250) gives 150 autoscale slots.

Decrease a commitment at renewal

An active commitment can’t be reduced, so change what renews before the commitment ends:

• To let it end, set its renewal plan to NONE. It’s deleted when it ends.

  ALTER CAPACITY `ADMIN_PROJECT_ID.region-LOCATION.COMMITMENT_ID`
  SET OPTIONS (renewal_plan = 'NONE');

• To renew a smaller size, keep renewing only the commitments that add up to the new size, and set the rest to NONE. A kept commitment whose renewal plan is NONE needs renewal_plan = 'ANNUAL'. If no combination adds up, split a commitment first. There is no SQL for a split: the new part keeps the plan and end date, and splits go in steps of 50 slots:

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

The console has the same actions on the Slot commitments tab: Edit renewal plan and Split.

Lower the baselines to the new size on or before the end date. When the commitment ends without renewing, set every baseline to 0.