Filtra recursos mediante etiquetas

Para filtrar recursos mediante el uso de etiquetas, puedes realizar una de las siguientes acciones:

  • Usa la barra de búsqueda en la consola de Google Cloud.
  • Crea una especificación de filtro para usar en la API, la herramienta de línea de comandos de bq o las bibliotecas cliente.

Limitaciones

  • La API, la herramienta de línea de comandos de bq y las bibliotecas cliente son compatibles con el filtrado solo para conjuntos de datos.
  • No puedes filtrar trabajos por etiqueta en ninguna de las herramientas de BigQuery.

Antes de comenzar

Otorga roles de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para hacer cada tarea de este documento.

Permisos necesarios

Para filtrar recursos mediante el uso de etiquetas, debes ser capaz de recuperar los metadatos del recurso. Para filtrar recursos mediante el uso de etiquetas, necesitas los siguientes permisos de IAM:

  • bigquery.datasets.get: te permite filtrar conjuntos de datos
  • bigquery.tables.get: te permite filtrar tablas y vistas

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para filtrar conjuntos de datos:

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

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para copiar tablas y particiones:

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

Además, si tienes el permiso bigquery.datasets.create, puedes filtrar los recursos que creas.

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

Filtra recursos en la consola de Google Cloud

Para generar una lista filtrada de recursos, usa la consola de Google Cloud:

  1. En la consola de Google Cloud, ve al panel Explorador.

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

    Por ejemplo, para mostrar solo los conjuntos de datos con la etiqueta department:shipping, puedes ingresar department o department:shipping.

Filtra conjuntos de datos en la API o en la herramienta de línea de comandos de bq

En la actualidad, la API, la herramienta de línea de comandos de bq y las bibliotecas cliente son compatibles con el filtrado solo para conjuntos de datos.

Para filtrar conjuntos de datos con la API, la herramienta de bq 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 herramienta de bq
  • 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 API, la herramienta de línea de comandos de bq 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]]..."

Reemplaza lo siguiente:

  • field se expresa como labels.key, y key 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

Filtra conjuntos de datos en la herramienta de línea de comandos de bq y en la API

Para filtrar conjuntos de datos con la API, la herramienta de línea de comandos de bq o las bibliotecas cliente, haz lo siguiente:

bq

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

Reemplaza lo siguiente:

  • 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 para Go incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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 probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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 probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

// 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 probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 


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.")

¿Qué sigue?