Viewing labels
This page explains how to view labels on your BigQuery resources.
You can view labels by:
- Using the Google Cloud console
- Querying
INFORMATION_SCHEMAviews - Using the bq command-line tool's
bq showcommand - Calling the
datasets.getortables.getAPI 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.
Before you begin
Grant Identity and Access Management (IAM) roles that give users the necessary permissions to perform each task in this document.
Required permissions
The permissions required for viewing labels depend on the types of resources you can access. To perform the tasks in this document, you need the following permissions.
Permissions to view dataset details
To view dataset details, you need the bigquery.datasets.get IAM permission.
Each of the following predefined IAM roles includes the permissions that you need in order to view dataset details:
roles/bigquery.userroles/bigquery.metadataViewerroles/bigquery.dataViewerroles/bigquery.dataOwnerroles/bigquery.dataEditorroles/bigquery.admin
Additionally, if you have the bigquery.datasets.create permission, you can view details of the datasets that you create.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Permissions to view table or view details
To view table or view details, you need the bigquery.tables.get IAM permission.
All predefined IAM roles include the permissions that you need in order to view table or view details except for roles/bigquery.user and roles/bigquery.jobUser.
Additionally, if you have the bigquery.datasets.create permission, you can view details of the tables and views in the datasets that you create.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
Permissions to view job details
To view job details, you need the bigquery.jobs.get IAM
permission.
Each of the following predefined IAM roles includes the permissions that you need in order to view job details:
roles/bigquery.admin(lets you view details of all the jobs in the project)roles/bigquery.user(lets you view details of your jobs)roles/bigquery.jobUser(lets you view details of your jobs)
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
View dataset, table, and view labels
To view a resource's labels, select one of the following options:
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.
Table details
SQL
Query the
INFORMATION_SCHEMA.SCHEMATA_OPTIONS view
to see the labels on a dataset, or the
INFORMATION_SCHEMA.TABLE_OPTIONS view
to see the labels on a table. For example, the following SQL query returns
the labels on the dataset named mydataset:
In the Google Cloud console, go to the BigQuery page.
In the query editor, enter the following statement:
SELECT * FROM INFORMATION_SCHEMA.SCHEMATA_OPTIONS WHERE schema_name='mydataset' ANDoption_name='labels';
Click Run.
For more information about how to run queries, see Run an interactive query.
bq
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.
bqshow--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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
import(
"context"
"fmt"
"io"
"cloud.google.com/go/bigquery"
)
// printDatasetLabels retrieves label metadata from a dataset and prints it to an io.Writer.
funcprintDatasetLabels(wio.Writer,projectID,datasetIDstring)error{
// projectID := "my-project-id"
// datasetID := "mydataset"
ctx:=context.Background()
client,err:=bigquery.NewClient(ctx,projectID)
iferr!=nil{
returnfmt.Errorf("bigquery.NewClient: %v",err)
}
deferclient.Close()
meta,err:=client.Dataset(datasetID).Metadata(ctx)
iferr!=nil{
returnerr
}
fmt.Fprintf(w,"Dataset %s labels:\n",datasetID)
iflen(meta.Labels)==0{
fmt.Fprintln(w,"Dataset has no labels defined.")
returnnil
}
fork,v:=rangemeta.Labels{
fmt.Fprintf(w,"\t%s:%s\n",k,v)
}
returnnil
}
Java
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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
importcom.google.cloud.bigquery.BigQuery ;
importcom.google.cloud.bigquery.BigQueryException ;
importcom.google.cloud.bigquery.BigQueryOptions ;
importcom.google.cloud.bigquery.Dataset ;
// Sample to get dataset labels
publicclass GetDatasetLabels{
publicstaticvoidrunGetDatasetLabels(){
// TODO(developer): Replace these variables before running the sample.
StringdatasetName="MY_DATASET_NAME";
getDatasetLabels(datasetName);
}
publicstaticvoidgetDatasetLabels(StringdatasetName){
try{
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests.
BigQuery bigquery=BigQueryOptions .getDefaultInstance().getService();
Dataset dataset=bigquery.getDataset (datasetName);
dataset
.getLabels()
.forEach((key,value)->System.out.println("Retrieved labels successfully"));
}catch(BigQueryException e){
System.out.println("Label was not found. \n"+e.toString());
}
}
}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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
// Import the Google Cloud client library
const{BigQuery}=require('@google-cloud/bigquery');
constbigquery=newBigQuery ();
asyncfunctiongetDatasetLabels(){
// Gets labels on a dataset.
/**
* TODO(developer): Uncomment the following lines before running the sample.
*/
// const datasetId = "my_dataset";
// Retrieve current dataset metadata.
constdataset=bigquery.dataset(datasetId);
const[metadata]=awaitdataset.getMetadata();
constlabels=metadata.labels;
console.log(`${datasetId} Labels:`);
for(const[key,value]ofObject.entries(labels)){
console.log(`${key}: ${value}`);
}
}
getDatasetLabels();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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
fromgoogle.cloudimport bigquery
# Construct a BigQuery client object.
client = bigquery .Client ()
# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"
dataset = client.get_dataset (dataset_id) # Make an API request.
# View dataset labels.
print("Dataset ID: {}".format(dataset_id))
print("Labels:")
if dataset.labels:
for label, value in dataset.labels.items ():
print("\t{}: {}".format(label, value))
else:
print("\tDataset has no labels defined.")View table labels
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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
import(
"context"
"fmt"
"io"
"cloud.google.com/go/bigquery"
)
// tableLabels demonstrates fetching metadata from a table and printing the Label metadata to an io.Writer.
functableLabels(wio.Writer,projectID,datasetID,tableIDstring)error{
// projectID := "my-project-id"
// datasetID := "mydataset"
// tableID := "mytable"
ctx:=context.Background()
client,err:=bigquery.NewClient(ctx,projectID)
iferr!=nil{
returnfmt.Errorf("bigquery.NewClient: %w",err)
}
deferclient.Close()
meta,err:=client.Dataset(datasetID).Table(tableID).Metadata(ctx)
iferr!=nil{
returnerr
}
fmt.Fprintf(w,"Table %s labels:\n",datasetID)
iflen(meta.Labels)==0{
fmt.Fprintln(w,"Table has no labels defined.")
returnnil
}
fork,v:=rangemeta.Labels{
fmt.Fprintf(w,"\t%s:%s\n",k,v)
}
returnnil
}
Java
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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
importcom.google.cloud.bigquery.BigQuery ;
importcom.google.cloud.bigquery.BigQueryException ;
importcom.google.cloud.bigquery.BigQueryOptions ;
importcom.google.cloud.bigquery.Table ;
importcom.google.cloud.bigquery.TableId ;
// Sample to get table labels
publicclass GetTableLabels{
publicstaticvoidmain(String[]args){
// TODO(developer): Replace these variables before running the sample.
StringdatasetName="MY_DATASET_NAME";
StringtableName="MY_TABLE_NAME";
getTableLabels(datasetName,tableName);
}
publicstaticvoidgetTableLabels(StringdatasetName,StringtableName){
try{
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests.
BigQuery bigquery=BigQueryOptions .getDefaultInstance().getService();
// This example table starts with existing label { color: 'green' }
Table table=bigquery.getTable (TableId.of(datasetName,tableName));
table
.getLabels()
.forEach((key,value)->System.out.println("Retrieved labels successfully"));
}catch(BigQueryException e){
System.out.println("Label was not deleted. \n"+e.toString());
}
}
}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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
// Import the Google Cloud client library
const{BigQuery}=require('@google-cloud/bigquery');
constbigquery=newBigQuery ();
asyncfunctiongetTableLabels(){
// Gets labels on a dataset.
/**
* TODO(developer): Uncomment the following lines before running the sample.
*/
// const datasetId = "my_dataset";
// const tableId = "my_table";
// Retrieve current dataset metadata.
consttable=bigquery.dataset(datasetId).table(tableId);
const[metadata]=awaittable.getMetadata();
constlabels=metadata.labels;
console.log(`${tableId} Labels:`);
for(const[key,value]ofObject.entries(labels)){
console.log(`${key}: ${value}`);
}
}
getTableLabels();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.
To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.
fromgoogle.cloudimport bigquery
client = bigquery .Client ()
# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"
table = client.get_table (table_id) # API Request
# View table labels
print(f"Table ID: {table_id}.")
if table.labels:
for label, value in table.labels.items ():
print(f"\t{label}: {value }")
else:
print("\tTable has no labels defined.")View job labels
To see the labels on a job, select one of the following options:
SQL
Query the
INFORMATION_SCHEMA.JOB_BY_* views
to see the labels on a job. For example, the following SQL query returns the
query text and labels on the jobs submitted by the current user in the
current project:
In the Google Cloud console, go to the BigQuery page.
In the query editor, enter the following statement:
SELECT query, labels FROM INFORMATION_SCHEMA.JOBS_BY_USER;
Click Run.
For more information about how to run queries, see Run an interactive query.
bq
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.
View reservation labels
To see the labels on a reservation, select one of the following options:
Console
In the Google Cloud console, go to the BigQuery page.
In the navigation menu, click Capacity management.
Click the Slot Reservations tab.
The labels for each reservation are listed in the Labels column.
SQL
Query the INFORMATION_SCHEMA.RESERVATIONS
views to see the labels on
a reservation. For example, the following SQL query returns the reservation
name and labels:
In the Google Cloud console, go to the BigQuery page.
In the query editor, enter the following statement:
SELECT reservation_name, labels FROM INFORMATION_SCHEMA.RESERVATIONS WHEREreservation_name=RESERVATION_NAME;
Replace the following:
RESERVATION_NAME: the name of the reservation.
Click Run.
For more information about how to run queries, see Run an interactive query.
bq
Use the bq show
command to view the reservation labels.
bqshow--format=prettyjson--reservation=true--location=LOCATIONRESERVATION_NAME
Replace the following:
LOCATION: the location of the reservation.RESERVATION_NAME: the name of the reservation.
The output looks similar to the following:
{
"autoscale": {
"maxSlots": "100"
},
"creationTime": "2023-10-26T15:16:28.196940Z",
"edition": "ENTERPRISE",
"labels": {
"department": "shipping"
},
"name": "projects/myproject/locations/US/reservations/myreservation",
"updateTime": "2025-06-05T19:37:28.125914Z"
}
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.