Ajouter et utiliser 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 explique comment ajouter des libellés à vos ressources BigQuery.

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

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.

Ajouter 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. Actuellement, vous ne pouvez pas ajouter de libellé à un ensemble de données lorsqu'il est créé via l'interface utilisateur Web de BigQuery.

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.

Lorsque vous ajoutez un libellé à un ensemble de données, celui-ci est inclus dans vos données de facturation du stockage. Toutefois, les libellés 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 un libellé à 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 un libellé à un ensemble de données

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

UI Web

  1. Dans l'UI Web, 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 (Libellés).

    Modifier les libellés

  3. Dans la boîte de dialogue Edit Labels (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 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 OK.

      Nouveau libellé

Ligne de commande

Pour ajouter un libellé à 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 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 à une paire clé/valeur pour un libellé 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 libellés.

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 le paramètre set_label et spécifiez une clé unique pour chaque libellé. Par exemple, si vous souhaitez 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 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.

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 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 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 en utilisant 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 de tester cet exemple, suivez la procédure de configuration de Python 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()
# 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 libellés à une table ou à une 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.

Cette page explique comment ajouter un libellé à 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 en utilisant l'UI Web de BigQuery, la commande bq update de l'outil de ligne de commande ou 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 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 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 un libellé à une table ou à une vue

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

UI Web

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

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

    Modifier les libellés

  3. Dans la boîte de dialogue Edit Labels (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 Add Label (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 de différents ensembles de données.
    • Cliquez sur OK.

      Nouveau libellé

Ligne de commande

Pour ajouter un libellé à 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 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 à une paire clé/valeur pour un libellé 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 libellés.

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é. Par exemple, si vous souhaitez 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é. Par exemple, si vous souhaitez 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 ajouter 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 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.

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 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 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 en utilisant 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 de tester cet exemple, suivez la procédure de configuration de Python 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()
# 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 libellés à une tâche

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

Vous pouvez également ajouter un libellé à une tâche soumise via l'API en spécifiant la propriété labels dans la ressource de 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

Aucune autorisation particulière n'est requise pour ajouter un libellé à une tâche. Si vous disposez d'autorisations jobs.create, vous pouvez ajouter un libellé à 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 un libellé à une tâche

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

UI Web

L'ajout de libellés aux tâches n'est pas possible via l'UI Web de BigQuery.

Ligne de commande

Pour ajouter un libellé à 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 libellés. 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 un libellé que vous souhaitez ajouter à la tâche de requête. La clé doit être unique. Pour ajouter plusieurs libellés à une tâche de requête, répétez l'indicateur --label et spécifiez une clé unique pour chaque libellé.
  • [QUERY] est une 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'indicateur --label et spécifiez une clé unique pour chaque libellé. Par exemple, si vous souhaitez ajouter un libellé department:shipping et un libellé 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 ressource de tâche. Vous pouvez utiliser l'API pour ajouter des libellés à tout type de tâche.

Go

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go 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 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

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

  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 Libellés.

  4. Dans la boîte de dialogue Edit Labels (Modifier les libellés), 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 un libellé).
    • Cliquez sur OK.

      Ajouter un tag

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é 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 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 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, 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 libellés

Vous pouvez afficher les libellés à l'aide de l'UI Web de BigQuery, de l'outil de ligne de commande bq show, ou des méthodes datasets.get ou tables.get de l'API. 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 disposer d'un accès READER 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.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 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

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

[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 la méthode 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 à l'aide de datasets.list ou 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 libellés de vues et de tables.

Go

Cet exemple permet d'envoyer une requête à l'API BigQuery en utilisant 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 de tester cet exemple, suivez la procédure de configuration de Python 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()
# 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 libellés d'une tâche

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

UI Web

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

CLI

Pour afficher les libellés 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 libellés associés à cette ressource.

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

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go 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 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 de tester cet exemple, suivez la procédure de configuration de Python 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()

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