CAPACITY_COMMITMENT_CHANGES view
The INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES view contains a near
real-time list of all changes to capacity commitments within the administration
project. Each row represents a single change to a single capacity commitment.
For more information, see Slot commitments.
Required permission
To query the INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES view,
you need the bigquery.capacityCommitments.list Identity and Access Management (IAM)
permission for the project.
Each of the following predefined IAM roles includes the required
permission:
roles/bigquery.resourceAdminroles/bigquery.resourceEditorroles/bigquery.resourceViewerroles/bigquery.userroles/bigquery.admin
For more information about BigQuery permissions, see
Access control with IAM.
Schema
The INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES view has the
following schema:
| Column name |
Data type |
Value |
change_timestamp |
TIMESTAMP |
Time when the change occurred. |
project_id |
STRING |
ID of the administration project. |
project_number |
INTEGER |
Number of the administration project. |
capacity_commitment_id |
STRING |
ID that uniquely identifies the capacity commitment. |
commitment_plan |
STRING |
Commitment plan of the capacity commitment. |
state |
STRING |
State the capacity commitment is in. Can be PENDING or
ACTIVE. |
slot_count |
INTEGER |
Slot count associated with the capacity commitment. |
action |
STRING |
Type of event that occurred with the capacity commitment. Can be
CREATE, UPDATE, or DELETE. |
user_email |
STRING |
Email address of the user or subject of the workforce identity
federation that made the change. google for changes
made by Google. NULL if the email address is unknown.
|
commitment_start_time |
TIMESTAMP |
The start of the current commitment period. Only applicable for
ACTIVE capacity commitments, otherwise this is
NULL. |
commitment_end_time |
TIMESTAMP |
The end of the current commitment period. Only applicable for
ACTIVE capacity commitments, otherwise this is
NULL. |
failure_status |
RECORD |
For a FAILED commitment plan, provides the failure
reason, otherwise this is NULL. RECORD
consists of code and message. |
renewal_plan |
STRING |
The plan this capacity commitment is converted to after
commitment_end_time passes. After the plan is changed,
the committed period is extended according to the commitment plan. Only
applicable for ANNUAL and TRIAL
commitments, otherwise this is NULL. |
edition |
STRING |
The edition associated with this reservation. For more information about editions, see Introduction to BigQuery editions. |
is_flat_rate |
BOOL |
Whether the commitment is associated with the legacy flat-rate capacity model or an edition. If FALSE, the current commitment is associated with an edition. If TRUE, the commitment is the legacy flat-rate capacity model. |
Data retention
This view contains current capacity commitments and the deleted capacity
commitments that are kept for a maximum of 41 days after which they are removed
from the view.
Scope and syntax
Queries against this view must include a region qualifier.
If you do not specify a regional qualifier, metadata is retrieved from all
regions. The following table explains the region scope for this view:
| View name |
Resource scope |
Region scope |
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES[_BY_PROJECT] |
Project level |
REGION |
Replace the following:
Example
The following query displays the user who has made the latest capacity commitment
update to the current project within the specified date.
SELECT
user_email,
change_timestamp
FROM
`region-us`.INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES
WHERE
change_timestamp BETWEEN '2021-09-30' AND '2021-10-01'
ORDER BY
change_timestamp DESC
LIMIT 1;
The result is similar to the following:
+--------------------------------+-------------------------+
| user_email | change_timestamp |
+--------------------------------+-------------------------+
| 222larabrown@gmail.com | 2021-09-30 09:30:00 UTC |
+--------------------------------+-------------------------+
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-25 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eThe \u003ccode\u003eINFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES\u003c/code\u003e view provides a real-time record of all changes made to capacity commitments within an administration project, with each row detailing a single change.\u003c/p\u003e\n"],["\u003cp\u003eQuerying this view requires the \u003ccode\u003ebigquery.capacityCommitments.list\u003c/code\u003e IAM permission, which is included in roles such as \u003ccode\u003eroles/bigquery.resourceAdmin\u003c/code\u003e, \u003ccode\u003eroles/bigquery.resourceEditor\u003c/code\u003e, \u003ccode\u003eroles/bigquery.resourceViewer\u003c/code\u003e, \u003ccode\u003eroles/bigquery.user\u003c/code\u003e, and \u003ccode\u003eroles/bigquery.admin\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eEach entry in the view includes details like the \u003ccode\u003echange_timestamp\u003c/code\u003e, \u003ccode\u003eproject_id\u003c/code\u003e, \u003ccode\u003ecapacity_commitment_id\u003c/code\u003e, \u003ccode\u003ecommitment_plan\u003c/code\u003e, \u003ccode\u003estate\u003c/code\u003e, \u003ccode\u003eslot_count\u003c/code\u003e, \u003ccode\u003eaction\u003c/code\u003e, and the \u003ccode\u003euser_email\u003c/code\u003e that initiated the change.\u003c/p\u003e\n"],["\u003cp\u003eThe data in this view is retained for a maximum of 41 days after a capacity commitment is deleted, after which it is permanently removed from the view.\u003c/p\u003e\n"],["\u003cp\u003eQueries against this view must include a region qualifier, and the location of the query execution must match the region of the \u003ccode\u003eINFORMATION_SCHEMA\u003c/code\u003e view.\u003c/p\u003e\n"]]],[],null,["# CAPACITY_COMMITMENT_CHANGES view\n================================\n\nThe `INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES` view contains a near\nreal-time list of all changes to capacity commitments within the administration\nproject. Each row represents a single change to a single capacity commitment.\nFor more information, see [Slot commitments](/bigquery/docs/reservations-workload-management#slot_commitments).\n\nRequired permission\n-------------------\n\nTo query the `INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES` view,\nyou need the `bigquery.capacityCommitments.list` Identity and Access Management (IAM)\npermission for the project.\nEach of the following predefined IAM roles includes the required\npermission:\n\n- `roles/bigquery.resourceAdmin`\n- `roles/bigquery.resourceEditor`\n- `roles/bigquery.resourceViewer`\n- `roles/bigquery.user`\n- `roles/bigquery.admin`\n\nFor more information about BigQuery permissions, see\n[Access control with IAM](/bigquery/docs/access-control).\n\nSchema\n------\n\nThe `INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES` view has the\nfollowing schema:\n\nData retention\n--------------\n\nThis view contains current capacity commitments and the deleted capacity\ncommitments that are kept for a maximum of 41 days after which they are removed\nfrom the view.\n\nScope and syntax\n----------------\n\nQueries against this view must include a [region qualifier](/bigquery/docs/information-schema-intro#syntax).\nIf you do not specify a regional qualifier, metadata is retrieved from all\nregions. The following table explains the region scope for this view:\n\nReplace the following:\n\n- Optional: \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the ID of your Google Cloud project. If not specified, the default project is used.\n- \u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e: any [dataset region name](/bigquery/docs/locations). For example, ```region-us```.\n\n \u003cbr /\u003e\n\n \u003cbr /\u003e\n\n | **Note:** You must use [a region qualifier](/bigquery/docs/information-schema-intro#region_qualifier) to query `INFORMATION_SCHEMA` views. The location of the query execution must match the region of the `INFORMATION_SCHEMA` view.\n\n\u003cbr /\u003e\n\nExample\n-------\n\nThe following query displays the user who has made the latest capacity commitment\nupdate to the current project within the specified date. \n\n```googlesql\nSELECT\n user_email,\n change_timestamp\nFROM\n `region-us`.INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES\nWHERE\n change_timestamp BETWEEN '2021-09-30' AND '2021-10-01'\nORDER BY\n change_timestamp DESC\nLIMIT 1;\n```\n\nThe result is similar to the following: \n\n```\n+--------------------------------+-------------------------+\n| user_email | change_timestamp |\n+--------------------------------+-------------------------+\n| 222larabrown@gmail.com | 2021-09-30 09:30:00 UTC |\n+--------------------------------+-------------------------+\n\n```"]]
