Viewing labels

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 bq command-line tool's bq show command
Calling the datasets.get or tables.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 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 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 IAM roles include bigquery.tables.get permissions except for bigquery.user and bigquery.jobUser.

For more information on 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 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 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.

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.

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.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// printDatasetLabels retrieves label metadata from a dataset and prints it to an io.Writer.
func printDatasetLabels(w io.Writer, projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	meta, err := client.Dataset(datasetID).Metadata(ctx)
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Dataset %s labels:\n", datasetID)
	if len(meta.Labels) == 0 {
		fmt.Fprintln(w, "Dataset has no labels defined.")
		return nil
	}
	for k, v := range meta.Labels {
		fmt.Fprintf(w, "\t%s:%s\n", k, v)
	}
	return nil
}

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.

View on GitHub Feedback

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get dataset labels
public class GetDatasetLabels {

  public static void runGetDatasetLabels() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    getDatasetLabels(datasetName);
  }

  public static void getDatasetLabels(String datasetName) {
    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.

View on GitHub Feedback

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getDatasetLabels() {
  // Gets labels on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();
  const labels = metadata.labels;

  console.log(`${datasetId} Labels:`);
  for (const [key, value] of Object.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.

View on GitHub Feedback


from google.cloud import 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.")

Viewing 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.

View on GitHub Feedback

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.
func tableLabels(w io.Writer, projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Table %s labels:\n", datasetID)
	if len(meta.Labels) == 0 {
		fmt.Fprintln(w, "Table has no labels defined.")
		return nil
	}
	for k, v := range meta.Labels {
		fmt.Fprintf(w, "\t%s:%s\n", k, v)
	}
	return nil
}

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.

View on GitHub Feedback

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;

// Sample to get table labels
public class GetTableLabels {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    getTableLabels(datasetName, tableName);
  }

  public static void getTableLabels(String datasetName, String tableName) {
    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.

View on GitHub Feedback

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getTableLabels() {
  // 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.
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();
  const labels = metadata.labels;

  console.log(`${tableId} Labels:`);
  for (const [key, value] of Object.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.

View on GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'
# table_id = 'my_table'

project = client.project
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)  # API Request

# View table labels
print("Table ID: {}".format(table_id))
print("Labels:")
if table.labels:
    for label, value in table.labels.items():
        print("\t{}: {}".format(label, value))
else:
    print("\tTable has no labels defined.")

==== YOURS //steffanyb:py-freeze:130:citc/google3/googledata/devsite/site-cloud/en/bigquery/docs/viewing-labels.md

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.

View on GitHub Feedback


from google.cloud import 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.")

<<<<

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.

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.

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.