Ajouter et utiliser des étiquettes

Pour vous aider à organiser vos ressources BigQuery, vous pouvez ajouter des étiquettes à vos ensembles de données, tables et vues. Les étiquettes sont des paires clé/valeur que vous pouvez associer à une ressource. Lorsque vous créez des ressources BigQuery, l'attribution de étiquettes est facultative.

Une fois vos ressources étiquetées, vous pouvez les rechercher grâce aux valeurs associées aux étiquettes. Vous pouvez par exemple exploiter les étiquettes pour regrouper des ensembles de données par finalité, par environnement, par service, etc.

Cette page explique comment ajouter des étiquettes à vos ressources BigQuery.

Pour en savoir plus sur la gestion des étiquettes, consultez la page Gérer les étiquettes.

Que sont les étiquettes ?

Une étiquette est une paire clé/valeur qui vous aide à organiser vos ressources BigQuery sur Google Cloud Platform. Vous pouvez associer une étiquette à chaque ressource, puis filtrer les ressources par étiquette. Les informations sur les étiquettes sont transmises au système de facturation afin que vous puissiez consulter le détail des frais apparaissant sur votre facture en fonction des étiquettes.

Cas d'utilisation courants des étiquettes

Voici quelques cas d'utilisation courants des étiquettes :

  • Étiquettes d'équipe ou de centre de coûts : ajoutez des étiquettes en fonction de l'équipe ou du centre de coûts pour distinguer les ressources BigQuery appartenant à différentes équipes (par exemple, team:research et team:analytics). Vous pouvez utiliser ce type d'étiquettes pour la comptabilité analytique ou la budgétisation.

  • Étiquettes de composants : par exemple, component:redis, component:frontend, component:ingest et component:dashboard.

  • Étiquettes d'environnement ou de préproduction : par exemple, environment:production et environment:test.

  • Étiquettes d'état : par exemple, state:active, state:readytodelete et state:archive.

Exigences relatives aux étiquettes

Les étiquettes appliquées à une ressource doivent répondre aux exigences suivantes :

  • Chaque ressource peut posséder plusieurs étiquettes, jusqu'à un maximum de 64.
  • Chaque étiquette doit correspondre à une paire clé/valeur.
  • Les clés doivent comporter un (1) caractère au minimum et 63 au maximum, et ne peuvent pas être vides. Les valeurs peuvent être vides et comporter 63 caractères au maximum.
  • 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.
  • La partie clé d'une étiquette doit être unique. Cependant, vous pouvez utiliser la même clé avec plusieurs ressources.
  • Les clés doivent commencer par une lettre minuscule ou un caractère international.

Ajouter des étiquettes d'ensemble de données

Vous pouvez attribuer une étiquette à un ensemble de données BigQuery lors de sa création en utilisant la commande bq mk de l'outil de ligne de commande ou en appelant la méthode API datasets.insert. Actuellement, il est impossible d'ajouter une étiquette à un ensemble de données lorsque ce dernier est créé via la console GCP ou l'UI Web classique de BigQuery.

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

Lorsque vous ajoutez une étiquette à un ensemble de données, celle-ci est incluse dans vos données de facturation du stockage. Toutefois, les étiquettes de l'ensemble de données ne s'afficheront pas dans vos données de facturation associées aux tâches.

Autorisations requises

Pour ajouter une étiquette à un ensemble de données existant, vous devez disposer d'un accès OWNER au niveau de l'ensemble de données ou détenir au niveau du projet un rôle IAM qui inclut les autorisations bigquery.datasets.update. Voici les rôles IAM prédéfinis au niveau du projet qui incluent les autorisations bigquery.datasets.update :

En outre, comme le rôle bigquery.user dispose des autorisations bigquery.datasets.create, un utilisateur ayant le rôle bigquery.user peut mettre à jour les ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. L'accès OWNER donne à l'utilisateur un contrôle total sur l'ensemble de données.

Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs pour les ensembles de données.

Ajouter une étiquette à un ensemble de données

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

Console

  1. Dans l'UI Web de BigQuery, 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 Labels (Étiquettes).

    Icône en forme de crayon pour modifier une étiquette

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

    • Cliquez sur Ajouter une étiquette.
    • Saisissez une clé et une valeur pour ajouter une étiquette. Pour attribuer des étiquettes supplémentaires, cliquez sur Ajouter une étiquette. 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 une étiquette.
    • Cliquez sur Mettre à jour pour enregistrer vos modifications.

UI classique

  1. Dans l'UI Web de BigQuery, sélectionnez l'ensemble de données.

  2. Sur la page Dataset Details (Détails de l'ensemble de données), cliquez sur le bouton Edit (Modifier) situé à droite du champ Labels (Étiquettes).

    Modifier les étiquettes

  3. Dans la boîte de dialogue Edit Labels (Modifier les étiquettes), effectuez les opérations suivantes :

    • Saisissez une clé et une valeur pour ajouter une étiquette. Pour attribuer des étiquettes supplémentaires, cliquez sur Add Label (Ajouter une étiquette). 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 une étiquette.
    • Cliquez sur OK.

      Nouvelle étiquette

Ligne de commande

Pour ajouter une étiquette à un ensemble de données existant, exécutez la commande bq update en spécifiant le paramètre set_label. Répétez le paramètre pour ajouter plusieurs étiquettes.

Si l'ensemble de données 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 utilisant le format suivant : [PROJECT_ID]:[DATASET].

    bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET]

Où :

  • [KEY:VALUE] correspond à une paire clé/valeur pour une étiquette que vous souhaitez ajouter. La clé doit être unique.
  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] correspond à l'ensemble de données auquel vous ajoutez des étiquettes.

Exemples :

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

    bq update --set_label department:shipping mydataset

Pour attribuer plusieurs étiquettes à un ensemble de données, répétez le paramètre set_label et spécifiez une clé unique pour chaque étiquette. Par exemple, si vous souhaitez attribuer les étiquettes 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 une étiquette à 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.

Comme la méthode datasets.update remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode datasets.patch.

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

Cet exemple permet d'envoyer une requête à l'API BigQuery à l'aide de la bibliothèque cliente HTTP Google pour Java.
static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

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

dataset = client.update_dataset(dataset, ["labels"])  # API request

assert dataset.labels == labels

Ajouter des étiquettes à une table ou à une vue

Vous pouvez attribuer une étiquette à une table ou à une vue lors de sa création en utilisant la commande bq mk dans l'outil de ligne de commande, ou 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'une étiquette lors de la création d'une table ou d'une vue, consultez les sections Créer une table et Créer une vue.

Pour ajouter une étiquette après la création d'une table ou d'une vue, vous pouvez utiliser la console GCP, passer par l'UI Web classique de BigQuery, exécuter la commande bq update de l'outil de ligne de commande ou appeler la méthode API tables.patch. 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 une étiquette à une table ou une vue existante, vous devez disposer d'un accès OWNER au niveau de l'ensemble de données ou détenir au niveau du projet un rôle IAM qui inclut les autorisations bigquery.tables.update. Voici les rôles IAM prédéfinis au niveau du projet qui incluent les autorisations bigquery.tables.update :

En outre, comme le rôle bigquery.user dispose des autorisations bigquery.datasets.create, un utilisateur affecté au rôle bigquery.user peut mettre à jour les tables et les vues des ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. L'accès OWNER donne à l'utilisateur un contrôle total sur l'ensemble de données et sur les tables et vues qu'il contient.

Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs pour les ensembles de données.

Ajouter une étiquette à une table ou à une vue

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

Console

  1. Dans l'UI Web de BigQuery, sélectionnez la table ou la vue.

  2. Cliquez sur l'onglet Details (Détails).

    Détails de la table

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

    Icône en forme de crayon permettant de modifier les étiquettes

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

    • Cliquez sur Ajouter une étiquette.
    • Saisissez une clé et une valeur pour ajouter une étiquette. Pour attribuer des étiquettes supplémentaires, cliquez sur Ajouter une étiquette. 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 une étiquette.
    • Cliquez sur Mettre à jour pour enregistrer vos modifications.

UI classique

Option 1 : Modifier les étiquettes manuellement 1. Dans l'UI Web de BigQuery, sélectionnez la table ou la vue.

  1. Sur la page des détails, cliquez sur le bouton Edit (Modifier) à droite du champ Labels (Étiquettes). L'exemple ci-dessous vous montre les détails d'une table.

    Modifier les étiquettes

  2. Dans la boîte de dialogue Edit Labels (Modifier les étiquettes), effectuez les opérations suivantes :

    • Saisissez une clé et une valeur pour ajouter une étiquette. Pour attribuer des étiquettes supplémentaires, cliquez sur Add Label (Ajouter une étiquette). Chaque clé ne peut être utilisée qu'une seule fois par table ou par vue, mais vous pouvez exploiter la même clé pour plusieurs tables ou vues au sein de différents ensembles de données.
    • Cliquez sur OK.

      Nouvelle étiquette

Option 2 : Utiliser une instruction LDD

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

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

  1. Cliquez sur Saisir une requête.

  2. Saisissez votre instruction DDL dans la zone de texte Nouvelle requête.

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       labels=[("department", "shipping"), ("cost_center", "logistics")]
     )
     

Ligne de commande

Pour ajouter une étiquette à une table ou à une vue existante, exécutez la commande bq update en spécifiant le paramètre set_label. Répétez le paramètre pour ajouter plusieurs étiquettes.

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 utilisant le format suivant : [PROJECT_ID]:[DATASET].

    bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE_OR_VIEW]

Où :

  • [KEY:VALUE] correspond à une paire clé/valeur pour une étiquette que vous souhaitez ajouter. La clé doit être unique.
  • [PROJECT_ID] est l'ID de votre projet.
  • [DATASET] correspond à l'ensemble de données contenant la table ou la vue que vous mettez à jour.
  • [TABLE_OR_VIEW] est le nom de la table ou de la vue à laquelle vous ajoutez des étiquettes.

Exemples :

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

    bq update --set_label department:shipping mydataset.mytable

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

    bq update --set_label department:shipping mydataset.myview

Pour ajouter plusieurs étiquettes à une table ou à une vue, répétez le paramètre set_label et spécifiez une clé unique pour chaque étiquette. Si vous souhaitez par exemple attribuer les étiquettes 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 une étiquette à 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.

Comme la méthode tables.update remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode tables.patch.

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

Cet exemple permet d'envoyer une requête à l'API BigQuery à l'aide de la bibliothèque cliente HTTP Google pour Java.
public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').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 étiquettes à une tâche

Vous pouvez ajouter des étiquettes aux tâches de requêtes via l'indicateur --label de l'outil de ligne de commande. Ce dernier n'accepte l'ajout d'étiquettes que pour les tâches de requêtes.

Vous pouvez également ajouter une étiquette à une tâche soumise 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 étiquettes à tout type de tâche.

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

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

Autorisations requises

Aucune autorisation particulière n'est requise pour ajouter une étiquette à une tâche. Si vous disposez d'autorisations jobs.create, vous pouvez ajouter une étiquette à votre tâche lorsque vous la soumettez.

Pour exécuter une tâche, vous devez disposer des autorisations bigquery.jobs.create. Les autorisations bigquery.jobs.create sont requises pour les tâches qui sont automatiquement créées par BigQuery, et celles que vous exécutez de manière automatisée.

Pour exécuter des tâches BigQuery, vous devez accorder les autorisations bigquery.jobs.create à votre compte utilisateur ou de service, ou lui attribuer un rôle IAM prédéfini au niveau du projet qui comprend les autorisations bigquery.jobs.create. Voici les rôles IAM prédéfinis au niveau du projet qui incluent les autorisations bigquery.jobs.create :

Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès.

Ajouter une étiquette à une tâche

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

Console

L'ajout d'étiquettes aux tâches n'est pas possible via l'UI Web de BigQuery disponible dans la console.

UI classique

L'ajout d'étiquettes aux tâches n'est pas possible via l'UI Web classique de BigQuery.

Ligne de commande

Pour ajouter une étiquette à une tâche de requête, exécutez la commande bq query avec l'indicateur --label. Répétez le paramètre pour ajouter plusieurs étiquettes. L'indicateur --nouse_legacy_sql indique que votre requête est en syntaxe SQL standard.

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

Où :

  • [KEY:VALUE] correspond à une paire clé/valeur pour une étiquette que vous souhaitez ajouter à la tâche de requête. La clé doit être unique. Pour ajouter plusieurs étiquettes à une tâche de requête, répétez l'indicateur --label et spécifiez une clé unique pour chaque étiquette.
  • [QUERY] est une requête SQL standard valide.

Exemples :

Pour ajouter une étiquette à 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 étiquettes à une tâche de requête, répétez l'indicateur --label et spécifiez une clé unique pour chaque étiquette. Par exemple, si vous souhaitez ajouter une étiquette department:shipping et une étiquette 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 une étiquette à une tâche, appelez la méthode jobs.insert et renseignez la propriété labels de la ressource de tâche. Vous pouvez utiliser l'API pour ajouter des étiquettes à tout type de tâche.

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Créer un tag

Une étiquette qui comporte une clé avec une valeur vide fait office de tag. Vous pouvez créer une étiquette sans valeur ou bien transformer une étiquette existant en tag.

Les tags peuvent s'avérer utiles lorsque vous attribuez des étiquettes à une ressource, mais n'avez pas besoin d'utiliser le format clé:valeur. 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.

Pour créer un tag, procédez comme suit :

Console

  1. Dans l'UI Web, sélectionnez la ressource concernée (ensemble de données, table ou vue).

  2. Dans le cas des ensembles de données, la page des détails de l'ensemble de données s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Details (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 Labels (Étiquettes).

    Icône en forme de crayon pour modifier une étiquette

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

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

UI classique

Option 1 : Modifier les étiquettes manuellement

  1. Dans l'UI Web, sélectionnez la ressource concernée (ensemble de données, table ou vue).

  2. Dans le cas des ensembles de données, la page Détails de l'ensemble de données s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Détails pour ouvrir la page des détails.

  3. Sur la page des détails, cliquez sur le bouton Modifier à droite du champ Étiquettes.

  4. Dans la boîte de dialogue Edit Labels (Modifier les étiquettes), effectuez les opérations suivantes :

    • Saisissez une nouvelle clé et laissez la valeur vide. Pour attribuer des tags supplémentaires, cliquez sur Add Label (Ajouter une étiquette).
    • Cliquez sur OK.

      Ajouter un tag

Option 2 : Utiliser une instruction LDD

Les instructions DDL (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

  1. Cliquez sur Saisir une requête.

  2. Saisissez votre instruction DDL dans la zone de texte Nouvelle requête.

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

Ligne de commande

Pour ajouter un tag à une ressource existante, utilisez la commande bq update avec l'indicateur 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]

Où :

  • [KEY] est la clé d'étiquette que vous souhaitez utiliser en tant que 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 au format suivant : [PROJECT_ID]:[DATASET].

Exemples :

Saisissez la commande ci-dessous pour créer un tag test_data pour mydataset.mytable. L'ensemble de données 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 étiquettes ayant pour valeur une chaîne vide ("") dans la ressource d'ensemble de données ou la ressource de table. Vous pouvez transformer des étiquettes existantes 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, comme la méthode tables.update remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode tables.patch.

Afficher des étiquettes

Pour afficher les étiquettes, vous pouvez utiliser l'UI Web de BigQuery, appeler la commande bq show de l'outil de ligne de commande, ou bien appeler la méthode API datasets.get ou tables.get. Comme les vues sont traitées comme des ressources de table, la méthode tables.get vous permet d'obtenir des informations à la fois sur les étiquettes de vue et de table.

Autorisations requises

Les autorisations requises pour afficher des étiquettes dépendent du type de ressource auquel vous accédez.

Autorisations d'ensemble de données

Pour obtenir des informations sur un ensemble de données, vous devez disposer du rôle READER au niveau de l'ensemble de données ou détenir au niveau du projet un rôle IAM qui inclut les autorisations bigquery.datasets.get. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.datasets.get, à l'exception de bigquery.jobUser.

En outre, comme le rôle bigquery.user dispose des autorisations bigquery.datasets.create, un utilisateur affecté au rôle bigquery.user peut obtenir des informations sur les ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. L'accès OWNER donne à l'utilisateur un contrôle total sur l'ensemble de données.

Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs pour les ensembles de données.

Autorisations relatives aux tables et aux vues

Pour obtenir des informations sur des tables, vous devez détenir le rôle READER au niveau de l'ensemble de données, ou un rôle IAM prédéfini au niveau du projet qui comprend les autorisations bigquery.tables.get. Si vous disposez des autorisations bigquery.tables.get au niveau du projet, vous pouvez obtenir des informations sur toutes les tables du projet. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.tables.get, à l'exception de bigquery.user et bigquery.jobUser.

En outre, comme le rôle bigquery.user dispose des autorisations bigquery.datasets.create, un utilisateur affecté au rôle bigquery.user peut obtenir des informations sur les tables et les vues des ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user crée un ensemble de données, il bénéficie d'un accès OWNER à celui-ci. L'accès OWNER à un ensemble de données donne à l'utilisateur un contrôle total sur celui-ci et sur toutes les tables et vues qu'il contient.

Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs pour les ensembles de données.

Autorisations relatives aux tâches

Pour obtenir des données et des métadonnées de tâche, vous devez disposer des autorisations bigquery.jobs.get. Le rôle IAM suivant prédéfini au niveau du projet inclut les autorisations bigquery.jobs.get :

Si vous accordez à un compte le rôle bigquery.admin, l'utilisateur pourra afficher toutes les données de tâche du projet, indépendamment de l'utilisateur ayant envoyé la tâche.

Les rôles suivants disposent des autorisations bigquery.jobs.get pour les tâches créées par vos utilisateurs. Ces utilisateurs ne sont autorisés à afficher les données de tâches que pour les tâches qu'ils envoient :

Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès.

Afficher des étiquettes d'ensemble de données, de table et de vue

Pour afficher les étiquettes d'une ressource, procédez comme suit :

Console

  1. Dans l'UI Web de BigQuery, 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 Details (Détails) pour ouvrir la page des détails. Les informations sur les étiquettes apparaissent dans la table d'informations de la ressource.

    Détails de la table

UI classique

  1. Dans l'UI Web de BigQuery, sélectionnez la ressource concernée (ensemble de données, table ou vue).

  2. Dans le cas des ensembles de données, la page Détails de l'ensemble de données s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Détails pour ouvrir la page des détails. Les informations sur les étiquettes apparaissent dans la table d'informations de la ressource.

Ligne de commande

Exécutez la commande bq show en spécifiant l'ID de ressource. Vous pouvez contrôler le format de sortie à l'aide du paramètre --format. Si la ressource se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet en utilisant le format suivant : [PROJECT_ID]:[DATASET]. Pour améliorer la lisibilité de la sortie, vous pouvez définir le paramètre --format sur pretty.

bq show --format=pretty [RESOURCE_ID]

[RESOURCE_ID] est un nom valide d'ensemble de données, de table ou de vue.

Exemples :

Saisissez la commande suivante pour afficher les étiquettes associées à mydataset dans votre projet par défaut :

bq show --format=pretty mydataset

Saisissez la commande ci-dessous pour afficher les étiquettes associées à mydataset.mytable. L'ensemble de données mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

bq show --format=pretty myotherproject:mydataset.mytable

API

Appelez la méthode datasets.get ou tables.get. La réponse inclut tous les étiquettes associées à cette ressource.

Vous pouvez également afficher les étiquettes de plusieurs ensembles de données à l'aide de datasets.list ou ceux de plusieurs tables et vues à l'aide de tables.list.

Comme les vues sont traitées comme des ressources de table, les méthodes tables.get et tables.list vous permettent d'obtenir des informations à la fois sur les étiquettes de vue et de table.

Go

Cet exemple permet d'envoyer une requête à l'API BigQuery à l'aide de la bibliothèque cliente HTTP Google pour Java.
// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}
fmt.Fprintf(w, "Dataset %s labels:\n", datasetID)
if len(meta.Labels) == 0 {
	fmt.Fprintln(w, "Dataset has no labels defined.")
	return nil
}
for k, v := range meta.Labels {
	fmt.Fprintf(w, "\t%s:%s\n", k, v)
}

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # API request

# View dataset labels
print("Dataset ID: {}".format(dataset_id))
print("Labels:")
if dataset.labels:
    for label, value in dataset.labels.items():
        print("\t{}: {}".format(label, value))
else:
    print("\tDataset has no labels defined.")

Afficher les étiquettes d'une tâche

Une fois la tâche de requête soumise, les étiquettes n'apparaissent pas dans l'UI Web de BigQuery. Pour afficher les étiquettes d'une tâche, exécutez la commande bq show -j [JOB_ID].

Console

Vous ne pouvez pas afficher les étiquettes d'une tâche à l'aide de l'UI Web de BigQuery disponible dans la console.

UI classique

Vous ne pouvez pas afficher les étiquettes d'une tâche à l'aide de l'UI Web classique de BigQuery.

CLI

Pour afficher les étiquettes d'une tâche de requête à l'aide de l'outil de ligne de commande bq, saisissez la commande bq show -j avec l'ID de la tâche de requête. Vous pouvez utiliser l'indicateur --format pour contrôler la sortie. Par exemple, si l'ID de votre tâche de requête correspond à bqjob_r1234d57f78901_000023746d4q12_1, saisissez la commande suivante :

bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1

Le résultat doit se présenter sous la forme suivante :

+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| Job Type |  State  |   Start Time    | Duration |    User Email     | Bytes Processed | Bytes Billed |        Labels        |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| query    | SUCCESS | 03 Dec 15:00:41 | 0:00:00  | email@example.com | 255             | 10485760     | department:shipping  |
|          |         |                 |          |                   |                 |              | costcenter:logistics |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+

API

Appelez la méthode jobs.get. La réponse inclut tous les étiquettes associées à cette ressource.

Filtrer des ensembles de données à l'aide d'étiquettes

Pour filtrer des ensembles de données grâce aux étiquettes, créez une spécification de filtre à utiliser dans l'outil de ligne de commande bq ou dans l'API BigQuery, en respectant la syntaxe suivante :

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

Où :

  • field est exprimé au format labels.[KEY], où [KEY] correspond à une clé d'étiquette.
  • value est une valeur d'étiquette facultative.

À l'heure actuelle, vous ne pouvez pas répertorier des tables ou des vues à l'aide d'une spécification de filtre.

Limites

La spécification de filtre présente les limites suivantes :

  • Le seul opérateur logique compatible est l'opérateur "AND". Les comparaisons séparées par des espaces sont traitées comme possédant des opérateurs "AND" implicites.
  • Le seul champ actuellement disponible pour le filtrage est le champ "labels.key", où "key" correspond à un nom d'étiquette.
  • Le filtre peut comprendre jusqu'à dix expressions.
  • Le filtrage est sensible à la casse.
  • Vous ne pouvez pas filtrer des tables ou des vues à l'aide d'une spécification de filtre.
  • À l'heure actuelle, vous ne pouvez pas filtrer des ensembles de données à l'aide de l'UI Web de BigQuery.

Exemples de spécifications de filtre

Pour répertorier les ensembles de données qui possèdent l'étiquette department:shipping, utilisez la spécification de filtre suivante :

labels.department:shipping

Pour répertorier les ensembles de données qui possèdent plusieurs étiquettes, séparez les paires clé/valeur par un espace. L'espace est traité comme un opérateur logique AND. Si vous souhaitez par exemple répertorier les ensembles de données qui possèdent les étiquettes 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 l'étiquette 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. Si vous souhaitez par exemple répertorier les ensembles de données qui possèdent l'étiquette department:shipping et le tag test_data, utilisez la spécification de filtre suivante :

labels.department:shipping labels.test_data

Générer des listes filtrées

Pour générer une liste filtrée d'ensembles de données, procédez comme suit :

Console

À l'heure actuelle, vous ne pouvez pas filtrer les ensembles de données à l'aide de l'UI Web de BigQuery disponible dans la console.

UI classique

À l'heure actuelle, vous ne pouvez pas filtrer les ensembles de données à l'aide de l'UI Web classique de BigQuery.

Ligne de commande

Exécutez la commande bq ls en spécifiant le paramètre --filter. Si vous répertoriez des ensembles de données dans un projet autre que celui par défaut, spécifiez le paramètre --project_id.

bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]

Où :

  • [FILTER_SPECIFICATION] is a valid filter specification. L'outil de ligne de commande renvoie une liste d'ensembles de données répondant aux exigences du filtre.
  • [PROJECT_ID] est l'ID de votre projet.

Exemples :

Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent l'étiquette 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 l'étiquette 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 du projet myotherproject qui possèdent l'étiquette department:shipping :

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

API

Appelez la méthode API datasets.list et incluez 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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Go.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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)
}

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python.

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:  # API request(s)
        print("\t{}".format(dataset.dataset_id))
else:
    print("No datasets found with this filter.")

Étapes suivantes

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.