Skip to main content

capacity_commitments

Creates, updates, deletes, gets or lists a capacity_commitments resource.

Overview​

Namecapacity_commitments
TypeResource
Idgoogle.bigqueryreservation.capacity_commitments

Fields​

The following fields are returned by SELECT queries:

Successful response

NameDatatypeDescription
namestringOutput only. The resource name of the capacity commitment, e.g., projects/myproject/locations/US/capacityCommitments/123 The commitment_id must only contain lower case alphanumeric characters or dashes. It must start with a letter and must not end with a dash. Its maximum length is 64 characters.
commitmentEndTimestring (google-datetime)Output only. The end of the current commitment period. It is applicable only for ACTIVE capacity commitments. Note after renewal, commitment_end_time is the time the renewed commitment expires. So itwould be at a time after commitment_start_time + committed period, because we don't change commitment_start_time ,
commitmentStartTimestring (google-datetime)Output only. The start of the current commitment period. It is applicable only for ACTIVE capacity commitments. Note after the commitment is renewed, commitment_start_time won't be changed. It refers to the start time of the original commitment.
editionstringOptional. Edition of the capacity commitment.
failureStatusobjectOutput only. For FAILED commitment plan, provides the reason of failure. (id: Status)
isFlatRatebooleanOutput only. If true, the commitment is a flat-rate commitment, otherwise, it's an edition commitment.
multiRegionAuxiliarybooleanApplicable only for commitments located within one of the BigQuery multi-regions (US or EU). If set to true, this commitment is placed in the organization's secondary region which is designated for disaster recovery purposes. If false, this commitment is placed in the organization's default region. NOTE: this is a preview feature. Project must be allow-listed in order to set this field.
planstringOptional. Capacity commitment commitment plan.
renewalPlanstringOptional. The plan this capacity commitment is converted to after commitment_end_time passes. Once the plan is changed, committed period is extended according to commitment plan. Only applicable for ANNUAL and TRIAL commitments.
slotCountstring (int64)Optional. Number of slots in this commitment.
statestringOutput only. State of the commitment.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectprojectsId, locationsId, capacityCommitmentsIdReturns information about the capacity commitment.
listselectprojectsId, locationsIdpageSize, pageTokenLists all the capacity commitments for the admin project.
createinsertprojectsId, locationsIdenforceSingleAdminProjectPerOrg, capacityCommitmentIdCreates a new capacity commitment resource.
patchupdateprojectsId, locationsId, capacityCommitmentsIdupdateMaskUpdates an existing capacity commitment. Only plan and renewal_plan fields can be updated. Plan can only be changed to a plan of a longer commitment period. Attempting to change to a plan with shorter commitment period will fail with the error code google.rpc.Code.FAILED_PRECONDITION.
deletedeleteprojectsId, locationsId, capacityCommitmentsIdforceDeletes a capacity commitment. Attempting to delete capacity commitment before its commitment_end_time will fail with the error code google.rpc.Code.FAILED_PRECONDITION.
splitexecprojectsId, locationsId, capacityCommitmentsIdSplits capacity commitment to two commitments of the same plan and commitment_end_time. A common use case is to enable downgrading commitments. For example, in order to downgrade from 10000 slots to 8000, you might split a 10000 capacity commitment into commitments of 2000 and 8000. Then, you delete the first one after the commitment end time passes.
mergeexecprojectsId, locationsIdMerges capacity commitments of the same plan into a single commitment. The resulting capacity commitment has the greater commitment_end_time out of the to-be-merged capacity commitments. Attempting to merge capacity commitments of different plan will fail with the error code google.rpc.Code.FAILED_PRECONDITION.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
capacityCommitmentsIdstring
locationsIdstring
projectsIdstring
capacityCommitmentIdstring
enforceSingleAdminProjectPerOrgboolean
forceboolean
pageSizeinteger (int32)
pageTokenstring
updateMaskstring (google-fieldmask)

SELECT examples​

Returns information about the capacity commitment.

SELECT
name,
commitmentEndTime,
commitmentStartTime,
edition,
failureStatus,
isFlatRate,
multiRegionAuxiliary,
plan,
renewalPlan,
slotCount,
state
FROM google.bigqueryreservation.capacity_commitments
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND capacityCommitmentsId = '{{ capacityCommitmentsId }}' -- required;

INSERT examples​

Creates a new capacity commitment resource.

INSERT INTO google.bigqueryreservation.capacity_commitments (
data__slotCount,
data__plan,
data__renewalPlan,
data__multiRegionAuxiliary,
data__edition,
projectsId,
locationsId,
enforceSingleAdminProjectPerOrg,
capacityCommitmentId
)
SELECT 
'{{ slotCount }}',
'{{ plan }}',
'{{ renewalPlan }}',
{{ multiRegionAuxiliary }},
'{{ edition }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ enforceSingleAdminProjectPerOrg }}',
'{{ capacityCommitmentId }}'
RETURNING
name,
commitmentEndTime,
commitmentStartTime,
edition,
failureStatus,
isFlatRate,
multiRegionAuxiliary,
plan,
renewalPlan,
slotCount,
state
;

UPDATE examples​

Updates an existing capacity commitment. Only plan and renewal_plan fields can be updated. Plan can only be changed to a plan of a longer commitment period. Attempting to change to a plan with shorter commitment period will fail with the error code google.rpc.Code.FAILED_PRECONDITION.

UPDATE google.bigqueryreservation.capacity_commitments
SET 
data__slotCount = '{{ slotCount }}',
data__plan = '{{ plan }}',
data__renewalPlan = '{{ renewalPlan }}',
data__multiRegionAuxiliary = {{ multiRegionAuxiliary }},
data__edition = '{{ edition }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND capacityCommitmentsId = '{{ capacityCommitmentsId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
commitmentEndTime,
commitmentStartTime,
edition,
failureStatus,
isFlatRate,
multiRegionAuxiliary,
plan,
renewalPlan,
slotCount,
state;

DELETE examples​

Deletes a capacity commitment. Attempting to delete capacity commitment before its commitment_end_time will fail with the error code google.rpc.Code.FAILED_PRECONDITION.

DELETE FROM google.bigqueryreservation.capacity_commitments
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND capacityCommitmentsId = '{{ capacityCommitmentsId }}' --required
AND force = '{{ force }}';

Lifecycle Methods​

Splits capacity commitment to two commitments of the same plan and commitment_end_time. A common use case is to enable downgrading commitments. For example, in order to downgrade from 10000 slots to 8000, you might split a 10000 capacity commitment into commitments of 2000 and 8000. Then, you delete the first one after the commitment end time passes.

EXEC google.bigqueryreservation.capacity_commitments.split 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@capacityCommitmentsId='{{ capacityCommitmentsId }}' --required 
@@json=
'{
"slotCount": "{{ slotCount }}"
}';