List table snapshots
This document describes how to get a list of the table snapshots in aBigQuery dataset in the Google Cloud console, by querying theINFORMATION_SCHEMA.TABLE_SNAPSHOTStable, by using thebq lscommand, or by calling thetables.listAPI. It also describes how to list all of the table snapshots of aspecified base table by querying theINFORMATION_SCHEMA.TABLE_SNAPSHOTS table.This document is intended for users who are familiar withBigQuerytables andtable snapshots.
Permissions and roles
This section describes theIdentity and Access Management (IAM) permissionsthat you need to list the table snapshots in a dataset, and thepredefined IAM rolesthat grant those permissions. The permissions and roles for listing tablesnapshots are the same as the permissions and roles required forlisting other types of tables.
Permissions
To list the table snapshots in a dataset, you need the following permission:
| Permission | Resource |
|---|---|
bigquery.tables.list | The dataset that contains the table snapshots. |
Roles
The predefined BigQuery roles that provide the requiredpermission are as follows:
| Role | Resource |
|---|---|
Any of the following:bigquery.dataUserbigquery.dataViewerbigquery.dataEditorbigquery.dataOwnerbigquery.admin | The dataset that contains the table snapshots. |
List the table snapshots in a dataset
Getting a list of table snapshots in a dataset is similar to listing othertypes of tables. The table snapshots have the typeSNAPSHOT.
You can list table snapshots by using one of the following options:
Console
In the Google Cloud console, go to theBigQuery page.
In the left pane, clickExplorer:
If you don't see the left pane, clickExpand left pane to open the pane.
In theExplorer pane, expand the project, clickDatasets, and thenselect the dataset that contains the table snapshots that you want to list.
ClickOverview> Tables. To find snapshots from the list,check for the
SNAPSHOTvalue in theType column.
SQL
Query theINFORMATION_SCHEMA.TABLE_SNAPSHOTS view:
In the Google Cloud console, go to theBigQuery page.
In the query editor, enter the following statement:
SELECT*FROMPROJECT_ID.DATASET_NAME.INFORMATION_SCHEMA.TABLE_SNAPSHOTS;
Replace the following:
PROJECT_ID: the project ID of the project that contains the snapshots you want to list.DATASET_NAME: the name of the dataset that contains the snapshots you want to list.
ClickRun.
For more information about how to run queries, seeRun an interactive query.
The result looks similar to the following:
+---------------+----------------+------------------+--------------------+-------------------+-----------------+-----------------------------+| table_catalog | table_schema | table_name | base_table_catalog | base_table_schema | base_table_name | snapshot_time |+---------------+----------------+------------------+--------------------+-------------------+-----------------+-----------------------------+| myproject | mydataset | mysnapshot | basetableproject | basetabledataset | basetable | 2021-04-16 14:05:27.519 UTC |+---------------+----------------+------------------+--------------------+-------------------+-----------------+-----------------------------+
bq
Enter the following command in the Cloud Shell:
bqls\PROJECT_ID:DATASET_NAME
Replace the following:
PROJECT_ID: the project ID of the project that contains the snapshots you want to list.DATASET_NAME: the name of the dataset that contains the snapshots you want to list.
The output looks similar to the following:
+-------------------------+--------+---------------------+-------------------+| tableId | Type | Labels | Time Partitioning |+-------------------------+--------+---------------------+-------------------+| mysnapshot |SNAPSHOT| | |+-------------------------+--------+---------------------+-------------------+
API
Call thetables.listmethod with the following parameters:
| Parameter | Value |
|---|---|
projectId | The project ID of the project that contains the snapshots you want to list. |
datasetId | The name of the dataset that contains the snapshots you want to list. |
List the table snapshots of a specified base table
You can list the table snapshots of a specified base table by querying theINFORMATION_SCHEMA.TABLE_SNAPSHOTS view:
SELECT*FROMPROJECT_ID.DATASET_NAME.INFORMATION_SCHEMA.TABLE_SNAPSHOTSWHEREbase_table_name='books';
Replace the following:
PROJECT_ID: the project ID of theproject that contains the snapshots you want to list.DATASET_NAME: the name of the datasetthat contains the snapshots you want to list.
What's next
- Get information about a table snapshot.
- Update a table snapshot's description, expiration date, oraccess policy.
- Delete a table snapshot.
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.