This page explains how to view labels on your BigQuery resources.
Overview
You can view labels by:
- Using the Cloud Console or classic BigQuery web UI
- Using the command-line tool's
bq show
command - Calling the
datasets.get
ortables.get
API methods - Using the client libraries
Because views are treated like table resources, you use the tables.get
method to get label information for both views and tables.
Required permissions
The permissions required for viewing labels depends on the type of resource you access.
Dataset permissions
At a minimum, to get information about a dataset, you must be granted
bigquery.datasets.get
permissions. The following predefined Cloud IAM
roles include bigquery.datasets.get
permissions:
bigquery.user
bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
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 get information
about a dataset.
For more information on Cloud IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Table and view permissions
At a minimum, to get information about tables or views, you must be granted
bigquery.tables.get
permissions. All predefined Cloud IAM roles
include bigquery.tables.get
permissions except for bigquery.user
and
bigquery.jobUser
.
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 get information
about tables and views in a dataset.
For more information on Cloud IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Job permissions
At a minimum, in order to get job data and metadata, you must be granted
bigquery.jobs.get
permissions. The following predefined Cloud IAM
role includes bigquery.jobs.get
permissions:
bigquery.admin
If you grant an account the bigquery.admin
role, the user can view all job
data in the project no matter who submitted the job.
The following roles are granted bigquery.jobs.get
permissions for self-created
jobs. These users can only view job data for jobs they submit:
bigquery.user
bigquery.jobUser
For more information on Cloud IAM roles and permissions in BigQuery, see Access control.
Viewing dataset, table, and view labels
To view a resource's labels:
Console
In the Cloud Console, select a dataset, table, or view. Job labels cannot be viewed in the Cloud Console.
For datasets, the dataset details page is automatically opened. For tables and views, click Details to open the details page. Label information appears in the information table for the resource.
Classic UI
In the web UI, select a dataset, table, or view. Job labels cannot be viewed in the classic web UI.
For datasets, the Dataset Details page is automatically opened. For tables and views, click Details to open the details page. Label information appears in the information table for the resource.
CLI
Use the bq show
command with the resource ID. The --format
flag can be
used to control the output. If the resource is in a project other than your
default project, add the project ID in the following format:
[PROJECT_ID]:[DATASET]
. For readability, the output is controlled by
setting the --format
flag to pretty
.
bq show --format=pretty [RESOURCE_ID]
Where [RESOURCE_ID]
is a valid dataset, table, view, or job ID.
Examples:
Enter the following command to display labels for mydataset
in your
default project.
bq show --format=pretty mydataset
The output looks like the following:
+-----------------+--------------------------------------------------------+---------------------+ | Last modified | ACLs | Labels | +-----------------+--------------------------------------------------------+---------------------+ | 11 Jul 19:34:34 | Owners: | department:shipping | | | projectOwners, | | | | Writers: | | | | projectWriters | | | | Readers: | | | | projectReaders | | +-----------------+--------------------------------------------------------+---------------------+
Enter the following command to display labels for mydataset.mytable
.
mydataset
is in myotherproject
, not your default project.
bq show --format=pretty myotherproject:mydataset.mytable
The output looks like the following for a clustered table:
+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+ | Last modified | Schema | Total Rows | Total Bytes | Expiration | Time Partitioning | Clustered Fields | Labels | +-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+ | 25 Jun 19:28:14 | |- timestamp: timestamp | 0 | 0 | 25 Jul 19:28:14 | DAY (field: timestamp, expirationMs: 86400000) | customer_id | org:dev | | | |- customer_id: string | | | | | | | | | |- transaction_amount: float | | | | | | | +-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+
API
Call the datasets.get
method or the tables.get
method. The response includes all labels associated with that resource.
Alternatively, you can use datasets.list
to view the labels for multiple datasets or tables.list
to view the labels for multiple tables and views.
Because views are treated like table resources, you use the tables.get
and tables.list
methods to view label information for both views and
tables.
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 .
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 .
Viewing job labels
After a job is submitted, the job labels do not appear in the
Cloud Console or the classic BigQuery web UI. To see the labels on a job,
issue the bq show -j [JOB_ID]
command or use the API or client libraries.
Console
You cannot view job labels by using the Cloud Console.
Classic UI
You cannot view job labels by using the classic BigQuery web UI.
CLI
To see the labels for a query job using the bq
command-line tool, enter
the bq show -j
command with the query job's job ID. The --format
flag
can be used to control the output. For example, if your query job has job ID
bqjob_r1234d57f78901_000023746d4q12_1
, enter the following command:
bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1
The output should look like the following:
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+ | Job Type | State | Start Time | Duration | User Email | Bytes Processed | Bytes Billed | Labels | +----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+ | query | SUCCESS | 03 Dec 15:00:41 | 0:00:00 | email@example.com | 255 | 10485760 | department:shipping | | | | | | | | | costcenter:logistics | +----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
API
Call the jobs.get
method. The response includes all labels associated with that resource.
What's next
- Learn how to add labels to 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.