RESERVATIONS_TIMELINE view

TheINFORMATION_SCHEMA.RESERVATIONS_TIMELINE view showstime slices of reservation metadata for each reservation administration projectfor every minute in real time. Additionally, theper_second_details arrayshows autoscale details for each second.

Note: The view namesINFORMATION_SCHEMA.RESERVATIONS_TIMELINE andINFORMATION_SCHEMA.RESERVATIONS_TIMELINE_BY_PROJECT are synonymous andcan be used interchangeably.

Required permission

To query theINFORMATION_SCHEMA.RESERVATIONS_TIMELINE 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, seeBigQuery IAM roles and permissions.

Schema

When you query theINFORMATION_SCHEMA.RESERVATIONS_TIMELINE view, the queryresults contain one row for every minute of every BigQueryreservation in the last 180 days, and one row for every minute with reservationchanges for any occurrences older than 180 days. Each period starts on a whole-minuteinterval and lasts exactly one minute.

TheINFORMATION_SCHEMA.RESERVATIONS_TIMELINE view has the following schema:

Column nameData typeValue
autoscaleSTRUCT

Contains information about the autoscale capacity of the reservation. Fields include the following:

editionSTRINGThe edition associated with this reservation. For more information about editions, seeIntroduction to BigQuery editions.
ignore_idle_slotsBOOLFalse if slot sharing is enabled, otherwise true.
labelsRECORDArray of labels associated with the reservation.
reservation_group_pathSTRINGThe hierarchical group structure to which the reservation is linked. For example, if the group structure includes a parent group and a child group, thereservation_group_path field contains a list such as:[parent group, child group]. This field is inPreview.
period_startTIMESTAMPStart time of this one-minute period.
per_second_detailsSTRUCT

Contains information about the reservation capacity and usage at each second. Fields include the following:

If there are any autoscale or reservation changes during this minute, the array is populated with 60 rows. However, for non-autoscale reservations that remain unchanged during this minute, the array is empty because it'll otherwise repeat the same number 60 times.

project_idSTRINGID of the reservation administration project.
project_numberINTEGERNumber of the project.
reservation_idSTRINGFor joining with the jobs_timeline table. This is of the formproject_id:location.reservation_name.
reservation_nameSTRINGThe name of the reservation.
slots_assignedINTEGERThe number of slots assigned to this reservation.
slots_max_assignedINTEGERThe maximum slot capacity for this reservation, including slot sharing. Ifignore_idle_slots is true, this is the same asslots_assigned, otherwise this is the total number of slots in all capacity commitments in the administration project.
max_slotsINTEGERThe maximum number of slots that this reservation can use, which includes baseline slots (slot_capacity), idle slots (ifignore_idle_slots is false), and autoscale slots. This field is specified by users for using thereservation predictability feature.
scaling_modeSTRINGThe scaling mode for the reservation, which determines how the reservation scales from baseline tomax_slots. This field is specified by users for using thereservation predictability feature.
period_autoscale_slot_secondsINTEGERThe total slot seconds charged by autoscale for a specific minute (each data row corresponds to one minute).
is_creation_regionBOOLEAN

Specifies if the current region is the location where the reservation was created. This location is used to determine the pricing of the baseline reservation slots. For a failoverdisaster recovery (DR) reservation, aTRUE value indicates the original primary location, while for a non-DR reservation, aTRUE value denotes the reservation's location.

For a non-failover reservation, this value is alwaysTRUE. For a failover reservation, the value depends on the region:TRUE for the original primary andFALSE for the original secondary.

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 aregion qualifier.If you don't specify a regional qualifier, metadata is retrieved from allregions. The following table explains the region and resource scope for this view:

View nameResource scopeRegion scope
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.RESERVATIONS_TIMELINE[_BY_PROJECT]Project levelREGION
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 usea region qualifier to queryINFORMATION_SCHEMA views. The location of the query execution must match the region of theINFORMATION_SCHEMA view.

Examples

Example: See autoscaling per second

The following example shows per-second autoscaling ofYOUR_RESERVATION_ID across all jobs:

SELECTs.start_time,s.autoscale_current_slotsFROM`region-us.INFORMATION_SCHEMA.RESERVATIONS_TIMELINE`mJOINm.per_second_detailssWHEREperiod_startBETWEEN'2025-09-28'AND'2025-09-29'ANDreservation_id='YOUR_RESERVATION_ID'ORDERBYperiod_start,s.start_time

The result is similar to the following:

+---------------------+-------------------------+|     start_time      | autoscale_current_slots |+---------------------+-------------------------+| 2025-09-28 00:00:00 |                    1600 || 2025-09-28 00:00:01 |                    1600 || 2025-09-28 00:00:02 |                    1600 || 2025-09-28 00:00:03 |                    1600 || 2025-09-28 00:00:04 |                    1600 |+---------------------+-------------------------+
Note: Theperiod_start column is a partitioning key, so it's important to filterbyperiod_start to make the query efficient.

Example: See total slot usage per second

To run the query against a project other than your default project, add theproject ID in the following format:

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_ORGANIZATION
For example,`myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_ORGANIZATION.

The following example shows per-second slot usage from projects assigned toYOUR_RESERVATION_ID across all jobs:

SELECTjobs.period_start,SUM(jobs.period_slot_ms)/1000ASperiod_slot_seconds,ANY_VALUE(COALESCE(s.slots_assigned,res.slots_assigned))ASestimated_slots_assigned,ANY_VALUE(COALESCE(s.slots_max_assigned,res.slots_max_assigned))ASestimated_slots_max_assignedFROM`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_ORGANIZATIONjobsJOIN`region-us`.INFORMATION_SCHEMA.RESERVATIONS_TIMELINEresONjobs.reservation_id=res.reservation_idANDTIMESTAMP_TRUNC(jobs.period_start,MINUTE)=res.period_startLEFTJOINUNNEST(res.per_second_details)sONjobs.period_start=s.start_timeWHEREjobs.job_creation_timeBETWEENTIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL1DAY)ANDCURRENT_TIMESTAMP()ANDres.period_startBETWEENTIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL1DAY)ANDCURRENT_TIMESTAMP()ANDres.reservation_id='YOUR_RESERVATION_ID'AND(jobs.statement_type!="SCRIPT"ORjobs.statement_typeISNULL)-- Avoid duplicate byte counting in parent and children jobs.GROUPBYperiod_startORDERBYperiod_startDESC;

The result is similar to the following:

+-----------------------+---------------------+--------------------------+------------------------------+|     period_start      | period_slot_seconds | estimated_slots_assigned | estimated_slots_max_assigned |+-----------------------+---------------------+--------------------------+------------------------------+|2021-06-08 21:33:59 UTC|       100.000       |         100              |           100                ||2021-06-08 21:33:58 UTC|        96.753       |         100              |           100                ||2021-06-08 21:33:57 UTC|        41.668       |         100              |           100                |+-----------------------+---------------------+--------------------------+------------------------------+

Example: Slot usage by reservation

The following example shows per-second slot usage for each reservation in thelast day:

SELECTjobs.period_start,res.reservation_id,SUM(jobs.period_slot_ms)/1000ASperiod_slot_seconds,ANY_VALUE(COALESCE(s.slots_assigned,res.slots_assigned))ASestimated_slots_assigned,ANY_VALUE(COALESCE(s.slots_max_assigned,res.slots_max_assigned))ASestimated_slots_max_assignedFROM`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_ORGANIZATIONjobsJOIN`region-us`.INFORMATION_SCHEMA.RESERVATIONS_TIMELINEresONjobs.reservation_id=res.reservation_idANDTIMESTAMP_TRUNC(jobs.period_start,MINUTE)=res.period_startLEFTJOINUNNEST(res.per_second_details)sONjobs.period_start=s.start_timeWHEREjobs.job_creation_timeBETWEENTIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL1DAY)ANDCURRENT_TIMESTAMP()ANDres.period_startBETWEENTIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL1DAY)ANDCURRENT_TIMESTAMP()AND(jobs.statement_type!="SCRIPT"ORjobs.statement_typeISNULL)-- Avoid duplicate byte counting in parent and children jobs.GROUPBYperiod_start,reservation_idORDERBYperiod_startDESC,reservation_id;

The result is similar to the following:

+-----------------------+----------------+---------------------+--------------------------+------------------------------+|     period_start      | reservation_id | period_slot_seconds | estimated_slots_assigned | estimated_slots_max_assigned |+-----------------------+----------------+---------------------+--------------------------+------------------------------+|2021-06-08 21:33:59 UTC|     prod01     |       100.000       |             100          |              100             ||2021-06-08 21:33:58 UTC|     prod02     |       177.201       |             200          |              500             ||2021-06-08 21:32:57 UTC|     prod01     |        96.753       |             100          |              100             ||2021-06-08 21:32:56 UTC|     prod02     |       182.329       |             200          |              500             |+-----------------------+----------------+---------------------+--------------------------+------------------------------+

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 2026-02-18 UTC.