Managing labels

To help organize your BigQuery resources, you can add labels to your datasets, tables, and views. Labels are key-value pairs that you can attach to a resource. When you create BigQuery resources, labels are optional.

After labeling your resources, you can search for them based on label values. For example, you can use labels to group datasets by purpose, environment, department, and so on.

This page explains how to manage labels on BigQuery resources, including how to update and remove labels.

For information on adding labels to BigQuery resources and on using labels in BigQuery, see Adding and using labels.

What are labels?

A label is a key-value pair that helps you organize your Google Cloud Platform BigQuery resources. You can attach a label to each resource, then filter the resources based on their labels. Information about labels is forwarded to the billing system, so you can break down your billing charges by label.

Common uses of labels

Here are some common use cases for labels:

  • Team or cost center labels: Add labels based on team or cost center to distinguish BigQuery resources owned by different teams (for example, team:research and team:analytics). You can use this type of label for cost accounting or budgeting.

  • Component labels: For example, component:redis, component:frontend, component:ingest, and component:dashboard.

  • Environment or stage labels: For example, environment:production and environment:test.

  • Owner or contact labels: Add labels based on the owner or a primary contact for BigQuery resources.

  • State labels: For example, state:active, state:readytodelete, and state:archive.

Requirements for labels

The labels applied to a resource must meet the following requirements:

  • Each resource can have multiple labels, up to a maximum of 64.
  • Each label must be a key-value pair.
  • Keys have a minimum length of 1 character and a maximum length of 63 characters, and cannot be empty. Values can be empty, and have a maximum length of 63 characters.
  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed.
  • The key portion of a label must be unique. However, you can use the same key with multiple resources.
  • Keys must start with a lowercase letter or international character.

Updating dataset labels

A dataset label can be updated by using the BigQuery web UI, the command-line tool's bq update command, or by calling the datasets.patch API method.

Required permissions

To update a dataset label, you must have OWNER access at the dataset level, or you must be assigned a project-level IAM role that includes bigquery.datasets.update permissions. The following predefined, project-level IAM roles include bigquery.datasets.update permissions:

In addition, because the bigquery.user role has bigquery.datasets.create permissions, a user assigned to the bigquery.user role can update any dataset that user creates. When a user assigned to the bigquery.user role creates a dataset, that user is given OWNER access to the dataset. OWNER access to a dataset gives the user full control over it.

For more information on IAM roles and permissions in BigQuery, see Access Control. For more information on dataset-level roles, see Primitive roles for datasets.

Updating a dataset label

To update labels for an existing dataset:

Web UI

  1. In the web UI, select the dataset.

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

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

      New label

Command-line

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.

Examples:

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

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 . 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

This sample uses the Google HTTP Client Library for Java to send a request to the BigQuery API. 
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));
}

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 . 

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

assert dataset.labels == {}
labels = {'color': 'green'}
dataset.labels = labels

dataset = client.update_dataset(dataset, ['labels'])  # API request

assert dataset.labels == labels

Updating table and view labels

A label can be updated after a table or view is created by using the BigQuery web UI, the command-line tool's bq update command, or by 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.

Required permissions

To update a table or view label, you must have OWNER access at the dataset level, or you must be assigned a project-level IAM role that includes bigquery.tables.update permissions. The following predefined, project-level IAM roles include bigquery.tables.update permissions:

In addition, because the bigquery.user role has bigquery.datasets.create permissions, a user assigned to the bigquery.user role can update tables and views in any dataset that user creates. When a user assigned to the bigquery.user role creates a dataset, that user is given OWNER access to the dataset. OWNER access to a dataset gives the user full control over it and the tables and views in it.

For more information on IAM roles and permissions in BigQuery, see Access Control. For more information on dataset-level roles, see Primitive roles for datasets.

Updating a table or view label

To update a table or view label:

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

    Edit labels

  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.

      New label

Command-line

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.

Examples:

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

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 . 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

This sample uses the Google HTTP Client Library for Java to send a request to the BigQuery API. 
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));
}

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 . 

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

Deleting labels

A label can be removed from a dataset, table, or view by using the BigQuery web UI, the command-line tool's bq update command, or by calling the datasets.patch or tables.patch API method.

Deleting a dataset label

To remove a dataset label, use the BigQuery web UI, the command-line tool's bq update command, or call the datasets.patch API method.

Required permissions

To remove a dataset label, you must have OWNER access at the dataset level, or you must be assigned a project-level IAM role that includes bigquery.datasets.update permissions. The following predefined, project-level IAM roles include bigquery.datasets.update permissions:

In addition, because the bigquery.user role has bigquery.datasets.create permissions, a user assigned to the bigquery.user role can update any dataset that user creates. When a user assigned to the bigquery.user role creates a dataset, that user is given OWNER access to the dataset. OWNER access to a dataset gives the user full control over it.

For more information on IAM roles and permissions in BigQuery, see Access Control. For more information on dataset-level roles, see Primitive roles for datasets.

Deleting a dataset label

To remove a label from a dataset:

Web 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:

    • Click the delete icon (X) for each label you want to remove.

    • Click OK.

      Delete label

Command-line

To remove a dataset label, issue the bq update command with the clear_label flag. Repeat the flag to remove 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 --clear_label [KEY] [PROJECT_ID]:[DATASET]

Where:

  • [KEY] is the key for a label that you want to remove.
  • [PROJECT_ID] is your project ID.
  • [DATASET] is the dataset you're updating.

Examples:

To remove the department:shipping label from mydataset, enter the bq update command with the --clear_label flag. mydataset is in your default project.

    bq update --clear_label department mydataset

To remove the department:shipping label from mydataset in myotherproject, enter the bq update command with the --clear_label flag.

    bq update --clear_label department myotherproject:mydataset

To remove multiple labels from a dataset, repeat the clear_label flag and specify each label's key. For example, to remove the department:shipping label and cost_center:logistics labels from mydataset in your default project, enter:

    bq update --clear_label department --clear_label cost_center mydataset

API

To remove a particular label for an existing dataset, call the datasets.patch method and update the labels property for the dataset resource by setting the label's key value to null.

To remove all labels from a dataset, call the datasets.patch method and remove the labels property.

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 . 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.DatasetMetadataToUpdate{}
update.DeleteLabel("color")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

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 . 

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

# This example dataset starts with one label
assert dataset.labels == {'color': 'green'}
# To delete a label from a dataset, set its value to None
dataset.labels['color'] = None

dataset = client.update_dataset(dataset, ['labels'])  # API request

assert dataset.labels == {}

Deleting a table or view label

To remove a table or view label, use the BigQuery web UI, the command-line tool's bq update command, or call the tables.patch API method. Because views are treated like table resources, you use the tables.patch method to modify both views and tables.

Required permissions

To remove a table or view label, you must have OWNER access at the dataset level, or you must be assigned a project-level IAM role that includes bigquery.tables.update permissions. The following predefined, project-level IAM roles include bigquery.tables.update permissions:

In addition, because the bigquery.user role has bigquery.datasets.create permissions, a user assigned to the bigquery.user role can update a table or view in any dataset that user creates. When a user assigned to the bigquery.user role creates a dataset, that user is given OWNER access to the dataset. OWNER access to a dataset gives the user full control over it and all the tables and views in it.

For more information on IAM roles and permissions in BigQuery, see Access Control. For more information on dataset-level roles, see Primitive roles for datasets.

Deleting a table or view label

To remove a label from a table or view:

Web UI

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

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

  3. In the Edit Labels dialog:

    • Click the delete icon (X) for each label you want to remove.

    • Click OK.

      Delete label

Command-line

To remove a label from a table or view, issue the bq update command with the clear_label flag. Repeat the flag to remove 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 --clear_label [KEY] [PROJECT_ID]:[TABLE_OR_VIEW]

Where:

  • [KEY] is the key for a label that you want to remove.
  • [PROJECT_ID] is your project ID.
  • [DATASET] is the dataset you're updating.
  • [TABLE_OR_VIEW] is the name of the table or view you're updating.

Examples:

To remove the department:shipping label from mydataset.mytable, enter the bq update command with the --clear_label flag. mydataset is in your default project.

    bq update --clear_label department mydataset.mytable

To remove the department:shipping label from mydataset.myview in myotherproject, enter the bq update command with the --clear_label flag.

    bq update --clear_label department myotherproject:mydataset.myview

To remove multiple labels from a table or view, repeat the clear_label flag and specify each label's key. For example, to remove the department:shipping label and cost_center:logistics label from mydataset.mytable in your default project, enter:

    bq update --clear_label department --clear_label cost_center mydataset.mytable

API

To remove a particular label for an existing table or view, call the tables.patch method and update the labels property for the table resource by setting the label's key value to null.

To remove all labels from a table or view, call the tables.patch method and remove the labels property.

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.

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 run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
tbl := client.Dataset(datasetID).Table(tableID)
meta, err := tbl.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.TableMetadataToUpdate{}
update.DeleteLabel("color")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

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 . 

# 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

# This example table starts with one label
assert table.labels == {'color': 'green'}
# To delete a label from a table, set its value to None
table.labels['color'] = None

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

assert table.labels == {}

Deleting job labels

Currently, deleting a label from an existing job is not supported.

Converting a label to a tag

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.

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.

To convert a label to a tag:

Web UI

  1. In the web UI, select the appropriate resource (a 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.

      Add tag

Command-line

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

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

Was this page helpful? Let us know how we did:

Send feedback about...

This page
Documentation feedback
BigQuery
Product feedback
Need help? Visit our support page.