Adding labels to resources

This page explains how to label your BigQuery resources.

Adding dataset labels

A label can be added to a BigQuery dataset when it is created by using the command-line tool's bq mk command or by calling the datasets.insert API method. Currently, you cannot add a label to a dataset when it's created via the GCP Console or the classic BigQuery web UI.

This page discusses how to add a label to a dataset after it is created. For more information on adding a label when you create a dataset, see Creating a dataset.

A label can be added after a dataset is created by:

• Using the GCP 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

When you add a label to a dataset, it does not propagate to resources within the dataset. Dataset labels are not inherited by tables or views. Also, when you add a label to a dataset, it is included in your storage billing data, but you will not see dataset labels in your job-related billing data.

Required permissions

At a minimum, to add a label to an existing dataset 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 add labels to their datasets.

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

Adding a label to a dataset

To add a label to a dataset after it is created:

Console

1. In the GCP 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:

   • Click Add label
   • Enter your key and value to add a label. 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 BigQuery web UI, select the dataset.

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

   

3. In the Edit Labels dialog:

   • Enter your key and value to add a label. 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 a label to an existing dataset, issue the bq update command with the set_label flag. Repeat the flag to add 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. The key must be unique.
• project_id is your project ID.
• dataset is the dataset you're labeling.

Examples:

To add a label to track departments, enter the bq update command and specify department as the label key. For example, to add a department:shipping label to mydataset in your default project, enter:

    bq update --set_label department:shipping mydataset

To add multiple labels to a dataset, repeat the set_label flag and specify a unique key for each label.For example, to add a department:shipping label and cost_center:logistics label to mydataset in your default project, enter:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset

API

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

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

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));
}

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_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

Adding table and view labels

A label can be added to a table or view when it is created by:

• Using the command-line tool's bq mk command
• Calling the tables.insert API method

This page discusses how to add a label to an existing table or view. For more information on adding a label when you create a table or view, see Creating a table or Creating a view.

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

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

Because views are treated like table resources, you use the tables.patch method to modify both views and tables.

Note: Table and view labels are not included in billing data.

Required permissions

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

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

Adding a label to a table or view

To add a label to an existing table or view:

Console

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

2. Click the Details tab.

   

3. Click the pencil icon to the right of Labels.

   

4. In the Edit labels dialog:

   • Click Add label
   • Enter your key and value to add a label. 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 existing keys or values to update a label.
   • Click Update to save your changes.

DDL

Data definition language (DDL) statements allow you to create and modify tables and views using standard SQL query syntax.

See more on Using Data Definition Language statements.

Beta

Esta es una versión Beta de BigQuery support for the ALTER TABLE SET OPTIONS statement. En esta función se pueden producir cambios que generen incompatibilidad con versiones anteriores y is sujetas a ningún ANS o política de baja del servicio.

To add a label using a DDL statement in the GCP Console:

1. Click Compose new query.

2. Type your DDL statement into the Query editor text area.

    ALTER TABLE mydataset.mytable
    SET OPTIONS (
      labels=[("department", "shipping"), ("cost_center", "logistics")]
    )
    

3. Click Run query.

Classic UI

1. In the BigQuery 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:

   • Enter your key and value to add a label. 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.

   • Click OK.

     

CLI

To add a label to an existing table or view, issue the bq update command with the set_label flag. Repeat the flag to add 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. The key must be unique.
• project_id is your project ID.
• dataset is the dataset that contains the table or view you're labeling.
• table_or_view is the name of the table or view you're labeling.

Examples:

To add a table label that tracks departments, enter the bq update command and specify department as the label key. For example, to add a department:shipping label to mytable in your default project, enter:

    bq update --set_label department:shipping mydataset.mytable

To add a view label that tracks departments, enter the bq update command and specify department as the label key. For example, to add a department:shipping label to myview in your default project, enter:

    bq update --set_label department:shipping mydataset.myview

To add multiple labels to a table or view, repeat the set_label flag and specify a unique key for each label. For example, to add a department:shipping label and cost_center:logistics label to mytable in your default project, enter:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset.mytable

API

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

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

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));
}

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

Adding job labels

Labels can be added to query jobs via the command line by using the command-line tool's --label flag. The command-line tool supports adding labels only to query jobs.

You can also add a label to a job when it's submitted via the API by specifying the labels property in the job configuration when you call the jobs.insert method. The API can be used to add labels to any job type.

You cannot add labels to or update labels on pending, running, or completed jobs.

When you add a label to a job, the label is included in your billing data.

Required permissions

No special permissions are required for adding a label to a job. If you have bigquery.jobs.create permissions, you can add a label to your job when you submit it.

At a minimum, to run a job, you must have bigquery.jobs.create permissions. bigquery.jobs.create permissions are required for jobs that are automatically created by BigQuery, and they are required for jobs that you run programmatically.

The following predefined Cloud IAM roles include bigquery.jobs.create permissions:

• bigquery.user
• bigquery.jobUser
• bigquery.admin

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

Adding a label to a job

To add a label to a job:

Console

Adding labels to jobs is not supported by the GCP Console.

Classic UI

Adding labels to jobs is not supported by the classic BigQuery web UI.

CLI

To add a label to a query job, issue the bq query command with the --label flag. Repeat the flag to add multiple labels. The --nouse_legacy_sql flag indicates that your query is in standard SQL syntax.

bq query --label key:value --nouse_legacy_sql 'query'

Where:

• key:value corresponds to a key:value pair for a label that you want to add to the query job. The key must be unique. To add multiple labels to a query job, repeat the --label flag and specify a unique key for each label.
• query is a valid standard SQL query.

Examples:

To add a label to a query job, enter:

    bq query \
    --label department:shipping \
    --nouse_legacy_sql \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

To add multiple labels to a query job, repeat the --label flag and specify a unique key for each label. For example, to add a department:shipping label and cost_center:logistics label to a query job, enter:

    bq query \
    --label department:shipping \
    --label cost_center:logistics \
    --nouse_legacy_sql \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

API

To add a label to a job, call the jobs.insert method and populate the labels property for the job configuration. You can use the API to add labels to any job type.

Adding 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 add a tag:

Console

1. In the GCP Console, 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, click the pencil icon to the right of Labels.

   

4. In the Edit labels dialog:

   • Click Add label.
   • Enter a new key and leave the value blank. To apply additional tags, click Add label and repeat.
   • Click Update to save your changes.

DDL

Data definition language (DDL) statements allow you to create and modify tables and views using standard SQL query syntax.

See more on Using Data Definition Language statements.

Beta

Esta es una versión Beta de BigQuery support for the ALTER TABLE SET OPTIONS statement. En esta función se pueden producir cambios que generen incompatibilidad con versiones anteriores y is sujetas a ningún ANS o política de baja del servicio.

To add a tag using a DDL statement in the GCP Console:

1. Click Compose new query.

2. Type your DDL statement into the Query editor text area.

    ALTER TABLE mydataset.mytable
    SET OPTIONS (
      labels=[("tag1", ""), ("tag2", "")]
    )
    

3. Click Run query.

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

   • Enter a new key and leave the value blank. To apply additional tags, click Add Label.

   • Click OK.

     

CLI

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

bq update --set_label key: resource_id

Where:

• key: is the label key that you want to use as 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 create a test_data tag for mydataset.mytable. mydataset is in your default project.

bq update --set_label test_data: mydataset

API

Call the datasets.patch method or the tables.patch method and add labels with the value set to the empty string ("") in the dataset resource or the table resource. You can turn existing labels into tags by replacing their values with the empty string.

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 view labels on 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.