Creating and 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 you can use labels with your BigQuery resources. It also describes how to add, update, and remove the labels for a resource.

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.

Creating and updating 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. For more information on adding a label when you create a dataset, see Creating a dataset.

A label can be added or updated after a dataset is created 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 add or update a dataset label after the dataset is created, 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.

Creating or updating a dataset label

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

Web UI

In the web UI, select the dataset.
On the Dataset Details page, to the right of Labels, click Edit.
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.

Command-line

To add or 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 create 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 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 update the department label, 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

To add multiple labels to a dataset, repeat the set_label flag and specify a unique key for each label. To delete multiple labels on a dataset, repeat the clear_label flag and specify a each key:value pair. 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 or 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

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

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

Creating and updating 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 or by calling the tables.insert API method. 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 or 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 create or 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.

Creating or updating a table or view label

To update a table or view label or to add a label to a table or view after it is created:

Web UI

In the web UI, select the table, or view.
On the details page, to the right of Labels, click Edit. This example shows the details for a table.
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.
- Modify the existing keys or values to update a label.
- Click OK.

Command-line

To add or 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 create 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 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 mytable in your default project, enter:

    bq update --set_label department:shipping mydataset.mytable

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 myview in your default project, enter:

    bq update --set_label department:shipping mydataset.myview

To update the department label, 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

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

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

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

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

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 delete a label from a dataset:

Web UI

In the web UI, select the dataset.
On the Dataset Details page, to the right of Labels, click Edit.
In the Edit Labels dialog:
- Click the delete icon (X) for each label you want to remove.
- Click OK.

Command-line

To add or update 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 .

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

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

# 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 delete 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 delete a label from a table or view:

Web UI

In the web UI, select the table or view.
On the Details page, to the right of Labels, click Edit.
In the Edit Labels dialog:
- Click the delete icon (X) for each label you want to remove.
- Click OK.

Command-line

To delete a table or view label, 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 .

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

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

# 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 == {}

Creating 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 create a tag:

Web UI

In the web UI, select the appropriate resource (a dataset, table, or view).
For datasets, the Dataset Details page is automatically opened. For tables and views, click Details to open the details page.
On the details page, to the right of Labels, click Edit.
In the Edit Labels dialog:
- Enter a new key and leave the value blank or delete the value for an existing label. To apply additional tags, click Add Label.
- Click OK.

Command-line

Use the bq update command with the set_label flag. Specify the key, followed by a colon, but leave the value unspecified. This can be used to update an existing label to a tag or to add a new tag.

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

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

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.

Viewing labels

You can view labels by using the BigQuery web UI, the command-line tool's bq show command, or by calling the datasets.get or tables.get API methods. 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

To get information about a dataset, you must be assigned the dataset-level READER role, or you must be assigned a project-level IAM role that includes bigquery.datasets.get permissions. All predefined, project-level IAM roles include bigquery.datasets.get permissions except for bigquery.jobUser.

In addition, a user assigned the bigquery.user role has bigquery.datasets.create permissions. This allows a user assigned to the bigquery.user role to get information about 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.

Table and view permissions

To get information about tables, you must be assigned the READER role on the dataset, or you must be assigned a predefined, project-level IAM role that includes bigquery.tables.get permissions. If you are granted bigquery.tables.get permissions at the project level, you can get information about all tables in the project. The following predefined, project-level IAM roles include bigquery.tables.get permissions:

In addition, a user assigned the bigquery.user role has bigquery.datasets.create permissions. This allows a user assigned to the bigquery.user role to get information about 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 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.

Viewing dataset, table, and view labels

To view a resource's labels:

Web UI

In the web UI, select the appropriate resource (a dataset, table, or view).
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.

Command-line

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, or view name.

Examples:

Enter the following command to display labels for mydataset in your default project.

bq show --format=pretty mydataset

Enter the follwoing command to display labels for mydataset.mytable. mydataset is in myotherproject, not your default project.

bq show --format=pretty myotherproject:mydataset.mytable

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

// 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")
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)
}

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'

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # 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.")

Filtering datasets using labels

To filter datasets based on labels, create a filter specification for use in the bq command-line tool or the BigQuery API that uses the following syntax:

    "field[:value][ field[:value]..."

Where:

field is expressed as labels.[KEY] where [KEY] is a label key.
value is an optional label value.

Currently, you cannot list tables or views based on a filter specification.

Limitations

The filter specification has the following limitations:

Only the AND logical operator is supported. Space-separated comparisons are treated as having implicit AND operators.
The only field currently eligible for filtering is "labels.key" where "key" is the name of a label.
The filter can include up to ten expressions.
Filtering is case-sensitive.
You cannot filter tables and views using a filter specification.
Currently, you cannot filter datasets using the BigQuery web UI.

Filter specification examples

To list datasets that have a department:shipping label, use the following filter specification:

labels.department:shipping

To list datasets using multiple labels, separate the key:value pairs with a space. The space is treated as a logical AND operator. For example, to list datasets with the department:shipping label and the location:usa label, use the following filter specification:

labels.department:shipping labels.location:usa

You can filter on the presence of a key alone, rather than matching against a key:value pair. The following filter specification lists all datasets labeled department regardless of the value:

labels.department

An equivalent filter specification uses an asterisk to represent all possible values associated with the department key:

labels.department:*

You can also use tags in a filter specification. For example, to list datasets with the department:shipping label and test_data tag, use the following filter specification:

labels.department:shipping labels.test_data

Generating filtered lists

To generate a filtered list of datasets:

Web UI

Currently, you cannot filter datasets using the BigQuery web UI.

Command-line

Issue the bq ls command with the --filter flag. If you are listing datasets in a project other than your default project, specify the --project_id flag.

bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]

Where:

[FILTER_SPECIFICATION] is a valid filter specification. The command-line tool returns a list of datasets that meet the filter requirements.
[PROJECT_ID] is your project ID.

Examples:

Enter the following command to list datasets in your default project that have a department:shipping label:

bq ls --filter "labels.department:shipping"

Enter the following command to list datasets in your default project that have a department:shipping label and a test_data tag.

bq ls --filter "labels.department:shipping labels.test_data"

Enter the following command to list datasets in myotherproject that have a department:shipping label:

bq ls --filter "labels.department:shipping" --project_id myotherproject

API

Call the datasets.list API method and provide the filter specification using the filter property.

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")
it := client.Datasets(ctx)
it.Filter = "labels.color:green"
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
}

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()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = 'labels.color:green'
datasets = list(client.list_datasets(filter=label_filter))

if datasets:
    print('Datasets filtered by {}:'.format(label_filter))
    for dataset in datasets:  # API request(s)
        print('\t{}'.format(dataset.dataset_id))
else:
    print('No datasets found with this filter.')

What's next

Read about Labeling or Tagging Resources in the Compute Engine documentation.
Read about Using Labels in the Resource Manager documentation.

What are labels?

Common uses of labels

Requirements for labels

Creating and updating dataset labels

Required permissions

Creating or updating a dataset label

Web UI

Command-line

API

Go

Java

Python

Creating and updating table and view labels

Required permissions

Creating or updating a table or view label

Web UI

Command-line

API

Go

Java

Python

Deleting labels

Deleting a dataset label

Required permissions

Deleting a dataset label

Web UI

Command-line

API

Go

Python

Deleting a table or view label

Required permissions

Deleting a table or view label

Web UI

Command-line

API

Go

Python

Creating a tag

Web UI

Command-line

API

Viewing labels

Required permissions

Dataset permissions

Table and view permissions

Viewing dataset, table, and view labels

Web UI

Command-line

API

Go

Python

Filtering datasets using labels

Limitations

Filter specification examples

Generating filtered lists

Web UI

Command-line

API

Go

Python

What's next

Envoyer des commentaires concernant…