Filtra recursos mediante etiquetas

En esta página, se explica cómo filtrar tus recursos de BigQuery mediante el uso de etiquetas.

Descripción general

Para filtrar recursos mediante el uso de etiquetas, haz lo siguiente:

  • Usa la barra de búsqueda en Cloud Console o la IU web clásica.
  • Crea una especificación de filtro para usar en la CLI, la API o las bibliotecas cliente.

Limitaciones

En la actualidad, existen las siguientes limitaciones:

  • Las API, CLI y bibliotecas cliente son compatibles con el filtrado solo para conjuntos de datos.
  • No se puede filtrar trabajos por etiqueta en ninguna de las herramientas de BigQuery.

Permisos necesarios

Para filtrar recursos mediante el uso de etiquetas, debes ser capaz de recuperar los metadatos del recurso. Como mínimo, esto requiere lo siguiente:

  • bigquery.datasets.get para filtrar conjuntos de datos
  • bigquery.tables.get para filtrar tablas y vistas

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.datasets.get:

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

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.get:

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

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. El acceso bigquery.dataOwner brinda al usuario la capacidad de filtrar los recursos que crea.

Para obtener más información sobre las funciones de Cloud IAM y los permisos en BigQuery, consulta Funciones y permisos predefinidos.

Filtra recursos en la IU

Para generar una lista filtrada de recursos mediante Cloud Console o la IU web clásica, sigue estos pasos:

Console

  1. En el panel de navegación, expande la sección Recursos.

  2. En la barra de búsqueda, ingresa tu par key, value o key:value. En tus resultados, se incluye cualquier coincidencia parcial.

    Por ejemplo, para mostrar solo los conjuntos de datos que tengan la etiqueta department:shipping, puedes ingresar algunas de las opciones siguientes:

    • valor de key: department
    • value: shipping
    • par key:value: department:shipping

IU clásica

  1. En el panel de navegación, desplázate hacia el cuadro Filtrar por ID o etiqueta. Este cuadro aparece justo por encima de tu lista de proyectos.

  2. En la barra de búsqueda, ingresa tu clave, valor o par clave-valor. El par clave-valor debe estar en formato key:value En tus resultados, se incluye cualquier coincidencia parcial.

    Por ejemplo, para mostrar solo los conjuntos de datos que tengan la etiqueta department:shipping, puedes ingresar algunas de las opciones siguientes:

    • valor de key: department
    • value: shipping
    • par key:value: department:shipping

Filtra conjuntos de datos en la CLI o la API

En la actualidad, la API, la CLI y las bibliotecas cliente son compatibles con el filtrado solo para conjuntos de datos.

Para filtrar conjuntos de datos mediante la CLI, la API o las bibliotecas cliente, crea una especificación de filtro y úsala de alguna de estas formas:

  • Como parámetro para la marca --filter en la CLI
  • Como valor de la propiedad filter en el método datasets.list de la API

Limitaciones de las especificaciones de los filtros

Las especificaciones de los filtros tienen las siguientes limitaciones:

  • Solo se admite el operador lógico AND. Las comparaciones separadas por espacios se tratan como si tuvieran operadores AND implícitos.
  • En la actualidad, el único campo apto para filtrar es labels.key, en el que key es el nombre de una etiqueta.
  • El filtro puede incluir hasta diez expresiones.
  • El filtro distingue mayúsculas y minúsculas.
  • En la actualidad, la CLI, la API y las bibliotecas cliente son compatibles con el filtrado solo para conjuntos de datos.

Ejemplos de especificación de filtro

En una especificación de filtro, se usa la siguiente sintaxis:

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

Donde:

  • field se expresa como labels.key, donde clave es una clave de etiqueta.
  • value es un valor de etiqueta opcional.

En los siguientes ejemplos, se muestra cómo generar expresiones de filtro.

Para enumerar los recursos que tienen una etiqueta department:shipping, usa la siguiente especificación de filtro:

labels.department:shipping

Para enumerar recursos con varias etiquetas, separa los pares key:value con un espacio. El espacio se trata como un operador lógico AND. Por ejemplo, para enumerar conjuntos de datos con la etiqueta department:shipping y la location:usa, usa la siguiente especificación de filtro:

labels.department:shipping labels.location:usa

Puedes filtrar según la sola presencia de una clave, sin buscar coincidencia con un par clave-valor. Con la siguiente especificación de filtro, se enumeran todos los conjuntos de datos etiquetados como department con independencia del valor.

labels.department

En una especificación de filtro equivalente, se usa un asterisco para representar todos los valores posibles asociados a la clave department.

labels.department:*

También puedes usar etiquetas en una especificación de filtro. Por ejemplo, para enumerar recursos con la etiqueta department:shipping y la test_data, usa la siguiente especificación de filtro:

labels.department:shipping labels.test_data

Filtrado de conjuntos de datos en la CLI y API

Para filtrar conjuntos de datos mediante la CLI, la API o las bibliotecas cliente, sigue estos pasos:

CLI

Ejecuta el comando bq ls con la marca --filter. Si vas a enumerar conjuntos de datos en un proyecto que no es tu proyecto predeterminado, especifica la marca --project_id.

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

Donde:

  • filter_specification es una especificación de filtro válida.
  • project_id es el ID del proyecto.

Ejemplos:

Ingresa el siguiente comando para enumerar los conjuntos de datos en tu proyecto predeterminado que tengan una etiqueta department:shipping:

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

Ingresa el siguiente comando para enumerar los conjuntos de datos en tu proyecto predeterminado que tengan una etiqueta department:shipping y una test_data.

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

Ingresa el siguiente comando para enumerar conjuntos de datos en myotherproject que tengan una etiqueta department:shipping:

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

En el resultado de cada uno de estos comandos, se muestra una lista de conjuntos de datos como la siguiente.

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

API

Llama al método de la API datasets.list y proporciona la especificación del filtro con la propiedad filter.

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración de Go incluidas en la guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para 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 probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para 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.")

Próximos pasos

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.