Como filtrar recursos usando rótulos

Esta página explica 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 GCP ou na IU clássica da Web.
• 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 papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.datasets.get:

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

Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.tables.get:

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

Além disso, quando um usuário com permissões bigquery.datasets.create cria um conjunto de dados, ele recebe acesso bigquery.dataOwner ao conjunto. Com o acesso bigquery.dataOwner, o usuário consegue filtrar os recursos que cria.

Para mais informações sobre papéis e permissões do Cloud IAM no BigQuery, consulte Controle de acesso.

Como filtrar recursos na IU

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

Console

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

2. Na barra de pesquisa, insira o 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, insira:

   • valor key: department
   • value: shipping
   • par key:value: 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 precisa 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, insira:

   • valor key: department
   • value: shipping
   • par key:value: 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 para a 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 tendo operadores AND implícitos.
• O único campo atualmente qualificado 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 a seguir:

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 os conjuntos de dados com os rótulos department:shipping e location:usa, use a especificação de filtro abaixo:

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 o rótulo department:shipping e a tag test_data, use a especificação de filtro a seguir:

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

Insira o comando bq ls com a sinalização --filter. Se você estiver listando conjuntos de dados em um projeto diferente do 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:

Insira o comando a seguir para listar conjuntos de dados no projeto padrão que tem um rótulo department:shipping:

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

Insira o comando a seguir para listar conjuntos de dados no projeto padrão que tem um rótulo department:shipping e uma tag test_data.

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

Insira o comando a seguir para listar conjuntos de dados em myotherproject que têm um 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 de 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.

Ver no GitHub Feedback

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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)
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python em 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.

Ver no GitHub Feedback

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))

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

A seguir

• Saiba como adicionar rótulos a recursos do BigQuery.
• Saiba como visualizar rótulos em recursos do BigQuery.
• Saiba como atualizar rótulos em recursos do BigQuery.
• Saiba como excluir rótulos em recursos do BigQuery.
• Leia Como usar rótulos na documentação do Resource Manager.