Créer et gérer des libellés

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

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

Cette page décrit comment utiliser des libellés avec vos ressources BigQuery. Elle vous explique également comment ajouter, mettre à jour et supprimer les libellés d'une ressource.

Que sont les libellés ?

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

Cas d'utilisation courants des libellés

Voici quelques cas d'utilisation courants des libellés :

Libellés d'équipe ou de centre de coûts : ajoutez des libellés 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 de libellés pour la comptabilité analytique ou la budgétisation.
Libellés de composant : par exemple, component:redis, component:frontend, component:ingest et component:dashboard.
Libellés d'environnement ou de production : par exemple, environment:production et environment:test.
Libellés de propriétaire ou de contact : ajoutez des libellés en fonction du propriétaire ou d'un contact principal pour les ressources BigQuery.
Libellés d'état : par exemple, state:active, state:readytodelete et state:archive.

Exigences relatives aux libellés

Les libellés appliqués à une ressource doivent répondre aux exigences suivantes :

Chaque ressource peut posséder plusieurs libellés, jusqu'à un maximum de 64.
Chaque libellé 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'un libellé 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.

Créer et mettre à jour des libellés d'ensemble de données

Vous pouvez attribuer 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 ou en appelant la méthode API datasets.insert. 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 ou mettre à jour un libellé après la création d'un ensemble de données en utilisant l'UI Web de BigQuery, la commande bq update de l'outil de ligne de commande, ou en appelant la méthode API datasets.patch.

Autorisations requises

Pour ajouter ou mettre à jour un libellé après la création d'un ensemble de données, 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 comprend les autorisations bigquery.datasets.update. Les rôles IAM prédéfinis au niveau du projet 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 confère à 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 au niveau des ensembles de données.

Créer ou mettre à jour un libellé d'ensemble de données

Pour mettre à jour un libellé d'ensemble de données ou en ajouter un après la création de la ressource, procédez comme suit :

UI Web

Dans l'UI Web, sélectionnez l'ensemble de données.
Sur la page Détails de l'ensemble de données, cliquez sur le bouton Modifier situé à droite du champ Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Saisissez une clé et une valeur pour ajouter un libellé. Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé. Chaque clé ne peut être utilisée qu'une seule fois par ensemble de données, mais vous pouvez exploiter la même clé pour plusieurs ensembles de données au sein d'un même projet.
- Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
- Cliquez sur OK.

Ligne de commande

Pour ajouter ou mettre à jour un libellé d'ensemble de données, exécutez la commande bq update en spécifiant le paramètre set_label. Répétez le paramètre pour ajouter ou mettre à jour plusieurs libellés.

Si l'ensemble de données se trouve dans un projet autre que celui par défaut, ajoutez l'ID 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 à la paire clé/valeur d'un libellé que vous souhaitez créer ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.
[PROJECT_ID] est l'ID de votre projet.
[DATASET] est le nom de l'ensemble de données que vous mettez à jour.

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 mettre à jour le libellé department, saisissez la commande bq update et spécifiez department comme clé de libellé. Si vous souhaitez par exemple remplacer le libellé department:shipping par department:logistics, saisissez la commande ci-dessous. L'ensemble de données mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

    bq update --set_label department:logistics myotherproject:mydataset

Pour attribuer plusieurs libellés à un ensemble de données, répétez le paramètre set_label et spécifiez une clé unique pour chaque libellé. De même, pour supprimer plusieurs libellés associés à un ensemble de données, répétez le paramètre clear_label et spécifiez une paire clé/valeur pour chaque libellé. Si vous souhaitez par exemple attribuer les 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 ou mettre à jour un libellé associé à un ensemble de données existant, appelez la méthode datasets.patch, et ajoutez ou mettez à jour 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 cet exemple, suivez les instructions de configuration de Go décrites 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 Go.

Afficher sur GitHub Commentaires

// 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 en utilisant la bibliothèque cliente HTTP Google pour Java.

Afficher sur GitHub Commentaires

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 cet exemple, suivez les instructions de configuration de Python décrites 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.

Afficher sur GitHub Commentaires

# 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

Créer et mettre à jour des libellés de table et de vue

Vous pouvez attribuer un libellé à 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. 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 ou mettre à jour un libellé après la création d'une table ou d'une vue en utilisant l'UI Web de BigQuery, la commande bq update de l'outil de ligne de commande, ou en appelant 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 créer ou mettre à jour un libellé de table ou de vue, vous devez disposer d'un accès OWNER au niveau de l'ensemble de données, ou détenir un rôle IAM au niveau du projet qui comprend 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 rôles et les autorisations IAM dans BigQuery, consultez la section 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 au niveau des ensembles de données.

Créer ou mettre à jour un libellé de table ou de vue

Pour mettre à jour un libellé de table ou de vue, ou en ajouter un après la création de la ressource, procédez comme suit :

UI Web

Dans l'UI Web, sélectionnez la table ou la vue.
Sur la page des détails, cliquez sur le bouton Modifier situé à droite du champ Libellés. L'exemple ci-dessous vous montre les détails d'une table.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Saisissez une clé et une valeur pour ajouter un libellé. Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé. Chaque clé ne peut être utilisée qu'une seule fois par table ou par vue, mais vous pouvez exploiter la même clé pour plusieurs tables ou vues au sein d'un même projet.
- Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
- Cliquez sur OK.

Ligne de commande

Pour ajouter ou mettre à jour un libellé de table ou de vue, exécutez la commande bq update en spécifiant le paramètre set_label. Répétez le paramètre pour ajouter ou mettre à jour plusieurs libellés.

Si la table ou la vue se trouve dans un projet autre que celui par défaut, ajoutez l'ID 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 à la paire clé/valeur d'un libellé que vous souhaitez créer ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.
[PROJECT_ID] est l'ID de votre projet.
[DATASET] est le nom de l'ensemble de données qui contient la table ou la vue que vous mettez à jour.
[TABLE_OR_VIEW] est le nom de la table ou de la vue que vous mettez à jour.

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 à mytable dans votre projet par défaut, saisissez la commande suivante :

    bq update --set_label department:shipping mydataset.mytable

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 à myview dans votre projet par défaut, saisissez la commande suivante :

    bq update --set_label department:shipping mydataset.myview

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

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

Pour attribuer plusieurs libellés à une table ou à une vue, répétez le paramètre 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 ou mettre à jour un libellé associé à une table ou à une vue existante, appelez la méthode tables.patch et ajoutez ou mettez à jour 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

Afficher sur GitHub Commentaires

// 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 en utilisant la bibliothèque cliente HTTP Google pour Java.

Afficher sur GitHub Commentaires

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

Afficher sur GitHub Commentaires

# 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

Supprimer des libellés

Vous pouvez supprimer un libellé d'un ensemble de données, d'une table ou d'une vue en utilisant l'UI Web de BigQuery, la commande bq update de l'outil de ligne de commande, ou en appelant les méthodes API datasets.patch ou tables.patch.

Supprimer un libellé d'ensemble de données

Pour supprimer un libellé associé à un ensemble de données, vous pouvez utiliser l'UI Web de BigQuery, la commande bq update de l'outil de ligne de commande ou bien appeler la méthode API datasets.patch.

Autorisations requises

Pour supprimer un libellé d'ensemble de données, 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 comprend les autorisations bigquery.datasets.update. Les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.datasets.update :

Supprimer un libellé d'ensemble de données

Pour supprimer un libellé associé à un ensemble de données, procédez comme suit :

UI Web

Dans l'UI Web, sélectionnez l'ensemble de données.
Sur la page Détails de l'ensemble de données, cliquez sur le bouton Modifier situé à droite du champ Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Cliquez sur l'icône de suppression (X) à côté de chaque libellé que vous souhaitez supprimer.
- Cliquez sur OK.

Ligne de commande

Pour ajouter ou mettre à jour un libellé d'ensemble de données, exécutez la commande bq update en spécifiant le paramètre clear_label. Répétez le paramètre pour supprimer plusieurs libellés.

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 --clear_label [KEY] [PROJECT_ID]:[DATASET]

Où :

[KEY] est la clé d'un libellé que vous souhaitez supprimer.
[PROJECT_ID] est l'ID de votre projet.
[DATASET] est le nom de l'ensemble de données que vous mettez à jour.

Exemples :

Pour supprimer le libellé department:shipping de mydataset, saisissez la commande bq update en spécifiant le paramètre --clear_label. L'ensemble de données mydataset se trouve dans votre projet par défaut.

    bq update --clear_label department mydataset

Pour supprimer le libellé department:shipping de mydataset dans le projet myotherproject, saisissez la commande bq update en spécifiant le paramètre --clear_label.

    bq update --clear_label department myotherproject:mydataset

Pour supprimer plusieurs libellés d'un ensemble de données, répétez le paramètre clear_label et spécifiez la clé de chaque libellé. Si vous souhaitez par exemple supprimer les libellés department:shipping et cost_center:logistics de l'ensemble de données mydataset dans votre projet par défaut, saisissez la commande suivante :

    bq update --clear_label department --clear_label cost_center mydataset

API

Pour supprimer un libellé spécifique d'un ensemble de données existant, appelez la méthode datasets.patch et mettez à jour la propriété labels de la ressource d'ensemble de données en définissant la valeur de clé du libellé sur null.

Pour supprimer tous les libellés d'un ensemble de données, appelez la méthode datasets.patch et supprimez la propriété labels.

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

Afficher sur GitHub Commentaires

// 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.DeleteLabel("color")
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

Afficher sur GitHub Commentaires

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

# This example dataset starts with one label
assert dataset.labels == {'color': 'green'}
# To delete a label from a dataset, set its value to None
dataset.labels['color'] = None

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

assert dataset.labels == {}

Supprimer un libellé de table ou de vue

Pour supprimer un libellé de table ou de vue, vous pouvez utiliser l'UI Web de BigQuery, la commande bq update de l'outil de ligne de commande, ou bien 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 supprimer un libellé de table ou de vue, 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 comprend 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 à un ensemble de données confère à l'utilisateur un contrôle total sur celui-ci, et sur toutes les tables et les vues qu'il contient.

Supprimer un libellé de table ou de vue

Pour supprimer un libellé associé à une table ou à une vue, procédez comme suit :

UI Web

Dans l'UI Web, sélectionnez la table ou la vue.
Sur la page Détails, cliquez sur le bouton Modifier situé à droite du champ Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Cliquez sur l'icône de suppression (X) à côté de chaque libellé que vous souhaitez supprimer.
- Cliquez sur OK.

Ligne de commande

Pour supprimer un libellé de table ou de vue, exécutez la commande bq update en spécifiant le paramètre clear_label. Répétez le paramètre pour supprimer plusieurs libellés.

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 --clear_label [KEY] [PROJECT_ID]:[TABLE_OR_VIEW]

Où :

[KEY] est la clé d'un libellé que vous souhaitez supprimer.
[PROJECT_ID] est l'ID de votre projet.
[DATASET] est le nom de l'ensemble de données que vous mettez à jour.
[TABLE_OR_VIEW] est le nom de la table ou de la vue que vous mettez à jour.

Exemples :

Pour supprimer le libellé department:shipping de mydataset.mytable, saisissez la commande bq update en spécifiant le paramètre --clear_label. L'ensemble de données mydataset se trouve dans votre projet par défaut.

    bq update --clear_label department mydataset.mytable

Pour supprimer le libellé department:shipping de mydataset.myview dans le projet myotherproject, saisissez la commande bq update en spécifiant le paramètre --clear_label.

    bq update --clear_label department myotherproject:mydataset.myview

Pour supprimer plusieurs libellés d'une table ou d'une vue, répétez le paramètre clear_label et spécifiez la clé de chaque libellé. Si vous souhaitez par exemple supprimer les libellés department:shipping et cost_center:logistics de la table mydataset.mytable dans votre projet par défaut, saisissez la commande suivante :

    bq update --clear_label department --clear_label cost_center mydataset.mytable

API

Pour supprimer un libellé spécifique d'une table ou d'une vue existante, appelez la méthode tables.patch et mettez à jour la propriété labels de la ressource de table en définissant la valeur de clé du libellé sur null.

Pour supprimer tous les libellés d'une table ou d'une vue, appelez la méthode tables.patch et supprimez la propriété labels.

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.

Go

Afficher sur GitHub Commentaires

// 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.DeleteLabel("color")
if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Python

Afficher sur GitHub Commentaires

# 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

# This example table starts with one label
assert table.labels == {'color': 'green'}
# To delete a label from a table, set its value to None
table.labels['color'] = None

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

assert table.labels == {}

Créer 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 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 :

UI Web

Dans l'UI Web, sélectionnez la ressource concernée (ensemble de données, table ou vue).
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.
Sur la page des détails, cliquez sur le bouton Modifier situé à droite du champ Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Saisissez une nouvelle clé et laissez la valeur vide, ou supprimez la valeur d'un libellé existant. Pour attribuer des tags supplémentaires, cliquez sur Ajouter un libellé.
- Cliquez sur OK.

Ligne de commande

Exécutez la commande bq update en incluant le paramètre set_label. Spécifiez la clé, suivie du caractère deux-points, mais ne renseignez pas la valeur. Cela permet de transformer un libellé existant en tag ou d'ajouter un nouveau tag.

bq update --set_label [KEY]: [RESOURCE_ID]

Où :

[KEY] est la clé de libellé 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 en utilisant le 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

Saisissez la commande ci-dessous pour transformer le libellé existant test_data:development de mydataset en tag. L'ensemble de données mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

bq update --set_label test_data: myotherproject:mydataset

API

Appelez la méthode datasets.patch ou tables.patch et 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.

Afficher des libellés

Vous pouvez afficher des libellés en utilisant l'UI Web de BigQuery, la commande bq show de l'outil de ligne de commande, ou en appelant les méthodes 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 libellés de vues et de tables.

Autorisations requises

Les autorisations requises pour afficher des libellés 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 détenir le rôle READER au niveau de l'ensemble de données, ou un rôle IAM au niveau du projet qui comprenne 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.

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.

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

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

UI Web

Dans l'UI Web, sélectionnez la ressource concernée (ensemble de données, table ou vue).
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 libellés 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]

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

Exemples :

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

bq show --format=pretty mydataset

Saisissez la commande ci-dessous pour afficher les libellés associés à 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 libellés associés à cette ressource.

Vous pouvez également afficher les libellés de plusieurs ensembles de données grâce à la commande datasets.list, ou de plusieurs tables et vues grâce à la commande 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 libellés de vues et de tables.

Go

Afficher sur GitHub Commentaires

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

Afficher sur GitHub Commentaires

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

Filtrer des ensembles de données à l'aide de libellés

Pour filtrer des ensembles de données grâce aux libellés, 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é de libellé.
value est une valeur de libellé 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 de libellé.
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 le libellé department:shipping, utilisez la spécification de filtre suivante :

labels.department:shipping

Pour répertorier les ensembles de données qui possèdent plusieurs libellés, séparez les paires 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 libellés department:shipping et location:usa, utilisez la spécification de filtre suivante :

labels.department:shipping labels.location:usa

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

labels.department

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

labels.department:*

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

labels.department:shipping labels.test_data

Générer des listes filtrées

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

UI Web

À l'heure actuelle, vous ne pouvez pas filtrer des ensembles de données à l'aide de l'UI Web 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] est une spécification de filtre valide. 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 le libellé department:shipping :

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

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

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

Saisissez la commande suivante pour répertorier les ensembles de données du projet myotherproject qui possèdent le libellé 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

Afficher sur GitHub Commentaires

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

Afficher sur GitHub Commentaires

# 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

Découvrez comment ajouter des libellés ou des tags aux ressources dans la documentation de Compute Engine.
Découvrez comment utiliser des libellés dans la documentation de Resource Manager.

Que sont les libellés ?

Cas d'utilisation courants des libellés

Exigences relatives aux libellés

Créer et mettre à jour des libellés d'ensemble de données

Autorisations requises

Créer ou mettre à jour un libellé d'ensemble de données

UI Web

Ligne de commande

API

Go

Java

Python

Créer et mettre à jour des libellés de table et de vue

Autorisations requises

Créer ou mettre à jour un libellé de table ou de vue

UI Web

Ligne de commande

API

Go

Java

Python

Supprimer des libellés

Supprimer un libellé d'ensemble de données

Autorisations requises

Supprimer un libellé d'ensemble de données

UI Web

Ligne de commande

API

Go

Python

Supprimer un libellé de table ou de vue

Autorisations requises

Supprimer un libellé de table ou de vue

UI Web

Ligne de commande

API

Go

Python

Créer un tag

UI Web

Ligne de commande

API

Afficher des libellés

Autorisations requises

Autorisations d'ensemble de données

Autorisations relatives aux tables et aux vues

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

UI Web

Ligne de commande

API

Go

Python

Filtrer des ensembles de données à l'aide de libellés

Limites

Exemples de spécifications de filtre

Générer des listes filtrées

UI Web

Ligne de commande

API

Go

Python

Étapes suivantes

Envoyer des commentaires concernant…