RESERVATIONS view

TheINFORMATION_SCHEMA.RESERVATIONS view contains a near real-time list of allcurrent reservations within the administration project. Each row represents asingle, current reservation. A current reservation is a reservation that has notbeen deleted. For more information about reservation, seeIntroduction to reservations.

Note: The view namesINFORMATION_SCHEMA.RESERVATIONS andINFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT are synonymous andcan be used interchangeably.

Required permission

To query theINFORMATION_SCHEMA.RESERVATIONS view, you needthebigquery.reservations.list Identity and Access Management (IAM) permission on theproject.Each of the following predefined IAM roles includes the requiredpermission:

BigQuery Resource Admin (roles/bigquery.resourceAdmin)
BigQuery Resource Editor (roles/bigquery.resourceEditor)
BigQuery Resource Viewer (roles/bigquery.resourceViewer)
BigQuery User (roles/bigquery.user)
BigQuery Admin (roles/bigquery.admin)

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

Schema

TheINFORMATION_SCHEMA.RESERVATIONS view has thefollowing schema:

Column name	Data type	Value
`ddl`	`STRING`	The DDL statement used to create this reservation.
`project_id`	`STRING`	ID of the administration project.
`project_number`	`INTEGER`	Number of the administration project.
`reservation_name`	`STRING`	User provided reservation name.
`ignore_idle_slots`	`BOOL`	If false, any query using this reservation can use unused idle slots from other capacity commitments.
`slot_capacity`	`INTEGER`	Baseline of the reservation.
`target_job_concurrency`	`INTEGER`	The target number of queries that can execute simultaneously, which is limited by available resources. If zero, then this value is computed automatically based on available resources.
`autoscale`	`STRUCT`	Information about the autoscale capacity of the reservation. Fields include the following: `current_slots`: the number of slots added to the reservation by autoscaling.Note: After users reduce`max_slots`, it may take a while before it can be propagated, so`current_slots` may stay in the original value and could be larger than`max_slots` for that brief period (less than one minute). `max_slots`: the maximum number of slots that could be added to the reservation by autoscaling.
`edition`	`STRING`	The edition associated with this reservation. For more information about editions, seeIntroduction to BigQuery editions.
`primary_location`	`STRING`	The current location of the reservation's primary replica. This field is only set for reservations using themanaged disaster recovery feature.
`secondary_location`	`STRING`	The current location of the reservation's secondary replica. This field is only set for reservations using themanaged disaster recovery feature.
`original_primary_location`	`STRING`	The location where the reservation was originally created.
`labels`	`RECORD`	Array of labels associated with the reservation.
`reservation_group_path`	`STRING`	The hierarchical group structure to which the reservation is linked. For example, if the group structure includes a parent group and a child group, the`reservation_group_path` field contains a list such as:`[parent group, child group]`. This field is inPreview.
`max_slots`	`INTEGER`	The maximum number of slots that this reservation can use, which includes baseline slots (`slot_capacity`), idle slots (if`ignore_idle_slots` is false), and autoscale slots. This field is specified by users for using thereservation predictability feature.
`scaling_mode`	`STRING`	The scaling mode for the reservation, which determines how the reservation scales from baseline to`max_slots`. This field is specified by users for using thereservation predictability feature.

For stability, we recommend that you explicitly list columns in your information schema queries instead ofusing a wildcard (SELECT *). Explicitly listing columns prevents queries frombreaking if the underlying schema changes.

Scope and syntax

Queries against this view must include aregionqualifier. The following tableexplains the region scope for this view:

View name	Resource scope	Region scope
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.RESERVATIONS[_BY_PROJECT]	Project level	`REGION`

Replace the following:

Optional:PROJECT_ID: the ID of your Google Cloud project. If not specified, the default project is used.
REGION: anydataset region name. For example,`region-us`.
Note: You must use a region qualifier to queryINFORMATION_SCHEMA views. The location of the query execution must match the region of theINFORMATION_SCHEMA view.

Joining between the reservation views and the job views

Thejob views contain the columnreservation_id. If your job ran in a project with a reservation assigned toit,reservation_id would follow this format:reservation-admin-project:reservation-location.reservation-name.

To join between the reservation views and the job views, you can join betweenthe job views columnreservation_id and the reservation views columnsproject_id andreservation_name. The following example shows an example of ausing theJOIN clause between the reservation and the job views.

Example

The following example shows slot usage, slot capacity, and assigned reservationfor a project with a reservation assignment, over the past hour. Slot usage isgiven in units of slot milliseconds per second.

WITHjob_dataAS(SELECTjob.period_start,job.reservation_id,job.period_slot_ms,job.job_id,job.job_typeFROM`my-project.region-us`.INFORMATION_SCHEMA.JOBS_TIMELINEASjobWHEREjob.period_start>TIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL1HOUR))SELECTreservation.reservation_nameASreservation_name,job.period_start,reservation.slot_capacity,job.period_slot_ms,job.job_id,job.job_typeFROMjob_dataASjobINNERJOIN`reservation-admin-project.region-us`.INFORMATION_SCHEMA.RESERVATIONSASreservationON(job.reservation_id=CONCAT(reservation.project_id,":","US",".",reservation.reservation_name));

The output is similar to the following:

+------------------+---------------------+---------------+----------------+------------------+----------+| reservation_name |    period_start     | slot_capacity | period_slot_ms |           job_id | job_type |+------------------+---------------------+---------------+----------------+------------------+----------+| my_reservation   | 2021-04-30 17:30:54 |           100 |          11131 | bquxjob_66707... | QUERY    || my_reservation   | 2021-04-30 17:30:55 |           100 |          49978 | bquxjob_66707... | QUERY    || my_reservation   | 2021-04-30 17:30:56 |           100 |           9038 | bquxjob_66707... | QUERY    || my_reservation   | 2021-04-30 17:30:57 |           100 |          17237 | bquxjob_66707... | QUERY    |

This query uses theRESERVATIONS view to get reservationinformation. If the reservations have changed in the past hour, thereservation_slot_capacity column might not be accurate.

The query joinsRESERVATIONS withJOBS_TIMELINE toassociate the job timeslices with the reservation information.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.