This page explains how to label your BigQuery resources.
Adding dataset labels
A label can be added to a BigQuery dataset when it is created by
using the bq
command-line tool's bq mk
command or by calling the
datasets.insert
API
method. Currently, you cannot add a label to a dataset when it's created using
the Cloud Console.
This page discusses how to add a label to a dataset after it is created. For more information on adding a label when you create a dataset, see Creating a dataset.
A label can be added after a dataset is created by:
- Using the Cloud Console
- Using the
bq
command-line tool'sbq update
command - Calling the
datasets.patch
API method - Using the client libraries
When you add a label to a dataset, it does not propagate to resources within the dataset. Dataset labels are not inherited by tables or views. Also, when you add a label to a dataset, it is included in your storage billing data, but you will not see dataset labels in your job-related billing data.
Required permissions
At a minimum, to add a label to an existing dataset 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 add labels to their
datasets.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Adding a label to a dataset
To add a label to a dataset after it is created:
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:
- Click Add label
- Enter your key and value to add a label. 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 a label to an existing dataset, issue the bq update
command with
the set_label
flag. Repeat the flag to add 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
Replace the following:
KEY:VALUE
: a key-value pair for a label that you want to add. The key must be unique.PROJECT_ID
: your project ID.DATASET
: the dataset you're labeling.
Examples:
To add a label to track departments, enter the bq update
command and
specify department
as the label key. For example, to add a
department:shipping
label to mydataset
in your default project, enter:
bq update --set_label department:shipping mydataset
To add multiple labels to a dataset, repeat the set_label
flag and specify
a unique key for each label.For example, to add a department:shipping
label and cost_center:logistics
label to mydataset
in your default
project, enter:
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset
API
To add a label to an existing dataset, call the
datasets.patch
method and populate 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.
Adding table and view labels
A label can be added to a table or view when it is created by:
- Using the
bq
command-line tool'sbq mk
command - Calling the
tables.insert
API method
This page discusses how to add a label to an existing table or view. For more information on adding a label when you create a table or view, see Creating a table or Creating a view.
A label can be added 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 - Using the client libraries
Because views are treated like table resources, you use the tables.patch
method to modify both views and tables.
Required permissions
At a minimum, to add a label to an existing table or view, you must be granted
bigquery.tables.update
and bigquery.tables.get
permissions. The following
predefined IAM roles include bigquery.tables.update
and
bigquery.tables.get
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 add labels to
tables and views in their datasets.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Adding a label to a table or view
To add a label to an existing table or view:
Console
In the Cloud Console, select the table, or view.
Click the Details tab.
Click the pencil icon to the right of Labels.
In the Edit labels dialog:
- Click Add label
- Enter your key and value to add a label. 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 existing keys or values to update a label.
- Click Update to save your changes.
SQL
Data definition language (DDL) statements allow you to create and modify tables and views using standard SQL query syntax.
See more on Using Data Definition Language statements.
To add a label using a DDL statement in the Cloud Console:
Click Compose new query.
Type your DDL statement into the Query editor text area.
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("department", "shipping"), ("cost_center", "logistics")] )
Click Run query.
bq
To add a label to an existing table or view, issue the bq update
command
with the set_label
flag. Repeat the flag to add 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
Replace the following:
KEY:VALUE
: a key-value pair for a label that you want to add. The key must be unique.PROJECT_ID
: your project ID.DATASET
: the dataset that contains the table or view you're labeling.TABLE_OR_VIEW
: the name of the table or view you're labeling.
Examples:
To add a table label that tracks departments, enter the bq update
command
and specify department
as the label key. For example, to add a
department:shipping
label to mytable
in your default project, enter:
bq update --set_label department:shipping mydataset.mytable
To add a view label that tracks departments, enter the bq update
command
and specify department
as the label key. For example, to add a
department:shipping
label to myview
in your default project, enter:
bq update --set_label department:shipping mydataset.myview
To add multiple labels to a table or view, repeat the set_label
flag and
specify a unique key for each label. For example, to add a
department:shipping
label and cost_center:logistics
label to mytable
in your default project, enter:
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset.mytable
API
To add a label to an existing table or view, call the
tables.patch
method and populate 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.
Adding job labels
Labels can be added to query jobs via the command line by using the
bq
command-line tool's --label
flag. The bq
tool supports adding
labels only to query jobs.
You can also add a label to a job when it's submitted via the API by specifying
the labels
property in the job configuration when you call the
jobs.insert
method. The API
can be used to add labels to any job type.
You cannot add labels to or update labels on pending, running, or completed jobs.
When you add a label to a job, the label is included in your billing data.
Required permissions
No special permissions are required for adding a label to a job. If you have
bigquery.jobs.create
permissions, you can add a label to your job when you
submit it.
At a minimum, to run a job, you must have bigquery.jobs.create
permissions.
bigquery.jobs.create
permissions are required for jobs that are automatically
created by BigQuery, and they are required for jobs that you
run programmatically.
The following predefined IAM roles include bigquery.jobs.create
permissions:
bigquery.user
bigquery.jobUser
bigquery.admin
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Adding a label to a job
To add a label to a job:
Console
Adding labels to jobs is not supported by the Cloud Console.
bq
To add a label to a query job, issue the bq query
command with
the --label
flag. Repeat the flag to add multiple labels. The
--nouse_legacy_sql
flag indicates that your query is in standard SQL
syntax.
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
Replace the following:
KEY:VALUE
: a key-value pair for a label that you want to add to the query job. The key must be unique. To add multiple labels to a query job, repeat the--label
flag and specify a unique key for each label.QUERY
: a valid standard SQL query.
Examples:
To add a label to a query job, enter:
bq query \
--label department:shipping \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
To add multiple labels to a query job, repeat the --label
flag and
specify a unique key for each label. For example, to add a
department:shipping
label and cost_center:logistics
label to a query
job, enter:
bq query \
--label department:shipping \
--label cost_center:logistics \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
API
To add a label to a job, call the
jobs.insert
method and populate the labels
property for the job configuration.
You can use the API to add labels to any job type.
Adding a tag
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.
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.
To add a tag:
Console
In the Cloud Console, select the appropriate resource (a 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:
- Click Add label.
- Enter a new key and leave the value blank. To apply additional tags, click Add label and repeat.
- Click Update to save your changes.
SQL
Data definition language (DDL) statements let you create and modify tables and views using standard SQL query syntax.
See more on Using Data Definition Language statements.
To add a tag using a DDL statement in the Cloud Console:
Click Compose new query.
Type your DDL statement into the Query editor text area.
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("tag1", ""), ("tag2", "")] )
Click Run query.
bq
To add a tag to an existing resource, use the bq update
command with the
set_label
flag. Specify the key, followed by a colon, but leave the value
unspecified.
bq update --set_label KEY: RESOURCE_ID
Replace the following:
KEY:
: the label key that you want to use as a tag.RESOURCE_ID
: 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 create a test_data
tag for
mydataset.mytable
. mydataset
is in your default project.
bq update --set_label test_data: mydataset
API
Call the datasets.patch
method or the tables.patch
method and add labels with the value set to the empty string (""
) in the
dataset resource
or the table resource.
You can turn existing labels into tags by replacing their values with the
empty string.
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 view labels on BigQuery resources.
- Learn how to update 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.