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.

Limitations

BigQuery labels have the following limitations:

  • Each of your resources can have up to 64 labels.
  • Label keys and values can be no longer than 63 characters.
  • Label keys and values can contain only lowercase letters, numbers, underscores, hyphens, and international characters.
  • Label keys and values cannot exceed 128 bytes in size.
  • Label keys must begin with a letter.
  • Labels must have a key, but can have an empty value. Labels with no value can be used as tags.
  • A label key can be used only once per resource. For example, you can have only one dataset label or table label with key value organization.
  • When you add labels to tables or views, the label keys must be unique within the dataset. You cannot use the same key for two different tables or views in the same dataset.
  • When you add labels to a dataset, the label keys do not need to be unique within the project, but they must be unique per dataset. For example, you can have two datasets in the same project with the label key department, but the department key can be used only once for each dataset.

Creating and updating dataset labels

A label can added to a 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

  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:

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

      New label

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.

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

This sample uses the Google Auth Library for Python to send a request to the BigQuery API with an AuthorizedSession, which is compatible with a Requests session.
def label_dataset(dataset_id, label_key, label_value, project_id=None):
    """Add or modify a label on a dataset."""
    # Authenticate requests using Google Application Default credentials.
    credentials, default_project_id = google.auth.default(
            scopes=['https://www.googleapis.com/auth/bigquery'])
    session = google.auth.transport.requests.AuthorizedSession(credentials)

    if project_id is None:
        project_id = default_project_id

    # Send a PATCH request to add or modify a label.
    url_format = (
        'https://www.googleapis.com/bigquery/v2/'
        'projects/{project_id}/datasets/{dataset_id}')
    response = session.patch(
        url_format.format(project_id=project_id, dataset_id=dataset_id),
        params={'fields': 'labels'},
        json={
            'labels': {
                label_key: label_value,
            }
        })

    # Check the response for errors.
    response.raise_for_status()

    # Print the new label value from the response.
    labels = response.json()['labels']
    print(
        'Updated label "{}" with value "{}"'.format(
            label_key,
            labels[label_key]))

Creating and updating table and view labels

A label can 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

  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:

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

      New label

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.

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

This sample uses the Google Auth Library for Python to send a request to the BigQuery API with an AuthorizedSession, which is compatible with a Requests session.
def label_dataset(dataset_id, label_key, label_value, project_id=None):
    """Add or modify a label on a dataset."""
    # Authenticate requests using Google Application Default credentials.
    credentials, default_project_id = google.auth.default(
            scopes=['https://www.googleapis.com/auth/bigquery'])
    session = google.auth.transport.requests.AuthorizedSession(credentials)

    if project_id is None:
        project_id = default_project_id

    # Send a PATCH request to add or modify a label.
    url_format = (
        'https://www.googleapis.com/bigquery/v2/'
        'projects/{project_id}/datasets/{dataset_id}')
    response = session.patch(
        url_format.format(project_id=project_id, dataset_id=dataset_id),
        params={'fields': 'labels'},
        json={
            'labels': {
                label_key: label_value,
            }
        })

    # Check the response for errors.
    response.raise_for_status()

    # Print the new label value from the response.
    labels = response.json()['labels']
    print(
        'Updated label "{}" with value "{}"'.format(
            label_key,
            labels[label_key]))

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:

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

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

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

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

  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 or delete the value for an existing label. To apply additional tags, click Add Label.
    • Click OK.

      Add tag

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.

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.

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

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

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.

What's next

Send feedback about...