Updating labels

This page explains how to update labels on BigQuery resources.

Updating dataset labels

A dataset label can be updated by:

• Using the Cloud Console or the classic BigQuery web UI
• Using the command-line tool's bq update command
• Calling the datasets.patch API method
• Using the client libraries

Required permissions

At a minimum, to update a dataset label, you must be granted bigquery.datasets.update permissions. The following predefined Cloud 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 update labels on a dataset.

For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.

Updating a dataset label

To update labels on a dataset:

Console

1. In the Cloud Console, select the dataset.

2. On the dataset details page, click the pencil icon to the right of Labels.

   

3. In the Edit labels dialog:

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

Classic UI

1. In the web UI, select the dataset.

2. On the Dataset Details page, to the right of Labels, click Edit.

   

3. In the Edit Labels dialog:

   • 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 OK.

     

CLI

To add additional labels or to update a dataset label, issue the bq update command with the set_label flag. Repeat the flag to add or update 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

Where:

• key:value corresponds to a key:value pair for a label that you want to add or update. If you specify the same key as an existing label, the value for the existing label is updated. The key must be unique.
• project_id is your project ID.
• dataset is the dataset you're updating.

Example:

To update the department label on mydataset, enter the bq update command and specify department as the label key. For example, to update the department:shipping label to department:logistics, enter the following command. mydataset is in myotherproject, not your default project.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

The output looks like the following.

Dataset 'myotherproject:mydataset' successfully updated.

API

To add additional labels or to update a label for an existing dataset, call the datasets.patch method and add to or update 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.

View on GitHub Feedback

import (
	"context"
	"fmt"

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

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(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()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

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.

View on GitHub Feedback

static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

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 labelDataset() {
  // Updates a label 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();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

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.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

Updating table and view labels

A label can be updated after a table or view is created by:

• Using the Cloud Console or the classic BigQuery web UI
• Using the command-line tool's bq update command
• Calling the tables.patch API method
  • Because views are treated like table resources, you use the tables.patch method to modify both views and tables.
• Using the client libraries

Required permissions

At a minimum, to update a table or view label, you must be granted bigquery.tables.update permissions. The following predefined Cloud IAM roles include bigquery.tables.update 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 update labels on their datasets and on tables and views in those datasets.

For more information on Cloud IAM roles and permissions in BigQuery, see Predefined roles and permissions.

Updating a table or view label

To update a table or view label:

Console

1. In the Cloud Console, select the table or view.

2. Click the Details tab, and then click the pencil icon to the right of Labels.

3. In the Edit labels dialog:

   • To apply additional labels, click Add label. Each key can be used only once per table or view, but you can use the same key in tables or views in different datasets.
   • Modify the existing keys or values to update a label.
   • Click Update to save your changes.

Classic UI

1. In the web UI, select the table or view.

2. On the details page, to the right of Labels, click Edit. This example shows the details for a table.

   

3. In the Edit Labels dialog:

   • To add additional labels, click Add Label. Each key can be used only once per table or view, but you can use the same key in tables or views in different datasets.
   • Modify the existing keys or values to update a label.

   • Click OK.

     

CLI

To add additional labels or to update a table or view label, issue the bq update command with the set_label flag. Repeat the flag to add or update 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

Where:

• key:value corresponds to a key:value pair for a label that you want to add or update. If you specify the same key as an existing label, the value for the existing label is updated. The key must be unique.
• project_id is your project ID.
• dataset is the dataset that contains the table or view you're updating.
• table_or_view is the name of the table or view you're updating.

Example:

To update the department label for mytable, enter the bq update command and specify department as the label key. For example, to update the department:shipping label to department:logistics for mytable, enter the following command. mytable is in myotherproject, not your default project.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

The output looks like the following:

Table 'myotherproject:mydataset.mytable' successfully updated.

API

To add additonal labels or to update a label for an existing table or view, call the tables.patch method and add to or update 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.

View on GitHub Feedback

import (
	"context"
	"fmt"

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

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(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()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

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.

View on GitHub Feedback

public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

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 labelTable() {
  // Adds a label to an existing table.

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

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

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()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

Updating job labels

Currently, updating a job label is not supported. To update the label on a job, resubmit the job with a new label specified.

Converting labels to tags

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 on a dataset, table, or view. You cannot convert a job label to 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.

Required permissions

At a minimum, the permissions required for converting a label to a tag are the same as those required to update labels.

• bigquery.datasets.update to convert a dataset label
• bigquery.tables.update to convert a table or view label

The following predefined Cloud IAM roles include bigquery.datasets.update permissions:

• bigquery.dataOwner
• bigquery.admin

The following predefined Cloud IAM roles include bigquery.tables.update 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 update labels on their datasets and on tables and views in those datasets.

For more information on Cloud IAM roles and permissions in BigQuery, see Predefined roles and permissions.

Converting a label to a tag

To convert a label to a tag:

Console

1. In the Cloud Console, select the dataset, table, or view.

2. For datasets, the dataset details page is automatically opened. For tables and views, click Details to open the details page.

   

3. On the details page, click the pencil icon to the right of Labels.

   

4. In the Edit labels dialog:

   • Delete the value for an existing label.
   • Click Update.

Classic UI

1. In the web UI, select the dataset, table, or view.

2. For datasets, the Dataset Details page is automatically opened. For tables and views, click Details to open the details page.

3. On the details page, to the right of Labels, click Edit.

4. In the Edit Labels dialog:

   • Delete the value for an existing label.

   • Click OK.

     

CLI

To convert a label to a tag, use the bq update command with the set_label flag. Specify the key, followed by a colon, but leave the value unspecified. This updates an existing label to a tag.

bq update \
--set_label key: \
resource_id

Where:

• key: is the label key that you want update to a tag.
• resource_id is 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 change the existing test_data:development label on mydataset to a tag. mydataset is in myotherproject, not your default project.

bq update --set_label test_data: myotherproject:mydataset

The output looks like the following:

Dataset 'myotherproject:mydataset' successfully updated.

API

To turn an existing label into a tag, call the datasets.patch method or the tables.patch method and replace the label values with the empty string ("") in the dataset resource or the table resource.

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 add labels to BigQuery resources.
• Learn how to view 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.