Update table snapshot metadata

This document describes how to update the description, expiration date, oraccess policy for a tablesnapshot by using the Google Cloud console, thebq updatecommand, or thetables.patch API.It is intended for users who are familiar withtables andtable snapshots in BigQuery.

Permissions and roles

This section describes theIdentity and Access Management (IAM) permissionsthat you need to update the metadata for a table snapshot, and thepredefined IAM rolesthat grant those permissions.

Permissions

To update a table snapshot's metadata, you need the following permission:

PermissionResource
bigquery.tables.updateThe table snapshot

Roles

The predefined BigQuery roles that provide the requiredpermission are as follows:

RoleResource
Any of the following:

bigquery.dataEditor
bigquery.dataOwner
biguqery.admin		The table snapshot

Limitations

You can update a table snapshot's metadata, but you can't update its databecause table snapshot data is read only. To update a table snapshot's data,you must first restore the table snapshot to a standard table, and then updatethe standard table's data. For more information, seeRestoring table snapshots.

Update a table snapshot's metadata

You can change a table snapshot's description, expiration, and access policiesin the same way as you change a standard table's metadata. Some examples areprovided in the following sections.

Update the description

You can change the description for a table snapshot by using one of thefollowing options:

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

    If you don't see the left pane, clickExpand left pane to open the pane.

  3. In theExplorer pane, expand your project, clickDatasets, andthen click the dataset that has the table snapshot.

  4. ClickOverview> Tables, and then click the name of thetable snapshot that you want to update.

  5. Go to theDetails tab, and then clickEdit Details.

  6. In theDescription field, add or update the description for thetable snapshot.

  7. ClickSave.

bq

Enter the following command in the Cloud Shell:

Go to Cloud Shell

bqupdate\--description="DESCRIPTION"\PROJECT_ID:DATASET_NAME.SNAPSHOT_NAME

Replace the following:

  • DESCRIPTION: text describing the snapshot. For example,Snapshot after table schema change X..
  • PROJECT_ID: the project ID of the project that contains the snapshot.
  • DATASET_NAME: the name of the dataset that contains the snapshot.
  • SNAPSHOT_NAME: the name of the snapshot.

API

Call thetables.patchmethod with the following parameters:

ParameterValue
projectIdThe project ID of the project that contains the snapshot.
datasetIdThe name of the dataset that contains the snapshot.
tableIdThe name of the snapshot.
Request bodydescription fieldText describing the snapshot. For example,Snapshot after table schema change X.

Prefer thetables.patch method over thetables.update method because thetables.update method replaces the entireTable resource.

Update the expiration

You can change the expiration of a table snapshot by using one of thefollowing options:

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, clickDatasets, andthen click the dataset that has the table snapshot.

  4. ClickOverview> Tables, and then click the name of thetable snapshot that you want to update.

  5. Go to theDetails tab and then clickEdit Details.

  6. In theExpiration time field, enter the new expiration time for thetable snapshot.

  7. ClickSave.

bq

Enter the following command in the Cloud Shell:

Go to Cloud Shell

bqupdate\--expiration=EXPIRATION_TIME\PROJECT_ID:DATASET_NAME.SNAPSHOT_NAME

Replace the following:

  • EXPIRATION_TIME: the number of seconds from the current time to the expiration time.
  • PROJECT_ID: the project ID of the project that contains the snapshot.
  • DATASET_NAME: the name of the dataset that contains the snapshot.
  • SNAPSHOT_NAME: the name of the snapshot.

API

Call thetables.patchmethod with the following parameters:

ParameterValue
projectIdThe project ID of the project that contains the snapshot.
datasetIdThe name of the dataset that contains the snapshot.
tableIdThe name of the snapshot.
Request bodyexpirationTime fieldThe time when the snapshot expires, in milliseconds since the epoch.

Prefer thetables.patch method over thetables.update method because thetables.update method replaces the entireTable resource.

Update access

You can give a user access to view the data in a table snapshot by usingone of the following options:

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, clickDatasets, andthen click the dataset that has the table snapshot.

  4. ClickOverview> Tables, and then click the name of thetable snapshot that you want to share.

  5. In the snapshot pane that appears, clickShare, then clickAddprincipal.

  6. In theAdd principals pane that appears, enter the identifier of theprincipal you want togive access to the table snapshot.

  7. In theSelect a role dropdown, chooseBigQuery, thenBigQuery Data Viewer.

  8. ClickSave.

bq

Enter the following command in the Cloud Shell:

Go to Cloud Shell

bqadd-iam-policy-binding\--member="user:PRINCIPAL"\--role="roles/bigquery.dataViewer"\PROJECT_ID:DATASET_NAME.SNAPSHOT_NAME

Replace the following:

  • PRINCIPAL: theprincipal you want to give access to the table snapshot.
  • PROJECT_ID: the project ID of the project that contains the snapshot.
  • DATASET_NAME: the name of the dataset that contains the snapshot.
  • SNAPSHOT_NAME: the name of the snapshot.

API

Call thetables.setIamPolicymethod with the following parameters:

ParameterValue
Resource
projects/PROJECT_ID/datasets/DATASET_NAME/tables/SNAPSHOT_NAME
Request body
{"policy":{"bindings":[{"members":["user:PRINCIPAL"],"role":"roles/bigquery.dataViewer"}]}}

Replace the following:

  • PROJECT_ID: the project ID of the project that contains the snapshot.
  • DATASET_NAME: the name of the dataset that contains the snapshot.
  • SNAPSHOT_NAME: the name of the snapshot.
  • PRINCIPAL: theprincipal you want to give access to the table snapshot.

What's next

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.