Como filtrar recursos usando rótulos

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

  • Use a barra de pesquisa no Console do 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.

Permissões exigidas

É preciso ser capaz de recuperar metadados de recursos para filtrar recursos usando rótulos. No mínimo, isso requer:

  • bigquery.datasets.get para filtrar conjuntos de dados;
  • bigquery.tables.get para filtrar tabelas e visualizações

Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.datasets.get:

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

Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.tables.get:

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

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário filtre 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 Cloud

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

Console

  1. No painel de navegação, expanda a seção Recursos.

  2. Na barra de pesquisa, digite seu par key, value 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, digite:

    • key valor: department
    • value: shipping
    • key:value par: 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 sinalização --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 essa amostra, siga as instruções de configuração para 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 Go (em inglês). 

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 essa amostra, siga as instruções de configuração para 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 Java.

Ver no GitHub (em inglês) Feedback 
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 essa amostra, siga as instruções de configuração para 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 Node.js. 

// 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 essa amostra, siga as instruções de configuração para 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. 


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