Add labels to resources

This document describes how to add labels to BigQuery resources, including the following resources:

For more information about labels in BigQuery, see Introduction to labels.

Before you begin

Grant users the necessary Identity and Access Management (IAM) roles to perform each task in this document. Each task's 'Required IAM roles' section lists the permissions needed to perform that task.

Add labels to datasets

You can add a label to a BigQuery dataset when you create it by using the bq command-line tool's bq mk command or by calling the datasets.insert API method. You cannot add a label to a dataset when you create it using the Google Cloud console. However, you can add a dataset label after creation. For more information about creating a dataset, see Creating a dataset.

When you add a label to a dataset, the label does not propagate to resources within the dataset. Tables or views do not inherit dataset labels. Also, when you add a label to a dataset, it is included in your storage billing data, but not in your job-related billing data.

For more information about label format, see Requirements for labels.

Required IAM roles

To get the permission that you need to add a label to an existing dataset, ask your administrator to grant you the BigQuery Data Owner (roles/bigquery.dataOwner) IAM role. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the bigquery.datasets.update permission, which is required to add a label to an existing dataset.

You might also be able to get this permission with custom roles or other predefined roles.

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

Add a label to a dataset

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

Console

In the Google Cloud console, select the dataset.
On the dataset details page, in the Labels section, click Edit.
In the Edit labels dialog:
- Click Add label
- Enter the key and value in the appropriate fields. 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 within the same project.
- To update a label, modify the existing keys or values.
- To save your changes, click Update.

SQL

Use the ALTER SCHEMA SET OPTIONS DDL statement to set the labels on an existing dataset. This action overwrites any existing labels on the dataset. The following example sets a label on the mydataset dataset:

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

Go to BigQuery

In the query editor, enter the following statement:

ALTER SCHEMA mydataset
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

Click Run.

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

bq

To add a label to an existing dataset, use the bq update command with the set_label flag. To add multiple labels, repeat the flag.

If the dataset is in a project other than your default project, specify the project ID in the following format: PROJECT_ID:DATASET.

bq update --set_label KEY:VALUE PROJECT_ID:DATASET

Replace the following:

KEY:VALUE: The key-value pair for a label you want to add. The key must be unique. 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.
PROJECT_ID: your project ID.
DATASET: the dataset you're labeling.

Examples:

To add a label to track departments, use 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, use:

    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, use:

    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, use the datasets.patch method instead.

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 authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

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.

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

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

  public static void labelDataset(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();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \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.

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

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