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
In the Google Cloud console, go to the BigQuery page.
In the Explorer pane, expand the project and dataset nodes of the table snapshot you want to update.
Click the name of the table snapshot.
In the snapshot pane that appears, click the Details tab, and then click Edit Details.
In the Description field, add or update the description for the table snapshot.
Click Save.
bq
Enter the following command in the 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
In the Google Cloud console, go to the BigQuery page.
In the Explorer pane, expand the project and dataset nodes of the table snapshot you want to update.
Click the name of the table snapshot.
In the snapshot pane that appears, click the Details tab, and then click Edit Details.
In the Expiration time field, enter the new expiration time for the table snapshot.
Click Save.
bq
Enter the following command in the 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
In the Google Cloud console, go to the BigQuery page.
In the Explorer pane, expand the project and dataset nodes of the table snapshot you want to update.
Click the name of the table snapshot.
In the snapshot pane that appears, click Share, then click Add principal.
In the Add principals pane that appears, enter the identifier of the principal you want to give access to the table snapshot.
In the Select a role dropdown, choose BigQuery, then BigQuery Data Viewer.
Click Save.
bq
Enter the following command in the 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
- List the table snapshots in a dataset.
- View the metadata for a table snapshot.
- Delete a table snapshot.