Update table snapshot metadata

This document describes how to update the description, expiration date, or access policy for a table snapshot by using the Google Cloud Console, the bq update command, or the tables.patch API. It is intended for users who are familiar with tables and table snapshots in BigQuery.

Permissions and roles

This section describes the Identity and Access Management (IAM) permissions that you need to update the metadata for a table snapshot, and the predefined IAM roles that grant those permissions.

Permissions

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

Permission Resource
bigquery.tables.update The table snapshot

Roles

The predefined BigQuery roles that provide the required permission are as follows:

Role Resource
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 data because 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 update the standard table's data. For more information, see Restoring table snapshots.

Update a table snapshot's metadata

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

Update the description

As an example, change the description for the library_backup.books table snapshot to books-2022-03-04 as follows:

Console

  1. In the Cloud Console, go to the BigQuery page.

    Go to BigQuery

  2. In the Explorer pane, expand the project and dataset nodes of the library_backup.books table snapshot.

  3. Click the name of the table snapshot, in this case, books.

  4. In the books panel that opens, click into the Details tab, and then click Edit Details.

  5. In the Description field, add or update the description for the table snapshot.

  6. Click Save.

bq

Enter the following command in the Cloud Shell:

Go to Cloud Shell

bq update --description="books-2022-03-04" library_backup.books

API

Call the tables.patch method with the following parameters:

Parameter Value
projectId myProject
datasetId library_backup
tableId books
Request body
{
"description": "books-2022-03-04"}

Prefer the tables.patch method over the tables.update method because the tables.update method replaces the entire Table resource.

Update the expiration

As an example, change the expiration of the library_backup.books table snapshot as follows:

Console

  1. In the Cloud Console, go to the BigQuery page.

    Go to BigQuery

  2. In the Explorer pane, expand the project and dataset nodes of the library_backup.books table snapshot.

  3. Click the name of the table snapshot, in this case, books.

  4. In the books panel that opens, click into the Details tab, and then click Edit Details.

  5. In the Expiration time field, enter the new expiration time for the table snapshot.

  6. Click Save.

bq

Enter the following command in the Cloud Shell:

Go to Cloud Shell

bq update --expiration=3600 library_backup.books

API

Call the tables.patch method with the following parameters:

Parameter Value
projectId myProject
datasetId library_backup
tableId books
Request body
{
"expirationTime":"1908630376000"
}

Prefer the tables.patch method over the tables.update method because the tables.update method replaces the entire Table resource.

Update access

As an example, give the user cloudysanfrancisco@gmail.com access to view the data in the library_backup.books table snapshot as follows:

Console

  1. In the Cloud Console, go to the BigQuery page.

    Go to BigQuery

  2. In the Explorer pane, expand the project and dataset nodes of the library_backup.books table snapshot.

  3. In the books panel that opens, click Share, then click Add principal.

  4. In the Add principals pane that appears, enter the identifier of the principal you want to give access to the table snapshot, in this case, cloudysanfrancisco@gmail.com.

  5. In the Select a role dropdown, select the BigQuery Data Viewer role.

  6. Click Save.

bq

Enter the following command in the Cloud Shell:

Go to Cloud Shell

bq add-iam-policy-binding \
  --member="user:cloudysanfrancisco@gmail.com"\
  --role="roles/bigquery.dataViewer" library_backup.books

API

Call the tables.setIamPolicy method with the following parameters:

Parameter Value
Resource projects/myProject/datasets/library_backup/tables/books
Request body
{
    "policy": {
      "bindings": [
        {
          "members": [
            "user:cloudysanfrancisco@gmail.com"
          ],
          "role": "roles/bigquery.dataViewer"
        }
      ]
    }
  }

What's next