Updating table snapshot metadata

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

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 minimum predefined role that you need to update a table snapshot's metadata is the following:

Role Resource
bigquery.dataEditor 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.

For example:

  • Update description. Change the description for the library_backup.books table snapshot to books-2022-03-04 as follows:

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 expiration. Change the expiration of the library_backup.books table snapshot as follows:

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. Give the user cloudysanfrancisco@gmail.com access to view the data in the library_backup.books table snapshot as follows:

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"
      }
    ]
  }
}

Table security

To control access to tables in BigQuery, see Introduction to table access controls.

What's next