Ajouter des libellés à des ressources

Cette page explique comment ajouter des étiquettes à vos 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. Toutes les autorisations requises pour effectuer une tâche sont répertoriées dans la section "Rôles IAM requis" de la tâche.

Ajouter des libellés à des ensembles de données

Vous pouvez ajouter un libellé à un ensemble de données BigQuery lors de sa création en utilisant la commande bq mk de l'outil de ligne de commande bq ou en appelant la méthode API datasets.insert. Actuellement, il est impossible d'ajouter un libellé à un ensemble de données lorsque celui-ci est créé à l'aide de la console Google Cloud.

Cette page explique comment ajouter un libellé à un ensemble de données une fois celui-ci créé. Pour en savoir plus sur l'ajout d'un libellé lors de la création d'un ensemble de données, consultez la section Créer un ensemble de données.

Vous pouvez ajouter un libellé à un ensemble de données après sa création de l'une des manières suivantes :

  • 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
  • utiliser les bibliothèques clientes.

Lorsque vous ajoutez un libellé à un ensemble de données, celui-ci ne se propage pas aux ressources de l'ensemble de données. Les libellés d'ensemble de données ne sont pas hérités par les tables ou les vues. En outre, lorsque vous ajoutez un libellé à un ensemble de données, celui-ci est inclus dans vos données de facturation du stockage, mais pas dans vos données de facturation associées aux tâches.

Pour plus d'informations sur le format des libellés, consultez la section Exigences relatives aux libellés.

Rôles IAM requis

Pour obtenir l'autorisation dont vous avez besoin pour ajouter un libellé à un ensemble de données existant, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de données BigQuery (roles/bigquery.dataEditor). Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation bigquery.datasets.update, qui est requise pour ajouter un libellé à un ensemble de données existant.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

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

Ajouter une étiquette à un ensemble de données

Pour ajouter un libellé à un ensemble de données une fois celui-ci créé, procédez comme suit :

Console

  1. Dans la console Google Cloud, sélectionnez l'ensemble de données.

  2. 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.

    Icône en forme de crayon pour modifier un libellé

  3. Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :

    • Cliquez sur Add label (Ajouter un libellé).
    • Saisissez la clé et la valeur. Pour attribuer des libellés supplémentaires, cliquez sur Add label (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.
    • Pour mettre à jour un libellé, modifiez les clés ou valeurs existantes.
    • Pour enregistrer vos modifications, cliquez sur Mettre à jour.

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 libellé sur l'ensemble de données mydataset :

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

    Accéder à BigQuery

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

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

  3. 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 un libellé à un ensemble de données existant, exécutez la commande bq update avec l'option set_label. Répétez l'option pour ajouter plusieurs libellés.

Si l'ensemble de données se trouve dans un projet autre que votre projet par défaut, ajoutez l'ID du 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

Remplacez l'élément suivant :

  • KEY:VALUE : paire clé-valeur pour un libellé que vous souhaitez ajouter. La clé doit être unique. Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés.
  • PROJECT_ID : ID de votre projet.
  • DATASET : ensemble de données auquel vous ajoutez un libellé.

Exemples :

Pour ajouter un libellé permettant de surveiller tout un service, saisissez la commande bq update et spécifiez department comme clé de libellé. Si vous souhaitez par exemple attribuer le libellé department:shipping à mydataset dans votre projet par défaut, saisissez la commande suivante :

    bq update --set_label department:shipping mydataset

Pour attribuer plusieurs libellés à un ensemble de données, répétez l'option set_label et spécifiez une clé unique pour chaque libellé. Si vous souhaitez par exemple ajouter des libellés department:shipping et cost_center:logistics à mydataset dans votre projet par défaut, saisissez la commande suivante :

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset

API

Pour ajouter un libellé à un ensemble de données existant, appelez la méthode datasets.patch et renseignez 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.

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 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 main(String[] args) {
    // 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.

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

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.


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

Ajouter des libellés à des tables et à des vues

Vous pouvez attribuer un libellé à une table ou à une vue lors de sa création de l'une des manières suivantes :

  • En exécutant la commande bq mk de l'outil de ligne de commande bq
  • En appelant la méthode API tables.insert

Cette page explique comment ajouter une étiquette à une table ou à une vue existante. Pour en savoir plus sur l'ajout d'un libellé lors de la création d'une table ou d'une vue, consultez les sections Créer une table et Créer une vue.

Vous pouvez ajouter un libellé après la création d'une table ou d'une vue de l'une des manières suivantes :

  • 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
  • utiliser les bibliothèques clientes.

Comme les vues sont traitées comme des ressources de table, la méthode tables.patch permet de modifier à la fois des vues et des tables.

Rôles IAM requis

Pour obtenir les autorisations nécessaires pour ajouter un libellé à une table ou à une vue existante, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de données BigQuery (roles/bigquery.dataEditor). Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour ajouter un libellé à une table ou à une vue existante. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour ajouter une étiquette à une table ou à une vue existante :

  • bigquery.tables.update
  • bigquery.tables.get

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

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

Ajouter une étiquette à une table ou à une vue

Pour ajouter un libellé à une table ou à une vue existante, procédez comme suit :

Console

  1. Dans la console Google Cloud, sélectionnez la table ou la vue.

  2. Cliquez sur l'onglet Détails.

    Détails de la table.

  3. Cliquez sur l'icône en forme de crayon située à droite de Labels (Libellés).

    Icône en forme de crayon pour modifier un libellé

  4. Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :

    • Cliquez sur Add label (Ajouter un libellé).
    • Saisissez une clé et une valeur pour ajouter un libellé. Pour attribuer des libellés supplémentaires, cliquez sur Add label (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 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 :

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

    Accéder à BigQuery

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

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

  3. 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 un libellé à une table ou à une vue existante, exécutez la commande bq update avec l'option set_label. Pour ajouter plusieurs libellés, répétez l'option.

Si la table ou la vue se trouve dans un projet autre que celui par défaut, ajoutez l'ID du 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

Remplacez l'élément suivant :

  • KEY:VALUE : paire clé-valeur pour un libellé que vous souhaitez ajouter. La clé doit être unique. Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés.
  • PROJECT_ID : ID de votre projet.
  • DATASET : ensemble de données contenant la table ou la vue à laquelle vous ajoutez un libellé.
  • TABLE_OR_VIEW : nom de la table ou de la vue à laquelle vous ajoutez un libellé.

Exemples :

Pour ajouter un libellé de table permettant de surveiller tout un service, saisissez la commande bq update et spécifiez department comme clé de libellé. Si vous souhaitez par exemple attribuer le libellé department:shipping à mytable dans votre projet par défaut, saisissez la commande suivante :

    bq update --set_label department:shipping mydataset.mytable

Pour ajouter un libellé de vue permettant de surveiller tout un service, saisissez la commande bq update et spécifiez department comme clé de libellé. Si vous souhaitez par exemple attribuer le libellé department:shipping à myview dans votre projet par défaut, saisissez la commande suivante :

    bq update --set_label department:shipping mydataset.myview

Pour attribuer plusieurs libellés à une table ou à une vue, répétez l'option set_label et spécifiez une clé unique pour chaque libellé. Si vous souhaitez par exemple attribuer les libellés department:shipping et cost_center:logistics à mytable dans votre projet par défaut, saisissez la commande suivante :

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset.mytable

API

Pour ajouter un libellé à une table ou à une vue existante, appelez la méthode tables.patch et renseignez la propriété labels de la ressource de table.

Comme les vues sont traitées comme des ressources de table, la méthode tables.patch 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

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

// 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.

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.

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 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 main(String[] args) {
    // 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

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.

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 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

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.

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.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # API request

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

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

print(f"Added {table.labels} to {table_id}.")

Ajouter des libellés à des tâches

Vous pouvez ajouter des libellés aux jobs de requête via l'option --label de l'outil de ligne de commande bq. L'outil bq n'accepte l'ajout d'étiquettes que pour les jobs de requête.

Vous pouvez également ajouter un libellé à une tâche envoyée via l'API en spécifiant la propriété labels dans la configuration de la tâche lorsque vous appelez la méthode jobs.insert. L'API peut être utilisée pour ajouter des libellés à tout type de tâche.

Vous ne pouvez pas ajouter de libellés à des tâches en attente, en cours ou terminées (ni mettre à jour les libellés).

Lorsque vous ajoutez une étiquette à une tâche, celle-ci est incluse dans vos données de facturation.

Rôles IAM requis

Pour obtenir l'autorisation dont vous avez besoin pour ajouter un libellé à un job, demandez à votre administrateur de vous attribuer le rôle IAM Utilisateur BigQuery (roles/bigquery.user). Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation bigquery.jobs.create, qui est requise pour ajouter un libellé à un job.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

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

Ajouter une étiquette à une tâche

Pour ajouter un libellé à une tâche, procédez comme suit :

bq

Pour ajouter un libellé à une tâche de requête, exécutez la commande bq query avec l'option --label. Pour ajouter plusieurs libellés, répétez l'option. L'option --nouse_legacy_sql indique que votre requête utilise la syntaxe GoogleSQL.

bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'

Remplacez les éléments suivants :

  • KEY:VALUE : paire clé-valeur pour un libellé que vous souhaitez ajouter à la tâche de requête. La clé doit être unique. Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés. Pour ajouter plusieurs libellés à une tâche de requête, répétez l'option --label et spécifiez une clé unique pour chaque libellé.
  • QUERY : requête GoogleSQL valide.

Exemples :

Pour ajouter un libellé à une tâche de requête, saisissez la commande suivante :

    bq query \
    --label department:shipping \
    --nouse_legacy_sql \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

Pour ajouter plusieurs libellés à une tâche de requête, répétez l'option --label et spécifiez une clé unique pour chaque libellé. Si vous souhaitez par exemple ajouter des libellés department:shipping et cost_center:logistics à une tâche de requête, saisissez la commande suivante :

    bq query \
    --label department:shipping \
    --label cost_center:logistics \
    --nouse_legacy_sql \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

API

Pour ajouter un libellé à une tâche, appelez la méthode jobs.insert et renseignez la propriété labels de la configuration de tâche. Vous pouvez utiliser l'API pour ajouter des étiquettes à tout type de tâche.

Associer des tâches dans une session avec un libellé

Si vous exécutez des requêtes dans une session, vous pouvez attribuer un libellé à toutes les futures tâches de requête de la session à l'aide de requêtes à plusieurs instructions BigQuery.

SQL

Définissez la variable système @@query_label dans la session en exécutant la requête suivante :

  SET @@query_label = "KEY:VALUE";
  

  • KEY:VALUE : paire clé-valeur pour le libellé à attribuer à toutes les requêtes futures de la session. La clé doit être unique. Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés.

Exemple :

  SET @@query_label = "cost_center:logistics";
  

API

Pour ajouter un libellé à une tâche de requête dans une session lorsque vous exécutez une requête à l'aide d'un appel d'API, appelez la méthode jobs.insert et remplissez la propriété query_label pour la configuration de la tâche connectionProperties.

Après avoir associé un libellé de requête à une session et exécuté des requêtes dans la session, vous pouvez collecter des journaux d'audit pour les requêtes portant ce libellé. Pour en savoir plus, consultez la documentation de référence sur les journaux d'audit pour BigQuery.

Ajouter un libellé sans valeur

Un libellé qui comporte une clé avec une valeur vide est parfois appelé "tag". Il ne faut pas le confondre avec une ressource de tag. Pour en savoir plus, consultez la section Libellés et tags. Vous pouvez créer un libellé sans valeur ou supprimer une valeur d'une clé de libellé existante.

Les libellés sans valeurs peuvent s'avérer utiles lorsque vous attribuez des libellés à une ressource, mais que vous n'avez pas besoin d'utiliser le format clé-valeur. Par exemple, si une table contient des données de test utilisées par plusieurs groupes, tels que l'assistance ou le développement, vous pouvez lui attribuer le libellé test_data pour l'identifier.

Pour ajouter un libellé sans valeur :

Console

  1. Dans la console Google Cloud, sélectionnez la ressource concernée (ensemble de données, table ou vue).

  2. 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.

    Détails de la table.

  3. Sur la page des détails, cliquez sur l'icône en forme de crayon située à droite de Libellés.

    Icône en forme de crayon pour modifier un libellé

  4. Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :

    • Cliquez sur Add label (Ajouter un libellé).
    • Saisissez une nouvelle clé et laissez la valeur vide. Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé et répétez l'opération.
    • Pour enregistrer vos modifications, cliquez sur Mettre à jour.

SQL

Pour ajouter un libellé sans valeur, utilisez l'instruction LDD ALTER TABLE SET OPTIONS :

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

    Accéder à BigQuery

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

    ALTER TABLE mydataset.mytable
    SET OPTIONS (
      labels=[("key1", ""), ("key2", "")]);

  3. 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 un libellé sans valeur à une ressource existante, 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.

bq update --set_label KEY: RESOURCE_ID

Remplacez les éléments suivants :

  • KEY: : clé de libellé que vous souhaitez utiliser.
  • RESOURCE_ID : 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 :

Saisissez la commande suivante pour créer un libellé test_data pour mydataset.mytable. mydataset se trouve dans votre projet par défaut.

bq update --set_label test_data: mydataset

API

Appelez la méthode datasets.patch ou tables.patch, puis ajoutez des libellés ayant pour valeur une chaîne vide ("") dans la ressource d'ensemble de données ou la ressource de table. Vous pouvez supprimer des valeurs de libellés existants en les remplaçant par une chaîne vide.

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