JOBS_TIMELINE view
TheINFORMATION_SCHEMA.JOBS_TIMELINE view contains near real-timeBigQuery metadata by timeslice for all jobs submitted in thecurrent project. This view contains currently running and completed jobs.
INFORMATION_SCHEMA.JOBS_TIMELINE andINFORMATION_SCHEMA.JOBS_TIMELINE_BY_PROJECT are synonymous and can be usedinterchangeably.Required permissions
To query theINFORMATION_SCHEMA.JOBS_TIMELINE view, you need thebigquery.jobs.listAll Identity and Access Management (IAM) permission for the project.Each of the following predefined IAM roles includes the requiredpermission:
- Project Owner
- BigQuery Admin
For more information about BigQuery permissions, seeAccess control with IAM.
Schema
When you query theINFORMATION_SCHEMA.JOBS_TIMELINE_BY_* views, the queryresults contain one row for every second of execution of everyBigQuery job. Each period starts on a whole-second interval andlasts exactly one second.
TheINFORMATION_SCHEMA.JOBS_TIMELINE_BY_* view has the following schema:
job_creation_time column andclustered byproject_id anduser_email.| Column name | Data type | Value |
|---|---|---|
period_start | TIMESTAMP | Start time of this period. |
period_slot_ms | INTEGER | Slot milliseconds consumed in this period. |
project_id | STRING | (Clustering column) ID of the project. |
project_number | INTEGER | Number of the project. |
user_email | STRING | (Clustering column) Email address or service account of the user who ran the job. |
principal_subject | STRING | A string representation of the identity of the principal that ran the job. |
job_id | STRING | ID of the job. For example,bquxjob_1234. |
job_type | STRING | The type of the job. Can beQUERY,LOAD,EXTRACT,COPY, orNULL. ANULL value indicates a background job. |
labels | RECORD | Array of labels applied to the job as key-value pairs. |
statement_type | STRING | The type of query statement, if valid. For example,SELECT,INSERT,UPDATE, orDELETE. |
priority | STRING | The priority of this job. Valid values includeINTERACTIVE andBATCH. |
parent_job_id | STRING | ID of the parent job, if any. |
job_creation_time | TIMESTAMP | (Partitioning column) Creation time of this job. Partitioning is based on the UTC time of this timestamp. |
job_start_time | TIMESTAMP | Start time of this job. |
job_end_time | TIMESTAMP | End time of this job. |
state | STRING | Running state of the job at the end of this period. Valid states includePENDING,RUNNING, andDONE. |
reservation_id | STRING | Name of the primary reservation assigned to this job at the end of this period, if applicable. |
edition | STRING | The edition associated with the reservation assigned to this job. For more information about editions, seeIntroduction to BigQuery editions. |
total_bytes_billed | INTEGER | If the project is configured to useon-demand pricing, then this field contains the total bytes billed for the job. If the project is configured to useflat-rate pricing, then you are not billed for bytes and this field is informational only. This field is only populated for completed jobs and contains the total number of bytes billed for the entire duration of the job. |
total_bytes_processed | INTEGER | Total bytes processed by the job. This field is only populated for completed jobs and contains the total number of bytes processed over the entire duration of the job. |
error_result | RECORD | Details of error (if any) as anErrorProto. |
cache_hit | BOOLEAN | Whether the query results of this job were from a cache. |
period_shuffle_ram_usage_ratio | FLOAT | Shuffle usage ratio in the selected time period. The value is0.0 if the job ran with a reservation that uses autoscaling and has zero baseline slots. |
period_estimated_runnable_units | INTEGER | Units of work that can be scheduled immediately in this period. Additional slots for these units of work accelerate your query, provided no other query in the reservation needs additional slots. |
transaction_id | STRING | ID of thetransaction in which this job ran, if any. |
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.
Data retention
This view displays running jobs along with job history for the past 180 days.If a project migrates to an organization (either from having no organization orfrom a different one), job information predating the migration date isn'taccessible through theINFORMATION_SCHEMA.JOBS_TIMELINE view, as the view onlyretains data starting from the migration date.
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 scope for this view:
| View name | Resource scope | Region scope |
|---|---|---|
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.JOBS_TIMELINE[_BY_PROJECT] | Project level | REGION |
- 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 query
INFORMATION_SCHEMAviews. The location of the query execution must match the region of theINFORMATION_SCHEMAview.
Examples
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.VIEW
For example,`myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE.
The following example calculates the slot utilization for every second in thelast day:
SELECTperiod_start,SUM(period_slot_ms)AStotal_slot_ms,FROM`reservation-admin-project.region-us`.INFORMATION_SCHEMA.JOBS_TIMELINEWHEREperiod_startBETWEENTIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL1DAY)ANDCURRENT_TIMESTAMP()GROUPBYperiod_startORDERBYperiod_startDESC;
INFORMATION_SCHEMA view names are case-sensitive.The result is similar to the following:
+---------------------+---------------+| period_start | total_slot_ms |+---------------------+---------------+| 2020-07-29 03:52:14 | 122415176 || 2020-07-29 03:52:15 | 141107048 || 2020-07-29 03:52:16 | 173335142 || 2020-07-28 03:52:17 | 131107048 |+---------------------+---------------+
You can check usage for a particular reservation withWHERE reservation_id = "…". For script jobs, the parent job also reports thetotal slot usage from its children jobs. To avoid double counting, useWHERE statement_type != "SCRIPT" to exclude the parent job.
Number ofRUNNING andPENDING jobs over time
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.VIEW
For example,`myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE.
The following example computes the number ofRUNNING andPENDING jobs at everysecond in the last day:
SELECTperiod_start,SUM(IF(state="PENDING",1,0))asPENDING,SUM(IF(state="RUNNING",1,0))asRUNNINGFROM`reservation-admin-project.region-us`.INFORMATION_SCHEMA.JOBS_TIMELINEWHEREperiod_startBETWEENTIMESTAMP_SUB(CURRENT_TIMESTAMP(),INTERVAL1DAY)ANDCURRENT_TIMESTAMP()GROUPBYperiod_start;
INFORMATION_SCHEMA view names are case-sensitive.The result is similar to the following:
+---------------------+---------+---------+| period_start | PENDING | RUNNING |+---------------------+---------+---------+| 2020-07-29 03:52:14 | 7 | 27 || 2020-07-29 03:52:15 | 1 | 21 || 2020-07-29 03:52:16 | 5 | 21 || 2020-07-29 03:52:17 | 4 | 22 |+---------------------+---------+---------+
Resource usage by jobs at a specific point in time
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.VIEW
For example,`myproject`.`region-us`.INFORMATION_SCHEMA.JOBS.
The following example returns thejob_id of all jobs running at a specificpoint in time together with their resource usage during that one-second period:
SELECTjob_id,period_slot_msFROM`reservation-admin-project.region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_PROJECTWHEREperiod_start='2020-07-29 03:52:14'AND(statement_type!='SCRIPT'ORstatement_typeISNULL);
INFORMATION_SCHEMA view names are case-sensitive.The result is similar to the following:
+------------------+| job_id | slot_ms |+------------------+| job_1 | 2415176 || job_2 | 4417245 || job_3 | 427416 || job_4 | 1458122 |+------------------+
Match slot usage behavior from administrative resource charts
You can useadministrative resource charts tomonitor your organization's health, slot usage, and BigQuery jobsperformance over time. The following example queries theINFORMATION_SCHEMA.JOBS_TIMELINE view for a slot usage timeline at one-hourintervals, similar to the information that is available in administrativeresource charts.
DECLAREstart_timetimestampDEFAULTTIMESTAMP(START_TIME);DECLAREend_timetimestampDEFAULTTIMESTAMP(END_TIME);WITHsnapshot_dataAS(SELECTUNIX_MILLIS(period_start)ASperiod_start,IFNULL(SUM(period_slot_ms),0)ASperiod_slot_ms,DIV(UNIX_MILLIS(period_start),3600000*1)*3600000*1AStime_msFROM(SELECT*FROM`PROJECT_ID.region-US`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_PROJECTWHERE((job_creation_time>=TIMESTAMP_SUB(start_time,INTERVAL1200MINUTE)ANDjob_creation_time<TIMESTAMP(end_time))ANDperiod_start>=TIMESTAMP(start_time)ANDperiod_start<TIMESTAMP(end_time))AND(statement_type!="SCRIPT"ORstatement_typeISNULL)ANDREGEXP_CONTAINS(reservation_id,"^PROJECT_ID:"))GROUPBYperiod_start,time_ms),converted_percentiles_dataAS(SELECTtime_ms,100-CAST(SAFE_DIVIDE(3600000*1*1/1000,COUNT(*))ASINT64)ASconverted_percentiles,FROMsnapshot_dataGROUPBYtime_ms),data_by_timeAS(SELECTtime_ms,IF(converted_percentiles<=0,0,APPROX_QUANTILES(period_slot_ms,100)[SAFE_OFFSET(converted_percentiles)]/1000)ASp99_slots,SUM(period_slot_ms)/(3600000*1)ASavg_slotsFROMsnapshot_dataJOINconverted_percentiles_dataAScUSING(time_ms)GROUPBYtime_ms,converted_percentiles)SELECTtime_ms,TIMESTAMP_MILLIS(time_ms)AStime_stamp,IFNULL(avg_slots,0)ASavg_slots,IFNULL(p99_slots,0)ASp99_slots,FROM(SELECTtime_ms*3600000*1AStime_msFROMUNNEST(GENERATE_ARRAY(DIV(UNIX_MILLIS(start_time),3600000*1),DIV(UNIX_MILLIS(end_time),3600000*1)-1,1))AStime_ms)LEFTJOINdata_by_timeUSING(time_ms)ORDERBYtime_msDESC;
Calculate the percentage of execution time that had pending work
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.VIEW
For example,`myproject`.`region-us`.INFORMATION_SCHEMA.JOBS.
The following example returns a float value that represents the percentage of the total job execution duration where the value ofperiod_estimated_runnable_units was non-zero, which means that the job was requesting more slots. A large value indicates that the job suffered from slot contention, whereas a small value indicates that the job wasn't requesting slots for the majority of the execution time, which means that there was little to no slot contention.
If the resulting value is large, you can try adding more slots to see the impact and understand whether slot contention is the only bottleneck.
SELECTROUND(COUNTIF(period_estimated_runnable_units>0)/COUNT(*)*100,1)asexecution_duration_percentageFROM`myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINEWHEREjob_id='my_job_id'GROUPBYjob_id
If you know the date of the query execution, add aDATE(period_start) = 'YYYY-MM-DD' clause to the query to reduce the amount of bytes processed and speed up the execution. For example,DATE(period_start) = '2025-08-22'.
INFORMATION_SCHEMA view names are case-sensitive.The result is similar to the following:
+-------------------------------+| execution_duration_percentage |+-------------------------------+| 96.7 |+-------------------------------+
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-19 UTC.