Como filtrar recursos usando rótulos

Nesta página, explicamos como filtrar os recursos do BigQuery usando rótulos.

Visão geral

Para filtrar recursos usando rótulos:

  • Use a barra de pesquisa no Console do Cloud ou na IU da Web clássica.
  • Crie uma especificação de filtro para usar na CLI, API ou nas bibliotecas de cliente.

Limitações

Atualmente:

  • A API, CLI e as bibliotecas de cliente oferecem suporte à filtragem apenas para 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 Cloud IAM incluem permissões bigquery.datasets.get:

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

Os seguintes papéis predefinidos do Cloud IAM incluem 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 os papéis e permissões do Cloud IAM no BigQuery, consulte Papéis e permissões predefinidos.

Como filtrar recursos na IU

Para gerar uma lista filtrada de recursos usando o Console do Cloud ou a IU da Web clássica:

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

IU clássica

  1. No painel de navegação, role até a caixa Filtrar por ID ou rótulo. Esta caixa aparece logo acima da lista de projetos.

  2. Na barra de pesquisa, insira seu par de chave, valor ou chave-valor. O par de chave-valor deve estar no formato 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 CLI ou API

No momento, a API, CLI e as bibliotecas de cliente oferecem suporte à filtragem apenas para conjuntos de dados.

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

  • como o parâmetro para a sinalização --filter na CLI;
  • 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 CLI, API e as bibliotecas de cliente oferecem suporte à filtragem apena para conjuntos de dados.

Exemplos de especificação de filtro

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

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

Em que:

  • 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 CLI e API

Para filtrar conjuntos de dados usando a CLI, API ou as bibliotecas de cliente:

CLI

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

Em que:

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

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

	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
}

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

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): 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