This page explains how to update labels on BigQuery resources.
Updating dataset labels
A dataset label can be updated by:
- Using the Cloud Console
- Using the
bq
command-line tool'sbq update
command - Calling the
datasets.patch
API method - Using the client libraries
Required permissions
At a minimum, to update a dataset label, you must be granted
bigquery.datasets.update
permissions. The following predefined
IAM roles include bigquery.datasets.update
permissions:
bigquery.dataOwner
bigquery.admin
In addition, if a user has bigquery.datasets.create
permissions, when that
user creates a dataset, they are granted bigquery.dataOwner
access to it.
bigquery.dataOwner
access gives the user the ability to update labels on
a dataset.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Updating a dataset label
To update labels on a dataset:
Console
In the Cloud Console, select the dataset.
On the dataset details page, click the pencil icon to the right of Labels.
In the Edit labels dialog:
- To apply additional labels, click Add label. Each key can be used only once per dataset, but you can use the same key in different datasets in the same project.
- Modify the existing keys or values to update a label.
- Click Update to save your changes.
bq
To add additional labels or to update a dataset label, issue the bq update
command with the set_label
flag. Repeat the flag to add or update multiple
labels.
If the dataset is in a project other than your default project, add the
project ID to the dataset in the following format: [PROJECT_ID]:[DATASET]
.
bq update \ --set_label key:value \ project_id:dataset
Where:
- key:value corresponds to a key:value pair for a label that you want to add or update. If you specify the same key as an existing label, the value for the existing label is updated. The key must be unique.
- project_id is your project ID.
- dataset is the dataset you're updating.
Example:
To update the department
label on mydataset
, enter the bq update
command and specify department
as the label key. For example, to update
the department:shipping
label to department:logistics
, enter the
following command. mydataset
is in myotherproject
, not your default
project.
bq update \
--set_label department:logistics \
myotherproject:mydataset
The output looks like the following.
Dataset 'myotherproject:mydataset' successfully updated.
API
To add additional labels or to update a label for an existing dataset, call
the datasets.patch
method and add to or update the labels
property for the
dataset resource.
Because the datasets.update
method replaces the entire dataset resource,
the datasets.patch
method is preferred.
Go
Before trying this sample, follow the Go setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Go API reference documentation.
Java
This sample uses the Google HTTP Client Library for Java to send a request to the BigQuery API.
Before trying this sample, follow the Java setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Node.js API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Python API reference documentation.
Updating table and view labels
A label can be updated after a table or view is created by:
- Using the Cloud Console
- Using the
bq
command-line tool'sbq update
command - Calling the
tables.patch
API method- Because views are treated like table resources, you use the
tables.patch
method to modify both views and tables.
- Because views are treated like table resources, you use the
- Using the client libraries
Required permissions
At a minimum, to update a table or view label, you must be granted
bigquery.tables.update
permissions. The following predefined
IAM roles include bigquery.tables.update
permissions:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
In addition, if a user has bigquery.datasets.create
permissions, when that
user creates a dataset, they are granted bigquery.dataOwner
access to it.
bigquery.dataOwner
access gives the user the ability to update labels on
their datasets and on tables and views in those datasets.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Updating a table or view label
To update a table or view label:
Console
In the Cloud Console, select the table or view.
Click the Details tab, and then click the pencil icon to the right of Labels.
In the Edit labels dialog:
- To apply additional labels, click Add label. Each key can be used only once per table or view, but you can use the same key in tables or views in different datasets.
- Modify the existing keys or values to update a label.
- Click Update to save your changes.
bq
To add additional labels or to update a table or view label, issue the bq
update
command with the set_label
flag. Repeat the flag to add or update
multiple labels.
If the table or view is in a project other than your default project, add
the project ID to the dataset in the following format:
project_id:dataset
.
bq update \ --set_label key:value \ project_id:dataset.table_or_view
Where:
- key:value corresponds to a key:value pair for a label that you want to add or update. If you specify the same key as an existing label, the value for the existing label is updated. The key must be unique.
- project_id is your project ID.
- dataset is the dataset that contains the table or view you're updating.
- table_or_view is the name of the table or view you're updating.
Example:
To update the department
label for mytable
, enter the bq update
command and specify department
as the label key. For example, to update
the department:shipping
label to department:logistics
for mytable
,
enter the following command. mytable
is in myotherproject
, not your
default project.
bq update \
--set_label department:logistics \
myotherproject:mydataset.mytable
The output looks like the following:
Table 'myotherproject:mydataset.mytable' successfully updated.
API
To add additonal labels or to update a label for an existing table or view,
call the tables.patch
method and add to or update the labels
property for the table resource.
Because views are treated like table resources, you use the tables.patch
method to modify both views and tables.
Because the tables.update
method replaces the entire dataset resource, the
tables.patch
method is preferred.
Go
Before trying this sample, follow the Go setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Go API reference documentation.
Java
This sample uses the Google HTTP Client Library for Java to send a request to the BigQuery API.
Before trying this sample, follow the Java setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Node.js API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Python API reference documentation.
Updating job labels
Currently, updating a job label is not supported. To update the label on a job, resubmit the job with a new label specified.
Converting labels to tags
A label that has a key with an empty value is used as a tag. You can create a new label with no value, or you can turn an existing label into a tag on a dataset, table, or view. You cannot convert a job label to a tag.
Tags can be useful in situations where you are labeling a resource, but you do
not need the key:value
format. For example, if you have a table that contains
test data that is used by multiple groups (support, development, and so on), you
can add a test_data
tag to the table to identify it.
Required permissions
At a minimum, the permissions required for converting a label to a tag are the same as those required to update labels.
bigquery.datasets.update
to convert a dataset labelbigquery.tables.update
to convert a table or view label
The following predefined IAM roles include
bigquery.datasets.update
permissions:
bigquery.dataOwner
bigquery.admin
The following predefined IAM roles include
bigquery.tables.update
permissions:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
In addition, if a user has bigquery.datasets.create
permissions, when that
user creates a dataset, they are granted bigquery.dataOwner
access to it.
bigquery.dataOwner
access gives the user the ability to update labels on their
datasets and on tables and views in those datasets.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Converting a label to a tag
To convert a label to a tag:
Console
In the Cloud Console, select the dataset, table, or view.
For datasets, the dataset details page is automatically opened. For tables and views, click Details to open the details page.
On the details page, click the pencil icon to the right of Labels.
In the Edit labels dialog:
- Delete the value for an existing label.
- Click Update.
bq
To convert a label to a tag, use the bq update
command with the
set_label
flag. Specify the key, followed by a colon, but leave the value
unspecified. This updates an existing label to a tag.
bq update \ --set_label key: \ resource_id
Where:
- key: is the label key that you want update to a tag.
- resource_id is a valid dataset, table, or view name. If the
resource is in a project other than your default project, add the project ID
in the following format:
project_id:dataset
.
Examples:
Enter the following command to change the existing test_data:development
label on mydataset
to a tag. mydataset
is in myotherproject
, not your
default project.
bq update --set_label test_data: myotherproject:mydataset
The output looks like the following:
Dataset 'myotherproject:mydataset' successfully updated.
API
To turn an existing label into a tag, call the datasets.patch
method or the tables.patch
method and replace the label values with the empty string (""
) in the
dataset resource
or the table resource.
Because views are treated like table resources, you use the tables.patch
method to modify both views and tables. Also, because the tables.update
method replaces the entire dataset resource, the tables.patch
method is
preferred.
What's next
- Learn how to add labels to BigQuery resources.
- Learn how to view labels on BigQuery resources.
- Learn how to filter resources using labels.
- Learn how to delete labels on BigQuery resources.
- Read about Using labels in the Resource Manager documentation.