Filtering resources using labels

To filter resources using labels, you can do one of the following:

• Use the search bar in the Google Cloud console.
• Create a filter specification for use in the API, bq command-line tool, or clientlibraries.

Limitations

• The API, bq command-line tool, and client libraries support filtering only for datasets.
• You cannot filter jobs by label in any of the BigQuery tools.

Before you begin

Grant Identity and Access Management (IAM) roles that give users the necessary permissions to perform each task in this document.

Required permissions

To filter resources using labels, you must be able to retrieve resourcemetadata. To filter resources using labels, you need the following IAM permissions:

• bigquery.datasets.get (lets you filter datasets)
• bigquery.tables.get (lets you filter tables and views)

Each of the following predefined IAM roles includes the permissions that you need in order to filter datasets:

• roles/bigquery.user
• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

Each of the following predefined IAM roles includes the permissions that you need in order to filter tables and views:

• roles/bigquery.metadataViewer
• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

Additionally, if you have thebigquery.datasets.create permission, you can filter the resources that you create.

For more information on IAM roles and permissions inBigQuery, seePredefined roles and permissions.

Filter resources in the Google Cloud console

To generate a filtered list of resources, use the Google Cloud console:

1. In the Google Cloud console, go to theExplorer pane.

2. In the search bar, enter thekey orkey:value pair. Your results include any partial matches.

   For example, to show only datasets with the labeldepartment:shipping,you can enterdepartment ordepartment:shipping.

Filter datasets in the API or bq command-line tool

The API, bq command-line tool, and client libraries support filtering only fordatasets.

To filter datasets by using the API, bq tool, or client libraries,create a filter specification and use the specification:

• As the parameter for the--filter flag in the bq tool
• As the value for thefilter property in the API'sdatasets.list method

Limitations on filter specifications

Filter specifications have the following limitations:

• Only theAND logical operator is supported. Space-separated comparisons aretreated as having implicitAND operators.
• The only field eligible for filtering islabels.key wherekey isthe name of a label.
• Eachkey in a filtering expression must be unique.
• The filter can include up to ten expressions.
• Filtering is case-sensitive.
• The API, bq command-line tool, and client libraries support filtering only fordatasets.

Filter specification examples

A filter specification uses the following syntax:

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

Replace the following:

• field is expressed aslabels.key wherekeyis a label key.
• value is an optional label value.

The following examples show how to generate filter expressions.

To list resources that have adepartment:shipping label, use the followingfilter specification:

labels.department:shipping

To list resources using multiple labels, separate thekey:value pairs with aspace. The space is treated as a logicalAND operator. For example, to listdatasets with thedepartment:shipping label and thelocation: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 akey:value pair. The following filter specification lists all datasetslabeleddepartment regardless of the value.

labels.department

An equivalent filter specification uses an asterisk to represent all possiblevalues associated with thedepartment key.

labels.department:*

You can also use tags in a filter specification. For example, to list resourceswith thedepartment:shipping label andtest_data tag, use the followingfilter specification:

labels.department:shipping labels.test_data

Filtering datasets in the bq command-line tool and the API

To filter datasets by using the API, bq command-line tool, or client libraries:

bqls\--filter"filter_specification"\--project_idproject_id

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

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

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

+-----------+| datasetId |+-----------+| mydataset || mydataset2|+-----------+

import("context""fmt""io""cloud.google.com/go/bigquery""google.golang.org/api/iterator")// listDatasetsByLabel demonstrates walking the collection of datasets in a project, and// filtering that list to a subset that has specific label metadata.funclistDatasetsByLabel(wio.Writer,projectIDstring)error{// projectID := "my-project-id"ctx:=context.Background()client,err:=bigquery.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("bigquery.NewClient: %v",err)}deferclient.Close()it:=client.Datasets(ctx)it.Filter="labels.color:green"for{dataset,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{returnerr}fmt.Fprintf(w,"dataset: %s\n",dataset.DatasetID)}returnnil}

importcom.google.api.gax.paging.Page;importcom.google.cloud.bigquery.BigQuery;importcom.google.cloud.bigquery.BigQueryException;importcom.google.cloud.bigquery.BigQueryOptions;importcom.google.cloud.bigquery.Dataset;// Sample to get list of datasets by labelpublicclassListDatasetsByLabel{publicstaticvoidrunListDatasetsByLabel(){// TODO(developer): Replace these variables before running the sample.StringprojectId="MY_PROJECT_ID";Stringfilter="MY_LABEL_FILTER";listDatasetsByLabel(projectId,filter);}publicstaticvoidlistDatasetsByLabel(StringprojectId,Stringfilter){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.BigQuerybigquery=BigQueryOptions.getDefaultInstance().getService();Page<Dataset>datasets=bigquery.listDatasets(projectId,BigQuery.DatasetListOption.pageSize(100),BigQuery.DatasetListOption.labelFilter(filter));// "labels.color:green"if(datasets==null){System.out.println("Dataset does not contain any models");return;}datasets.iterateAll().forEach(dataset->System.out.printf("Success! Dataset ID: %s ",dataset.getDatasetId()));}catch(BigQueryExceptione){System.out.println("Project does not contain any datasets \n"+e.toString());}}}

// Import the Google Cloud client libraryconst{BigQuery}=require('@google-cloud/bigquery');constbigquery=newBigQuery();asyncfunctionlistDatasetsByLabel(){// Lists all datasets in current GCP project, filtering by label color:green.constoptions={filter:'labels.color:green',};// Lists all datasets in the specified projectconst[datasets]=awaitbigquery.getDatasets(options);console.log('Datasets:');datasets.forEach(dataset=>console.log(dataset.id));}

fromgoogle.cloudimportbigquery# Construct a BigQuery client object.client=bigquery.Client()label_filter="labels.color:green"datasets=list(client.list_datasets(filter=label_filter))# Make an API request.ifdatasets:print("Datasets filtered by{}:".format(label_filter))fordatasetindatasets:print("\t{}.{}".format(dataset.project,dataset.dataset_id))else:print("No datasets found with this filter.")

What's next

• Learn how toadd labels to BigQueryresources.
• Learn how toview labels on BigQueryresources.
• Learn how toupdate labels onBigQuery resources.
• Learn how todelete labels onBigQuery resources.
• Read aboutusing labels in theResource Manager documentation.