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

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

Console

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

    Go to BigQuery

  2. In the Explorer pane, expand the project and dataset nodes of the table snapshot you want to update.

  3. Click the name of the table snapshot.

  4. In the snapshot pane that appears, click 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="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 the tables.patch method with the following parameters:

Parameter Value
projectId The project ID of the project that contains the snapshot.
datasetId The name of the dataset that contains the snapshot.
tableId The name of the snapshot.
Request body description field Text describing the snapshot. For example, Snapshot after table schema change X.

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

Update the expiration

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

Console

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

    Go to BigQuery

  2. In the Explorer pane, expand the project and dataset nodes of the table snapshot you want to update.

  3. Click the name of the table snapshot.

  4. In the snapshot pane that appears, click 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=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 the tables.patch method with the following parameters:

Parameter Value
projectId The project ID of the project that contains the snapshot.
datasetId The name of the dataset that contains the snapshot.
tableId The name of the snapshot.
Request body expirationTime field The time when the snapshot expires, in milliseconds since the epoch.

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

Update access

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

Console

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

    Go to BigQuery

  2. In the Explorer pane, expand the project and dataset nodes of the table snapshot you want to update.

  3. Click the name of the table snapshot.

  4. In the snapshot pane that appears, click Share, then click Add principal.

  5. In the Add principals pane that appears, enter the identifier of the principal you want to give access to the table snapshot.

  6. In the Select a role dropdown, choose BigQuery, then BigQuery Data Viewer.

  7. Click Save.

bq

Enter the following command in the Cloud Shell:

Go to Cloud Shell 

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

Replace the following:

  • PRINCIPAL: the principal 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 the tables.setIamPolicy method with the following parameters:

Parameter Value
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: the principal you want to give access to the table snapshot.

What's next