Como filtrar recursos usando rótulos

Para filtrar recursos usando rótulos, siga um destes procedimentos:

  • Use a barra de pesquisa no console do Google Cloud.
  • Crie uma especificação de filtro para usar na API, ferramenta de linha de comando bq ou bibliotecas de cliente.

Limitações

  • A API, a ferramenta de linha de comando bq e as bibliotecas de cliente são compatíveis com a filtragem apenas de conjuntos de dados.
  • Não é possível filtrar jobs por rótulo em nenhuma das ferramentas do BigQuery.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Permissões necessárias

É preciso ser capaz de recuperar metadados de recursos para filtrar recursos usando rótulos. Para filtrar recursos usando rótulos, você precisa das seguintes permissões do IAM:

  • bigquery.datasets.get (permite filtrar conjuntos de dados)
  • bigquery.tables.get (permite filtrar tabelas e visualizações)

Cada um dos seguintes papéis predefinidos do IAM inclui as permissões necessárias para filtrar conjuntos de dados:

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

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para filtrar tabelas e visualizações:

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

Além disso, se você tiver a permissão bigquery.datasets.create, poderá filtrar os recursos criados.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Como filtrar recursos no console do Google Cloud

Para gerar uma lista filtrada de recursos, use o console do Google Cloud:

  1. No Console do Google Cloud, acesse o painel Explorer.

  2. Na barra de pesquisa, digite o par key ou key:value. Os resultados incluem todas as correspondências parciais.

    Por exemplo, para mostrar apenas conjuntos de dados com o rótulo department:shipping, insira department ou department:shipping.

Como filtrar conjuntos de dados na API ou na ferramenta de linha de comando bq

No momento, a API, a ferramenta de linha de comando bq e as bibliotecas de cliente são compatíveis com a filtragem apenas de conjuntos de dados.

Para filtrar conjuntos de dados usando a API, a ferramenta bq ou as bibliotecas de cliente, crie uma especificação de filtro e use-a:

  • como o parâmetro para a flag --filter na ferramenta bq
  • como o valor da propriedade filter no método datasets.list da API.

Limitações nas especificações do filtro

As especificações do filtro têm as seguintes limitações:

  • Somente o operador lógico AND é compatível. As comparações separadas por espaço são tratadas como se tivessem operadores AND implícitos.
  • O único campo qualificado atualmente para filtragem é labels.key, em que key é o nome de um rótulo.
  • O filtro pode incluir até dez expressões.
  • A filtragem diferencia maiúsculas e minúsculas.
  • No momento, a API, a ferramenta de linha de comando bq e as bibliotecas de cliente são compatíveis com a filtragem apenas de conjuntos de dados.

Exemplos de especificação de filtro

Uma especificação de filtro usa a seguinte sintaxe:

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

Substitua:

  • field é expresso como labels.key, em que key é uma chave de rótulo;
  • value é um valor de rótulo opcional.

Os exemplos a seguir mostram como gerar expressões de filtro.

Para listar recursos que têm um rótulo department:shipping, use a especificação de filtro abaixo:

labels.department:shipping

Para listar recursos usando vários rótulos, separe os pares key:value com um espaço. O espaço é tratado como um operador AND lógico. Por exemplo, para listar conjuntos de dados com os rótulos department:shipping e location:usa, use a seguinte especificação de filtro:

labels.department:shipping labels.location:usa

Filtre a presença de uma chave sozinha, em vez de corresponder com um par de chave-valor. A especificação de filtro a seguir lista todos os conjuntos de dados rotulados como department, independentemente do valor.

labels.department

Uma especificação de filtro equivalente usa um asterisco para representar todos os valores possíveis associados à chave department.

labels.department:*

Você também pode usar tags em uma especificação de filtro. Por exemplo, para listar recursos com rótulo department:shipping e tag test_data, use a especificação de filtro abaixo:

labels.department:shipping labels.test_data

Como filtrar conjuntos de dados na ferramenta de linha de comando bq e na API

Para filtrar conjuntos de dados usando a API, a ferramenta de linha de comando bq ou as bibliotecas de cliente:

bq

Use o comando bq ls com a sinalização --filter. Se estiver listando conjuntos de dados em um projeto diferente do seu projeto padrão, especifique a sinalização --project_id.

bq ls \
--filter "filter_specification" \
--project_id project_id

Substitua:

  • filter_specification é uma especificação de filtro válida;
  • project_id é o ID do projeto.

Exemplos:

Digite o comando a seguir para listar conjuntos de dados do seu projeto padrão que têm rótulo department:shipping:

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

Digite o comando a seguir para listar conjuntos de dados do seu projeto padrão que têm rótulo department:shipping e tag test_data.

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

Digite o comando a seguir para listar, conjuntos de dados em myotherproject que têm rótulo department:shipping:

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

A saída para cada um desses comandos retorna uma lista de conjuntos de dados, como a seguinte. 

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

API

Chame o método da API datasets.list e forneça a especificação de filtro usando a propriedade filter.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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.
func listDatasetsByLabel(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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)
	}
	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get list of datasets by label
public class ListDatasetsByLabel {

  public static void runListDatasetsByLabel() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String filter = "MY_LABEL_FILTER";
    listDatasetsByLabel(projectId, filter);
  }

  public static void listDatasetsByLabel(String projectId, String filter) {
    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();

      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 (BigQueryException e) {
      System.out.println("Project does not contain any datasets \n" + e.toString());
    }
  }
}

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function listDatasetsByLabel() {
  // Lists all datasets in current GCP project, filtering by label color:green.

  const options = {
    filter: 'labels.color:green',
  };
  // Lists all datasets in the specified project
  const [datasets] = await bigquery.getDatasets(options);

  console.log('Datasets:');
  datasets.forEach(dataset => console.log(dataset.id));
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 


from google.cloud import bigquery

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

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:
        print("\t{}.{}".format(dataset.project, dataset.dataset_id))
else:
    print("No datasets found with this filter.")

A seguir