TABLE_STORAGE_USAGE_TIMELINE view

The INFORMATION_SCHEMA.TABLE_STORAGE_USAGE_TIMELINE view provides daily totals of storage usage for the past 90 days for the following types of tables:

  • Standard tables
  • Materialized views
  • Table clones that have a delta in bytes from the base table
  • Table snapshots that have a delta in bytes from the base table

Tables that don't have billable bytes aren't included in the INFORMATION_SCHEMA.TABLE_STORAGE_USAGE_TIMELINE view. This includes the following types of tables:

  • External tables
  • Anonymous tables
  • Empty tables
  • Table clones that have no delta in bytes from the base table
  • Table snapshots that have no delta in bytes from the base table

When you query the INFORMATION_SCHEMA.TABLE_STORAGE_USAGE_TIMELINE view, the query results contain one row per day for each table or materialized view for the current project.

The data in this table is not kept in real time. It takes approximately 72 hours for table data to be reflected in this view.

Storage usage is returned in MB second. For example, if a project uses 1,000,000 physical bytes for 86,400 seconds (24 hours), the total physical usage is 86,400,000,000 byte seconds, which is converted to 82,397 MB seconds, as shown in the following example:

86,400,000,000 / 1,024 / 1,024 = 82,397

This is the value that would be returned by the BILLABLE_TOTAL_PHYSICAL_USAGE column.

For more information, see Storage pricing details.

Required permissions

To query the INFORMATION_SCHEMA.TABLE_STORAGE_USAGE_TIMELINE view, you need the following Identity and Access Management (IAM) permissions:

  • bigquery.tables.get
  • bigquery.tables.list

Each of the following predefined IAM roles includes the preceding permissions:

  • roles/bigquery.dataViewer
  • roles/bigquery.dataEditor
  • roles/bigquery.metadataViewer
  • roles/bigquery.admin

For queries with a region qualifier, you must have permissions for the project.

For more information about BigQuery permissions, see Access control with IAM.

Schema

The INFORMATION_SCHEMA.TABLE_STORAGE_USAGE_TIMELINE view has the following schema:

USAGE_DATE DATE The billing date for the bytes shown
PROJECT_ID STRING The project ID of the project that contains the dataset
TABLE_CATALOG STRING The project ID of the project that contains the dataset
PROJECT_NUMBER INT64 The project number of the project that contains the dataset
TABLE_SCHEMA STRING The name of the dataset that contains the table or materialized view, also referred to as the datasetId
TABLE_NAME STRING The name of the table or materialized view, also referred to as the tableId
BILLABLE_TOTAL_LOGICAL_USAGE INT64

The total logical usage, in MB second.

Returns 0 if the dataset uses the physical storage billing model.

BILLABLE_ACTIVE_LOGICAL_USAGE INT64

The logical usage that is less than 90 days old, in MB second.

Returns 0 if the dataset uses the physical storage billing model.

BILLABLE_LONG_TERM_LOGICAL_USAGE INT64

The logical usage that is more than 90 days old, in MB second.

Returns 0 if the dataset uses the physical storage billing model.

BILLABLE_TOTAL_PHYSICAL_USAGE