Afficher des étiquettes

Cette page explique comment afficher les libellés de vos ressources BigQuery.

Présentation

Vous pouvez afficher les libellés de plusieurs façons :

Utiliser la console Google Cloud
En interrogeant des vues INFORMATION_SCHEMA
En utilisant la commande bq show de l'outil de ligne de commande bq
En appelant les méthodes d'API datasets.get ou tables.get
En utilisant les bibliothèques clientes

Les vues étant 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 vue et de table.

Avant de commencer

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document.

Autorisations requises

Les autorisations requises pour afficher des libellés dépendent des types de ressources auxquels vous pouvez accéder. Pour effectuer les tâches décrites dans ce document, vous devez disposer des autorisations suivantes.

Autorisations pour afficher les détails de l'ensemble de données

Pour afficher les détails d'un ensemble de données, vous devez disposer de l'autorisation IAM bigquery.datasets.get.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour afficher les détails de l'ensemble de données :

roles/bigquery.user
roles/bigquery.metadataViewer
roles/bigquery.dataViewer
roles/bigquery.dataOwner
roles/bigquery.dataEditor
roles/bigquery.admin

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez afficher les détails des ensembles de données que vous créez.

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

Autorisations pour afficher les détails d'une table ou d'une vue

Pour afficher les détails d'une table ou d'une vue, vous devez disposer de l'autorisation IAM bigquery.tables.get.

Tous les rôles IAM prédéfinis incluent les autorisations dont vous avez besoin pour afficher les détails de la table ou de la vue, à l'exception de roles/bigquery.user et roles/bigquery.jobUser.

De plus, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez afficher les détails des tables et des vues des ensembles de données que vous créez.

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

Autorisations pour afficher les détails de la tâche

Pour afficher les détails d'une tâche, vous devez disposer de l'autorisation IAM bigquery.jobs.get.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour afficher les détails de la tâche :

roles/bigquery.admin (vous permet d'afficher les détails de toutes les tâches du projet)
roles/bigquery.user (vous permet d'afficher les détails de vos tâches)
roles/bigquery.jobUser (vous permet d'afficher les détails de vos tâches)

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

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

Pour afficher les libellés d'une ressource, sélectionnez l'une des options suivantes :

Console

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 libellés apparaissent dans la table d'informations de la ressource.

SQL

Interrogez la vue INFORMATION_SCHEMA.SCHEMATA_OPTIONS pour afficher les libellés d'un ensemble de données ou la vue INFORMATION_SCHEMA.TABLE_OPTIONS pour afficher les libellés d'une table. Par exemple, la requête SQL suivante renvoie les libellés sur l'ensemble de données nommé mydataset :

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

Accéder à BigQuery

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

SELECT
  *
FROM
  INFORMATION_SCHEMA.SCHEMATA_OPTIONS
WHERE
  schema_name = 'mydataset'
  AND option_name = 'labels';

Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

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

bq show --format=pretty [RESOURCE_ID]

Où [RESOURCE_ID] est un ensemble de données, une table, une vue ou une tâche valide.

Exemples :

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

bq show --format=pretty mydataset

La sortie ressemble à ceci :

+-----------------+--------------------------------------------------------+---------------------+
|  Last modified  |                          ACLs                          |       Labels        |
+-----------------+--------------------------------------------------------+---------------------+
| 11 Jul 19:34:34 | Owners:                                                | department:shipping |
|                 |   projectOwners,                                       |                     |
|                 | Writers:                                               |                     |
|                 |   projectWriters                                       |                     |
|                 | Readers:                                               |                     |
|                 |   projectReaders                                       |                     |
+-----------------+--------------------------------------------------------+---------------------+

Saisissez la commande ci-dessous pour afficher les libellés associés à mydataset.mytable. mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

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

Pour une table en cluster, le résultat ressemble à ce qui suit :

+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+
|  Last modified  |            Schema            | Total Rows | Total Bytes |   Expiration    |               Time Partitioning                | Clustered Fields | Labels  |
+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+
| 25 Jun 19:28:14 | |- timestamp: timestamp      | 0          | 0           | 25 Jul 19:28:14 | DAY (field: timestamp, expirationMs: 86400000) | customer_id      | org:dev |
|                 | |- customer_id: string       |            |             |                 |                                                |                  |         |
|                 | |- transaction_amount: float |            |             |                 |                                                |                  |         |
+-----------------+------------------------------+------------+-------------+-----------------+------------------------------------------------+------------------+---------+

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 utiliser datasets.list pour afficher les libellés de plusieurs ensembles de données ou tables.list pour afficher les libellés de plusieurs tables et vues.

Les vues étant 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 vue et de table.

Go

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Go.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// printDatasetLabels retrieves label metadata from a dataset and prints it to an io.Writer.
func printDatasetLabels(w io.Writer, projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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)
	}
	return nil
}

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

// Sample to get dataset labels
public class GetDatasetLabels {

  public static void runGetDatasetLabels() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    getDatasetLabels(datasetName);
  }

  public static void getDatasetLabels(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Dataset dataset = bigquery.getDataset(datasetName);
      dataset
          .getLabels()
          .forEach((key, value) -> System.out.println("Retrieved labels successfully"));
    } catch (BigQueryException e) {
      System.out.println("Label was not found. \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getDatasetLabels() {
  // Gets labels on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();
  const labels = metadata.labels;

  console.log(`${datasetId} Labels:`);
  for (const [key, value] of Object.entries(labels)) {
    console.log(`${key}: ${value}`);
  }
}
getDatasetLabels();

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.

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

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// tableLabels demonstrates fetching metadata from a table and printing the Label metadata to an io.Writer.
func tableLabels(w io.Writer, projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Table %s labels:\n", datasetID)
	if len(meta.Labels) == 0 {
		fmt.Fprintln(w, "Table has no labels defined.")
		return nil
	}
	for k, v := range meta.Labels {
		fmt.Fprintf(w, "\t%s:%s\n", k, v)
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;

// Sample to get table labels
public class GetTableLabels {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    getTableLabels(datasetName, tableName);
  }

  public static void getTableLabels(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      table
          .getLabels()
          .forEach((key, value) -> System.out.println("Retrieved labels successfully"));
    } catch (BigQueryException e) {
      System.out.println("Label was not deleted. \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getTableLabels() {
  // Gets labels on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Retrieve current dataset metadata.
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();
  const labels = metadata.labels;

  console.log(`${tableId} Labels:`);
  for (const [key, value] of Object.entries(labels)) {
    console.log(`${key}: ${value}`);
  }
}
getTableLabels();

Python

from google.cloud import bigquery

client = bigquery.Client()

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

table = client.get_table(table_id)  # API Request

# View table labels
print(f"Table ID: {table_id}.")
if table.labels:
    for label, value in table.labels.items():
        print(f"\t{label}: {value}")
else:
    print("\tTable has no labels defined.")

Afficher les libellés d'une tâche

Pour afficher les libellés d'une tâche, sélectionnez l'une des options suivantes :

SQL

Interrogez les vues INFORMATION_SCHEMA.JOB_BY_* pour afficher les libellés d'une tâche. Par exemple, la requête SQL suivante renvoie le texte de la requête et les libellés des tâches envoyées par l'utilisateur actuel dans le projet en cours :

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

Accéder à BigQuery

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

SELECT
  query,
  labels
FROM
  INFORMATION_SCHEMA.JOBS_BY_USER;

Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

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 contrôler le résultat à l'aide de l'option --format. 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.

Étapes suivantes

Apprenez à ajouter des libellés aux ressources BigQuery.
Apprenez à mettre à jour des libellés sur des ressources BigQuery.
Apprenez à filtrer des ressources à l'aide de libellés.
Apprenez à supprimer des libellés sur des ressources BigQuery.
Consultez la documentation Resource Manager pour savoir comment utiliser des libellés.