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

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.

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
  • Utiliser des instructions LDD SQL
  • Exécuter 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.

Autorisations requises

Pour ajouter un libellé à un ensemble de données existant, 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 ajouter un libellé à un ensemble de données existant :

  • roles/bigquery.dataOwner
  • roles/bigquery.admin

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez ajouter des libellés aux 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.

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, 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 étiquettes, 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, 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 la page Exécuter des requêtes interactives.

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

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 l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le 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 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 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 l'exemple ci-dessous, suivez la procédure de configuration pour Node.js décrite dans le 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 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 l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le 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 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))

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 :

  • Exécuter 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 :

  • Utiliser la console
  • Exécuter 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.

Autorisations requises

Pour ajouter un libellé à une table ou à une vue existante, vous devez disposer des autorisations IAM suivantes :

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

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

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

De plus, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez ajouter les libellés aux 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.

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, 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 étiquettes, 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, 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 la page Exécuter des requêtes interactives.

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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le 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 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 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 l'exemple ci-dessous, suivez la procédure de configuration pour Node.js décrite dans le 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 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

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 : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery 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

Ajouter des libellés à des tâches

Vous pouvez ajouter des libellés aux tâches de requêtes via l'option --label de l'outil de ligne de commande bq. L'outil bq n'accepte l'ajout de libellés que pour les tâches 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 un libellé à une tâche, celui-ci est inclus dans vos données de facturation.

Autorisations requises

Pour ajouter un libellé à une tâche, vous devez disposer de l'autorisation IAM bigquery.jobs.create.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour ajouter un libellé à une tâche :

  • roles/bigquery.user
  • roles/bigquery.jobUser
  • roles/bigquery.admin

Pour exécuter une tâche BigQuery, vous avez besoin de l'autorisation IAM bigquery.jobs.create. Cette autorisation vous permet d'exécuter des tâches de manière automatisée et accorde des autorisations pour celles qui sont exécutées automatiquement en votre nom par BigQuery.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour exécuter une tâche :

  • roles/bigquery.user
  • roles/bigquery.jobUser
  • roles/bigquery.admin

De plus, lorsque vous créez une tâche, vous recevez automatiquement les autorisations suivantes pour cette tâche :

  • bigquery.jobs.get
  • bigquery.jobs.update

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

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

Remplacez l'élément suivant :

  • 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 SQL standard 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 tag

Un libellé qui comporte une clé avec une valeur vide fait office de tag. Vous pouvez créer un libellé sans valeur ou bien transformer un libellé existant 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 clé:valeur. Par exemple, si une table 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.

Pour ajouter un tag, procédez comme suit :

Console

  1. Dans la console, 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 étiquettes, effectuez les opérations suivantes :

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

SQL

Les instructions LDD (langage de définition de données) vous permettent de créer et de modifier des tables et des vues à l'aide de la syntaxe de requête SQL standard.

En savoir plus sur l'utilisation des instructions de langage de définition de données

Pour ajouter un tag à l'aide d'une instruction LDD dans la console, procédez comme suit :

  1. Cliquez sur Saisir une nouvelle requête.

  2. Saisissez votre instruction LDD dans la zone de texte Query editor (Éditeur de requête).

     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       labels=[("tag1", ""), ("tag2", "")]
     )
     

  3. Cliquez sur Exécuter la requête.

bq

Pour ajouter un tag à 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 l'élément suivant :

  • KEY: : clé de libellé que vous souhaitez utiliser en tant que tag.
  • 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 tag 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 transformer des libellés existants en tags en remplaçant leurs valeurs par une chaîne vide.

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.

Étape suivante