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 dadosbigquery.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
No painel de navegação, expanda a seção Recursos.
Na barra de pesquisa, insira o par
key
,value
oukey: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
- valor
IU clássica
No painel de navegação, role até a caixa Filtrar por ID ou rótulo. Esta caixa aparece logo acima da lista de projetos.
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
- valor
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étododatasets.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 operadoresAND
implícitos. - O único campo atualmente qualificado para filtragem é
labels.key
, em quekey
é 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 comolabels.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.
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.
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.