Répertorier les ensembles de données

Ce document explique comment répertorier des ensembles de données dans BigQuery et obtenir des informations à leur sujet.

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.

Rôle requis

Pour obtenir l'autorisation dont vous avez besoin pour répertorier des ensembles de données ou obtenir des informations sur ceux-ci, demandez à votre administrateur de vous attribuer le rôle IAM "Lecteur de métadonnées BigQuery" (roles/bigquery.metadataViewer) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ce rôle prédéfini contient l'autorisation bigquery.datasets.get, qui est requise pour répertorier les ensembles de données ou obtenir des informations les concernant.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Lorsque vous appliquez le rôle roles/bigquery.metadataViewer au niveau du projet ou de l'organisation, vous pouvez répertorier tous les ensembles de données du projet. Lorsque vous appliquez le rôle roles/bigquery.metadataViewer au niveau de l'ensemble de données, vous pouvez lister tous les ensembles de données pour lesquels vous avez obtenu ce rôle.

Répertorier des ensembles de données

Sélectionnez l'une des options suivantes :

Console

Dans le menu de navigation, cliquez sur BigQuery Studio.
Dans le panneau Explorateur, développez un nom de projet pour afficher les ensembles de données qu'il contient ou utilisez le champ de recherche pour effectuer une recherche par nom d'ensemble de données.

SQL

Interrogez la vue INFORMATION_SCHEMA.SCHEMATA :

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
SELECT
  schema_name
FROM
  PROJECT_ID.`region-REGION`.INFORMATION_SCHEMA.SCHEMATA;
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud. Si non spécifié, le projet par défaut est utilisé.
- REGION : tout nom de région d'ensemble de données. Exemple :us
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 ls pour répertorier les ensembles de données par ID. Vous pouvez contrôler le résultat à l'aide de l'option --format. Si vous répertoriez un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'option --project_id à la commande.

Pour répertorier tous les ensembles de données d'un projet, y compris les ensembles de données masqués, utilisez l'option --all ou le raccourci -a.

Pour répertorier tous les ensembles de données d'un projet, à l'exception des ensembles de données masqués, utilisez l'option --datasets ou le raccourci -d. Cette option est facultative. Par défaut, les ensembles de données masqués ne sont pas répertoriés.

Les options supplémentaires comprennent les éléments suivants :

--filter : permet de répertorier les ensembles de données qui correspondent à l'expression de filtre. Utilise une liste de clés de libellés et de valeurs séparées par des espaces au format labels.key:value. Pour en savoir plus sur le filtrage des ensembles de données à l'aide de libellés, consultez la page Filtrer des ressources à l'aide de libellés.
--max_results ou -n : entier indiquant le nombre maximal de résultats. La valeur par défaut est 50.

bq ls --filter labels.key:value \
--max_results integer \
--format=prettyjson \
--project_id project_id

Remplacez les éléments suivants :

key:value : clé et valeur de libellé
integer : entier représentant le nombre d'ensembles de données à lister
project_id : nom de votre projet

Exemples :

Saisissez la commande suivante pour répertorier les ensembles de données dans votre projet par défaut. L'élément -- format est défini sur "pretty" pour renvoyer une table au format de base.

bq ls --format=pretty

Saisissez la commande suivante pour répertorier les ensembles de données dans myotherproject. L'élément --format est défini sur prettyjson pour renvoyer les résultats détaillés au format JSON.

bq ls --format=prettyjson --project_id myotherproject

Saisissez la commande suivante pour répertorier tous les ensembles de données, y compris les ensembles de données masqués, dans votre projet par défaut. Dans le résultat, les ensembles de données masqués commencent par un trait de soulignement.

bq ls -a

Saisissez la commande suivante pour renvoyer plus de résultats que la sortie par défaut, correspondant à 50 ensembles de données dans votre projet par défaut.

bq ls --max_results 60

Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut avec le libellé org:dev.

bq ls --filter labels.org:dev

API

Pour répertorier les ensembles de données à l'aide de l'API, appelez la méthode API datasets.list.

C#

Avant d'essayer cet exemple, suivez les instructions de configuration pour C# 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 C#.

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.


using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryListDatasets
{
    public void ListDatasets(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Retrieve list of datasets in project
        List<BigQueryDataset> datasets = client.ListDatasets().ToList();
        // Display the results
        if (datasets.Count > 0)
        {
            Console.WriteLine($"Datasets in project {projectId}:");
            foreach (var dataset in datasets)
            {
                Console.WriteLine($"\t{dataset.Reference.DatasetId}");
            }
        }
        else
        {
            Console.WriteLine($"{projectId} does not contain any datasets.");
        }
    }
}

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.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listDatasets demonstrates iterating through the collection of datasets in a project.
func listDatasets(projectID string, w io.Writer) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	it := client.Datasets(ctx)
	for {
		dataset, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, dataset.DatasetID)
	}
	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.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.DatasetListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;

public class ListDatasets {

  public static void runListDatasets() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    listDatasets(projectId);
  }

  public static void listDatasets(String projectId) {
    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();

      Page<Dataset> datasets = bigquery.listDatasets(projectId, DatasetListOption.pageSize(100));
      if (datasets == null) {
        System.out.println("Dataset does not contain any models");
        return;
      }
      datasets
          .iterateAll()
          .forEach(
              dataset -> System.out.printf("Success! Dataset ID: %s ", dataset.getDatasetId()));
    } catch (BigQueryException e) {
      System.out.println("Project does not contain any datasets \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 listDatasets() {
  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = "my_project_id";

  // Lists all datasets in the specified project.
  // If projectId is not specified, this method will take
  // the projectId from the authenticated BigQuery Client.
  const [datasets] = await bigquery.getDatasets({projectId});
  console.log('Datasets:');
  datasets.forEach(dataset => console.log(dataset.id));
}

PHP

Avant d'essayer cet exemple, suivez les instructions de configuration pour PHP 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 PHP.

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$datasets = $bigQuery->datasets();
foreach ($datasets as $dataset) {
    print($dataset->id() . PHP_EOL);
}

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()

datasets = list(client.list_datasets())  # Make an API request.
project = client.project

if datasets:
    print("Datasets in project {}:".format(project))
    for dataset in datasets:
        print("\t{}".format(dataset.dataset_id))
else:
    print("{} project does not contain any datasets.".format(project))

Ruby

Avant d'essayer cet exemple, suivez les instructions de configuration pour Ruby 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 Ruby.

require "google/cloud/bigquery"

def list_datasets project_id = "your-project-id"
  bigquery = Google::Cloud::Bigquery.new project: project_id

  puts "Datasets in project #{project_id}:"
  bigquery.datasets.each do |dataset|
    puts "\t#{dataset.dataset_id}"
  end
end

Obtenir des informations sur les ensembles de données

Sélectionnez l'une des options suivantes :

Console

Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Développez l'option Actions puis cliquez sur Ouvrir. La description et les détails s'affichent dans le panneau de détails. Les tables d'un ensemble de données sont répertoriées avec le nom de l'ensemble de données dans le panneau Explorateur.

Par défaut, les ensembles de données masqués sont masqués dans la console Google Cloud. Pour afficher des informations sur des ensembles de données masqués, utilisez l'outil de ligne de commande bq ou l'API.

SQL

Interrogez la vue INFORMATION_SCHEMA.SCHEMATA :

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

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
SELECT
  * EXCEPT (schema_owner)
FROM
  PROJECT_ID.`region-REGION`.INFORMATION_SCHEMA.SCHEMATA;
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud. Si non spécifié, le projet par défaut est utilisé.
- REGION : tout nom de région d'ensemble de données. Exemple :us
Cliquez sur Exécuter.

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

Vous pouvez également interroger la vue INFORMATION_SCHEMA.SCHEMATA_OPTIONS.

SELECT
  *
FROM
  PROJECT_ID.`region-REGION`.INFORMATION_SCHEMA.SCHEMATA_OPTIONS;

bq

Exécutez la commande bq show. L'option --format peut être utilisée pour contrôler le résultat. Si vous souhaitez obtenir des informations sur un ensemble de données dans un projet autre que celui par défaut, ajoutez l'ID du projet au nom de l'ensemble de données, en respectant le format suivant : project_id:dataset.

Pour afficher des informations sur un ensemble de données masqué, exécutez la commande bq ls --all pour répertorier tous les ensembles de données, puis utilisez le nom de l'ensemble de données masqué dans la commande bq show.

bq show --format=prettyjson project_id:dataset

Remplacez les éléments suivants :

project_id est le nom de votre projet.
dataset est le nom de l'ensemble de données.

Exemples :

Saisissez la commande suivante pour afficher des informations sur mydataset dans votre projet par défaut :

bq show --format=prettyjson mydataset

Saisissez la commande suivante pour afficher des informations sur mydataset dans myotherproject.

bq show --format=prettyjson myotherproject:mydataset

Saisissez la commande suivante pour afficher des informations sur l'ensemble de données masqué _1234abcd56efgh78ijkl1234 dans votre projet par défaut.

bq show --format=prettyjson _1234abcd56efgh78ijkl1234

API

Appelez la méthode datasets.get et définissez tous les paramètres pertinents.

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// printDatasetInfo demonstrates fetching dataset metadata and printing some of it to an io.Writer.
func printDatasetInfo(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 ID: %s\n", datasetID)
	fmt.Fprintf(w, "Description: %s\n", meta.Description)
	fmt.Fprintln(w, "Labels:")
	for k, v := range meta.Labels {
		fmt.Fprintf(w, "\t%s: %s", k, v)
	}
	fmt.Fprintln(w, "Tables:")
	it := client.Dataset(datasetID).Tables(ctx)

	cnt := 0
	for {
		t, err := it.Next()
		if err == iterator.Done {
			break
		}
		cnt++
		fmt.Fprintf(w, "\t%s\n", t.TableID)
	}
	if cnt == 0 {
		fmt.Fprintln(w, "\tThis dataset does not contain any tables.")
	}
	return nil
}

Java

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetId;
import com.google.cloud.bigquery.Table;

public class GetDatasetInfo {

  public static void runGetDatasetInfo() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    getDatasetInfo(projectId, datasetName);
  }

  public static void getDatasetInfo(String projectId, 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();
      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Dataset dataset = bigquery.getDataset(datasetId);

      // View dataset properties
      String description = dataset.getDescription();
      System.out.println(description);

      // View tables in the dataset
      // For more information on listing tables see:
      // https://javadoc.io/static/com.google.cloud/google-cloud-bigquery/0.22.0-beta/com/google/cloud/bigquery/BigQuery.html
      Page<Table> tables = bigquery.listTables(datasetName, TableListOption.pageSize(100));

      tables.iterateAll().forEach(table -> System.out.print(table.getTableId().getTable() + "\n"));

      System.out.println("Dataset info retrieved successfully.");
    } catch (BigQueryException e) {
      System.out.println("Dataset info not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

async function getDataset() {
  // Retrieves dataset named "my_dataset".

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

  // Retrieve dataset reference
  const [dataset] = await bigquery.dataset(datasetId).get();

  console.log('Dataset:');
  console.log(dataset.metadata.datasetReference);
}
getDataset();

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.

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
friendly_name = dataset.friendly_name
print(
    "Got dataset '{}' with friendly_name '{}'.".format(
        full_dataset_id, friendly_name
    )
)

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

# View tables in dataset.
print("Tables:")
tables = list(client.list_tables(dataset))  # Make an API request(s).
if tables:
    for table in tables:
        print("\t{}".format(table.table_id))
else:
    print("\tThis dataset does not contain any tables.")

Vérifier le nom de l'ensemble de données

Les exemples suivants montrent comment vérifier si un ensemble de données existe:

Java

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

// Sample to check dataset exist
public class DatasetExists {

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

  public static void datasetExists(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(DatasetId.of(datasetName));
      if (dataset != null) {
        System.out.println("Dataset already exists.");
      } else {
        System.out.println("Dataset not found.");
      }
    } catch (BigQueryException e) {
      System.out.println("Something went wrong. \n" + e.toString());
    }
  }
}

Python

from google.cloud import bigquery
from google.cloud.exceptions import NotFound

client = bigquery.Client()

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

try:
    client.get_dataset(dataset_id)  # Make an API request.
    print("Dataset {} already exists".format(dataset_id))
except NotFound:
    print("Dataset {} is not found".format(dataset_id))

Étapes suivantes

Pour en savoir plus sur la création des ensembles de données, consultez la page Créer des ensembles de données.
Pour en savoir plus sur l'attribution de contrôles d'accès aux ensembles de données, consultez la page Contrôler l'accès aux ensembles de données.
Pour en savoir plus sur la modification des propriétés d'un ensemble de données, consultez la page Mettre à jour les propriétés d'un ensemble de données.
Pour savoir comment créer et gérer des libellés, consultez la page sur la création et la gestion des libellés.
Pour obtenir une présentation de INFORMATION_SCHEMA, consultez la page Présentation de BigQuery INFORMATION_SCHEMA.