Filtrer des ressources à l'aide de libellés

Cette page explique comment filtrer vos ressources BigQuery à l'aide de libellés.

Présentation

Pour filtrer des ressources à l'aide de libellés, vous pouvez :

  • utiliser la barre de recherche de Cloud Console ou de l'UI Web classique ;
  • créer une spécification de filtre à utiliser avec la CLI, l'API ou les bibliothèques clientes.

Limites

Voici les limites actuelles concernant le filtrage des ressources :

  • L'API, la CLI et les bibliothèques clientes ne permettent de filtrer que des ensembles de données.
  • Le filtrage des tâches par étiquette n'est disponible dans aucun des outils BigQuery.

Autorisations requises

Pour filtrer des ressources à l'aide de libellés, vous devez pouvoir récupérer les métadonnées de ressource. Pour effectuer cette opération, vous devez disposer au minimum des autorisations suivantes :

  • bigquery.datasets.get pour filtrer les ensembles de données
  • bigquery.tables.get pour filtrer les tables et les vues

Les rôles Cloud IAM prédéfinis suivants incluent les autorisations bigquery.datasets.get :

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

Les rôles Cloud IAM prédéfinis suivants incluent les autorisations bigquery.tables.get :

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

En outre, si un utilisateur possède les autorisations bigquery.datasets.create, il obtient également un accès bigquery.dataOwner à l'ensemble de données qu'il crée. L'accès bigquery.dataOwner permet à l'utilisateur de filtrer les ressources qu'il crée.

Pour en savoir plus sur les rôles et les autorisations Cloud IAM dans BigQuery, consultez la page Rôles et autorisations prédéfinis.

Filtrer des ressources dans l'interface utilisateur

Pour générer une liste filtrée de ressources à l'aide de Cloud Console ou de l'UI Web classique, procédez comme suit :

Console

  1. Dans le volet de navigation, développez la section Ressources.

  2. Dans la barre de recherche, saisissez key, value ou la paire key:value. Les résultats incluent les correspondances partielles.

    Par exemple, si vous souhaitez n'afficher que les ensembles de données qui possèdent le libellé department:shipping, vous pouvez saisir les éléments suivants :

    • Valeur key : department
    • Valeur value : shipping
    • Paire key:value : department:shipping

UI classique

  1. Dans le volet de navigation, faites défiler l'écran jusqu'à la zone Filtrer par ID ou par étiquette. Cette zone s'affiche juste au-dessus de la liste de vos projets.

  2. Dans la barre de recherche, saisissez la clé, la valeur ou la paire clé/valeur. La paire clé/valeur doit être au format key:value. Les résultats incluent les correspondances partielles.

    Par exemple, si vous souhaitez n'afficher que les ensembles de données qui possèdent le libellé department:shipping, vous pouvez saisir les éléments suivants :

    • Valeur key : department
    • Valeur value : shipping
    • Paire key:value : department:shipping

Filtrer des ensembles de données à l'aide de la CLI ou de l'API

À l'heure actuelle, l'API, la CLI et les bibliothèques clientes ne permettent de filtrer que des ensembles de données.

Pour filtrer des ensembles de données à l'aide de la CLI, de l'API ou des bibliothèques clientes, créez une spécification de filtre et utilisez-la :

  • en tant que paramètre de l'option --filter dans la CLI ;
  • en tant que valeur de la propriété filter dans la méthode datasets.list de l'API.

Limites applicables aux spécifications de filtre

Les spécifications de filtre sont soumises aux limites suivantes :

  • Le seul opérateur logique compatible est l'opérateur AND. Les comparaisons séparées par des espaces sont considérées comme possédant des opérateurs AND implicites.
  • Le seul champ actuellement disponible pour le filtrage est labels.key, où key correspond à un nom de libellé.
  • Le filtre peut comprendre jusqu'à dix expressions.
  • Le filtrage est sensible à la casse.
  • À l'heure actuelle, la CLI, l'API et les bibliothèques clientes ne permettent de filtrer que des ensembles de données.

Exemples de spécifications de filtre

Une spécification de filtre utilise la syntaxe suivante :

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

Où :

  • field est exprimé au format labels.key, où key correspond à une clé de libellé.
  • value est une valeur de libellé facultative.

Les exemples suivants expliquent comment générer des expressions de filtre.

Pour répertorier les ressources qui possèdent le libellé department:shipping, utilisez la spécification de filtre suivante :

labels.department:shipping

Pour répertorier les ensembles de données qui possèdent plusieurs libellés, séparez les paires key:value par un espace. L'espace est traité comme un opérateur logique AND. Par exemple, si vous souhaitez répertorier les ensembles de données qui possèdent les libellés department:shipping et location:usa, utilisez la spécification de filtre suivante :

labels.department:shipping labels.location:usa

Plutôt que d'utiliser une paire clé/valeur, vous pouvez créer un filtre ne contenant qu'une clé. La spécification de filtre suivante répertorie tous les ensembles de données possédant le libellé department, quelle que soit la valeur :

labels.department

Une alternative consiste à utiliser un astérisque pour représenter toutes les valeurs possibles associées à la clé department :

labels.department:*

Vous pouvez également utiliser des tags dans une spécification de filtre. Par exemple, si vous souhaitez répertorier les ressources qui possèdent le libellé department:shipping et le tag test_data, utilisez la spécification de filtre suivante :

labels.department:shipping labels.test_data

Filtrer des ensembles de données à l'aide de la CLI et de l'API

Pour filtrer des ensembles de données à l'aide de la CLI, de l'API ou des bibliothèques clientes, procédez comme suit :

CLI

Exécutez la commande bq ls avec l'option --filter. Si vous répertoriez des ensembles de données dans un projet autre que votre projet par défaut, spécifiez l'option --project_id.

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

Où :

  • filter_specification est une spécification de filtre valide.
  • project_id est l'ID du projet.

Exemples :

Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent le libellé department:shipping :

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

Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent le libellé department:shipping et le tag test_data.

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

Saisissez la commande suivante pour répertorier les ensembles de données de myotherproject qui possèdent le libellé department:shipping :

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

Le résultat de chacune de ces commandes ressemble à ce qui suit.

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

API

Appelez la méthode API datasets.list et fournissez la spécification de filtre à l'aide de la propriété filter.

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage 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.")

Étapes suivantes