Viewing labels

This page explains how to view labels on your BigQuery resources.

You can view labels by:

  • Using the Google Cloud console
  • QueryingINFORMATION_SCHEMA views
  • Using the bq command-line tool'sbq show command
  • Calling thedatasets.getortables.get API methods
  • Using the client libraries

Because views are treated like table resources, you use thetables.getmethod to get label information for both views and tables.

Before you begin

Grant Identity and Access Management (IAM) roles that give users the necessary permissionsto perform each task in this document.

Required permissions

The permissions required for viewing labels depend on the types of resourcesyou can access. To perform the tasks in this document, you need the followingpermissions.

Permissions to view dataset details

To view dataset details, you need thebigquery.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.user
  • roles/bigquery.metadataViewer
  • roles/bigquery.dataViewer
  • roles/bigquery.dataOwner
  • roles/bigquery.dataEditor
  • roles/bigquery.admin

Additionally, if you have thebigquery.datasets.create permission, you can view details of the datasets that you create.

For more information on IAM roles and permissions inBigQuery, seePredefined roles and permissions.

Permissions to view table or view details

To view table or view details, you need thebigquery.tables.get IAM permission.

All predefined IAM roles include the permissions that you need in order to view table or view detailsexcept forroles/bigquery.user androles/bigquery.jobUser.

Additionally, if you have thebigquery.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 inBigQuery, seePredefined roles and permissions.

Permissions to view job details

To view job details, you need thebigquery.jobs.get IAMpermission.

Each of the following predefined IAM roles includes thepermissions 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 inBigQuery, seePredefined roles and permissions.

View dataset, table, and view labels

To view a resource's labels, select one of the following options:

Console

  1. For datasets, the dataset details page is automatically opened. Fortables and views, clickDetails to open the details page. Labelinformation appears in the information table for the resource.

    Table details

SQL

Query theINFORMATION_SCHEMA.SCHEMATA_OPTIONS viewto see the labels on a dataset, or theINFORMATION_SCHEMA.TABLE_OPTIONS viewto see the labels on a table. For example, the following SQL query returnsthe labels on the dataset namedmydataset:

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    SELECT*FROMINFORMATION_SCHEMA.SCHEMATA_OPTIONSWHEREschema_name='mydataset'ANDoption_name='labels';

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Use thebq show command with the resource ID. The--format flag can beused to control the output. If the resource is in a project other than yourdefault project, add the project ID in the following format:[PROJECT_ID]:[DATASET]. For readability, the output is controlled bysetting the--format flag topretty.

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 formydataset in yourdefault 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 formydataset.mytable.mydataset is inmyotherproject, 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 thedatasets.getmethod or thetables.getmethod. The response includes all labels associated with that resource.

Alternatively, you can usedatasets.listto view the labels for multiple datasets ortables.listto view the labels for multiple tables and views.

Because views are treated like table resources, you use thetables.getandtables.list methods to view label information for both views andtables.

Go

Before trying this sample, follow theGo setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryGo API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet 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 theJava setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryJava API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet 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 labelspublicclassGetDatasetLabels{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.BigQuerybigquery=BigQueryOptions.getDefaultInstance().getService();Datasetdataset=bigquery.getDataset(datasetName);dataset.getLabels().forEach((key,value)->System.out.println("Retrieved labels successfully"));}catch(BigQueryExceptione){System.out.println("Label was not found. \n"+e.toString());}}}

Node.js

Before trying this sample, follow theNode.js setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryNode.js API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

// Import the Google Cloud client libraryconst{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 thePython setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryPython API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

fromgoogle.cloudimportbigquery# 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:")ifdataset.labels:forlabel,valueindataset.labels.items():print("\t{}:{}".format(label,value))else:print("\tDataset has no labels defined.")

View table labels

Go

Before trying this sample, follow theGo setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryGo API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet 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 theJava setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryJava API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet 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 labelspublicclassGetTableLabels{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.BigQuerybigquery=BigQueryOptions.getDefaultInstance().getService();// This example table starts with existing label { color: 'green' }Tabletable=bigquery.getTable(TableId.of(datasetName,tableName));table.getLabels().forEach((key,value)->System.out.println("Retrieved labels successfully"));}catch(BigQueryExceptione){System.out.println("Label was not deleted. \n"+e.toString());}}}

Node.js

Before trying this sample, follow theNode.js setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryNode.js API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

// Import the Google Cloud client libraryconst{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 thePython setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryPython API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

fromgoogle.cloudimportbigqueryclient=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 labelsprint(f"Table ID:{table_id}.")iftable.labels:forlabel,valueintable.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 theINFORMATION_SCHEMA.JOB_BY_* viewsto see the labels on a job. For example, the following SQL query returns thequery text and labels on the jobs submitted by the current user in thecurrent project:

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    SELECTquery,labelsFROMINFORMATION_SCHEMA.JOBS_BY_USER;

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

To see the labels for a query job using the bq command-line tool, enterthebq show -j command with the query job's job ID. The--format flagcan be used to control the output. For example, if your query job has job IDbqjob_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 thejobs.getmethod. 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

  1. In the Google Cloud console, go to the BigQuery page.

    Go to BigQuery

  2. In the navigation menu, clickCapacity management.

  3. Click theSlot Reservations tab.

  4. The labels for each reservation are listed in theLabels column.

SQL

Query theINFORMATION_SCHEMA.RESERVATIONSviews to see the labels ona reservation. For example, the following SQL query returns the reservationname and labels:

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    SELECTreservation_name,labelsFROMINFORMATION_SCHEMA.RESERVATIONSWHEREreservation_name=RESERVATION_NAME;

    Replace the following:

    • RESERVATION_NAME: the name of the reservation.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Use thebq showcommand 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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.