Mettre à jour des libellés

Cette page explique comment mettre à jour les libellés des ressources BigQuery.

Avant de commencer

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document. Les autorisations requises pour effectuer une tâche (le cas échéant) sont répertoriées dans la section "Autorisations requises" de la tâche.

Mettre à jour les libellés d'un ensemble de données

Vous pouvez mettre à jour un libellé d'ensemble de données de plusieurs façons :

Utiliser la console Google Cloud
Utiliser des instructions LDD SQL
En exécutant la commande bq update de l'outil de ligne de commande bq
En appelant la méthode API datasets.patch
En utilisant les bibliothèques clientes

Autorisations requises

Pour mettre à jour un libellé d'ensemble de données, vous devez disposer de l'autorisation IAM bigquery.datasets.update.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour mettre à jour un libellé d'ensemble de données :

roles/bigquery.dataOwner
roles/bigquery.admin

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez mettre à jour les libellés des ensembles de données que vous créez.

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

Mettre à jour un libellé d'ensemble de données

Pour mettre à jour les libellés d'un ensemble de données, sélectionnez l'une des options suivantes :

Console

Dans la console Google Cloud, sélectionnez l'ensemble de données.
Sur la page des détails de l'ensemble de données, cliquez sur l'icône en forme de crayon située à droite de Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé. Chaque clé ne peut être utilisée qu'une seule fois par ensemble de données, mais vous pouvez exploiter la même clé pour plusieurs ensembles de données au sein d'un même projet.
- Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
- Cliquez sur Mettre à jour pour enregistrer vos modifications.

SQL

Utilisez l'instruction LDD ALTER SCHEMA SET OPTIONS pour définir les libellés d'un ensemble de données existant. La définition de libellés écrase tous les libellés existants de l'ensemble de données. L'exemple suivant définit un seul libellé sur l'ensemble de données mydataset :

Dans Google Cloud Console, accédez à la page BigQuery.

Accéder à BigQuery

Dans l'éditeur de requête, saisissez l'instruction suivante :

ALTER SCHEMA mydataset
SET OPTIONS (labels = [('sensitivity', 'high')]);

Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Pour ajouter des libellés supplémentaires ou pour mettre à jour un libellé d'ensemble de données, exécutez la commande bq update en spécifiant l'option set_label. Répétez l'indicateur pour ajouter ou mettre à jour plusieurs libellés.

Si l'ensemble de données se trouve dans un projet autre que celui par défaut, ajoutez l'ID de ce projet au nom de l'ensemble de données, en respectant le format suivant : [PROJECT_ID]:[DATASET].

bq update \
--set_label key:value \
project_id:dataset

Où :

key:value est une paire clé/valeur pour un libellé que vous souhaitez ajouter ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.
project_id est l'ID de votre projet.
dataset est le nom de l'ensemble de données que vous mettez à jour.

Exemple :

Pour mettre à jour le libellé department sur l'ensemble de données mydataset, saisissez la commande bq update et spécifiez department comme clé de libellé. Par exemple, si vous souhaitez remplacer le libellé department:shipping par department:logistics, saisissez la commande ci-dessous. mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

Le résultat est semblable à ce qui suit.

Dataset 'myotherproject:mydataset' successfully updated.

API

Pour ajouter des libellés supplémentaires ou pour mettre à jour un libellé associé à un ensemble de données existant, appelez la méthode datasets.patch, puis ajoutez ou mettez à jour la propriété labels de la ressource d'ensemble de données.

Étant donné que la méthode datasets.update remplace l'intégralité de la ressource d'ensemble de données, la méthode datasets.patch est préférable.

Go

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Go.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Cet exemple permet d'envoyer une requête à l'API BigQuery à l'aide de la bibliothèque cliente HTTP Google pour Java.

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void runLabelDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    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();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

Mettre à jour des libellés de table et de vue

Vous pouvez mettre à jour un libellé après la création d'une table ou d'une vue de plusieurs façons :

En utilisant la console Google Cloud
En exécutant la commande bq update de l'outil de ligne de commande bq
En appelant la méthode API tables.patch
- Les vues étant traitées comme des ressources de table, la méthode tables.patch vous permet de modifier à la fois des vues et des tables.
En utilisant les bibliothèques clientes

Autorisations requises

Pour mettre à jour un libellé de table ou de vue, vous devez disposer de l'autorisation IAM bigquery.tables.update.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour mettre à jour un libellé de table ou de vue :

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

De plus, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez mettre à jour les libellés des tables et des vues des ensembles de données que vous créez.

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

Mettre à jour un libellé de table ou de vue

Pour mettre à jour un libellé de table ou de vue, procédez comme suit :

Console

Dans la console Google Cloud, sélectionnez la table ou la vue.
Cliquez sur l'onglet Détails, puis sur l'icône représentant un crayon à droite de Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé. Chaque clé ne peut être utilisée qu'une seule fois par table ou par vue, mais vous pouvez vous servir de la même clé pour plusieurs tables ou vues au sein de différents ensembles de données.
- Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
- Cliquez sur Mettre à jour pour enregistrer vos modifications.

SQL

Utilisez l'instruction LDD ALTER TABLE SET OPTIONS pour définir les libellés d'une table existante ou l'instruction LDD ALTER VIEW SET OPTIONS pour définir les libellés d'une vue existante. La définition de libellés écrase tous les libellés existants de la table ou de la vue. L'exemple suivant permet de définir deux libellés sur la table mytable :

Dans Google Cloud Console, accédez à la page BigQuery.

Accéder à BigQuery

Dans l'éditeur de requête, saisissez l'instruction suivante :

ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels = [('department', 'shipping'), ('cost_center', 'logistics')]);

Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Pour ajouter des libellés supplémentaires ou pour mettre à jour un libellé de table ou de vue, exécutez la commande bq update en spécifiant l'option set_label. Répétez l'indicateur pour ajouter ou mettre à jour plusieurs libellés.

Si la table ou la vue se trouve dans un projet autre que celui par défaut, ajoutez l'ID de ce projet au nom de l'ensemble de données, en respectant le format suivant : project_id:dataset.

bq update \
--set_label key:value \
project_id:dataset.table_or_view

Où :

key:value est une paire clé/valeur pour un libellé que vous souhaitez ajouter ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.
project_id est l'ID de votre projet.
dataset est le nom de l'ensemble de données qui contient la table ou la vue que vous mettez à jour.
table_or_view est le nom de la table ou de la vue que vous mettez à jour.

Exemple :

Pour mettre à jour le libellé department pour mytable, saisissez la commande bq update et spécifiez department comme clé de libellé. Par exemple, si vous souhaitez remplacer le libellé department:shipping par department:logistics pour mytable, saisissez la commande ci-dessous. mytable se trouve dans myotherproject, et non dans votre projet par défaut.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

La sortie ressemble à ceci :

Table 'myotherproject:mydataset.mytable' successfully updated.

API

Pour ajouter des libellés ou pour mettre à jour un libellé pour une table ou une vue existante, appelez la méthode tables.patch, puis ajoutez ou mettez à jour la propriété labels pour la ressource de table.

Les vues étant traitées comme des ressources de table, la méthode tables.patch vous permet de modifier à la fois des vues et des tables.

En outre, étant donné que la méthode tables.update remplace l'intégralité de la ressource d'ensemble de données, la méthode tables.patch est préférable.

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Cet exemple permet d'envoyer une requête à l'API BigQuery à l'aide de la bibliothèque cliente HTTP Google pour Java.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void runLabelTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    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();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

Mettre à jour des libellés de tâche

Actuellement, il n'est pas possible de mettre à jour des libellés de tâches. Pour mettre à jour le libellé d'une tâche, soumettez à nouveau la tâche en question en spécifiant un nouveau libellé.

Convertir des libellés en tags

Un libellé qui comporte une clé avec une valeur vide fait office de tag. Vous pouvez créer un libellé sans valeur ou convertir un libellé existant en tag sur un ensemble de données, une table ou une vue. En revanche, vous ne pouvez pas convertir un libellé de tâche en tag.

Les tags peuvent s'avérer utiles lorsque vous attribuez des libellés à une ressource, mais n'avez pas besoin d'utiliser le format key:value. Par exemple, si vous disposez d'une table qui contient des données de test utilisées par plusieurs groupes (assistance, développement, etc.), vous pouvez lui attribuer le tag test_data pour l'identifier.

Autorisations requises

Pour convertir un libellé en tag, vous devez disposer des autorisations IAM suivantes :

bigquery.datasets.update (permet de convertir un libellé d'ensemble de données)
bigquery.tables.update (permet de convertir un libellé de table ou de vue)

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour convertir un libellé d'ensemble de données :

roles/bigquery.dataOwner
roles/bigquery.admin

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour convertir un libellé de table ou de vue :

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez mettre à jour les libellés des ensembles de données que vous créez et des tables et vues qu'ils contiennent.

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

Convertir un libellé en tag

Pour convertir un libellé en tag, procédez comme suit :

Console

Dans la console Google Cloud, sélectionnez l'ensemble de données, la table ou la vue.
Pour les ensembles de données, la page des détails correspondante s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Détails pour ouvrir la page des détails.
Sur la page des détails, cliquez sur l'icône en forme de crayon située à droite de Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Supprimez la valeur d'un libellé existant.
- Cliquez sur Mettre à jour.

bq

Pour convertir un libellé en tag, exécutez la commande bq update avec l'option set_label. Spécifiez la clé, suivie du caractère deux-points, mais ne renseignez pas la valeur. Cette action permet de transformer un libellé existant en tag.

bq update \
--set_label key: \
resource_id

Où :

key: est la clé de libellé que vous voulez convertir en tag.
resource_id est un nom valide d'ensemble de données, de table ou de vue. Si la ressource se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet en respectant le format suivant : project_id:dataset.

Exemples :

Exécutez la commande suivante pour transformer le libellé test_data:development existant sur mydataset en tag. mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

bq update --set_label test_data: myotherproject:mydataset

La sortie ressemble à ceci :

Dataset 'myotherproject:mydataset' successfully updated.

API

Pour transformer un libellé existant en tag, appelez la méthode datasets.patch ou tables.patch, puis remplacez les valeurs du libellé par la chaîne vide ("") dans la ressource d'ensemble de données ou la ressource de table.

Les vues étant traitées comme des ressources de table, la méthode tables.patch vous permet de modifier à la fois des vues et des tables. En outre, étant donné que la méthode tables.update remplace l'intégralité de la ressource d'ensemble de données, la méthode tables.patch est préférable.

Étape suivante

Apprenez à ajouter des libellés aux ressources BigQuery.
Apprenez à afficher des libellés sur des ressources BigQuery.
Apprenez à filtrer des ressources à l'aide de libellés.
Apprenez à supprimer des libellés sur des ressources BigQuery.
Consultez la documentation Resource Manager pour savoir comment utiliser des libellés.