Créer et utiliser des ensembles de données

Ce document décrit comment créer et utiliser des ensembles de données dans BigQuery. Après avoir créé un ensemble de données, vous pouvez :

  • affecter des contrôles d'accès à vos ensembles de données ;
  • obtenir des informations sur vos ensembles de données ;
  • lister vos ensembles de données ;
  • obtenir des métadonnées d'ensembles de données à l'aide de métatables.

Pour en savoir plus sur la gestion des ensembles de données et apprendre à mettre à jour leurs propriétés, à les renommer, les supprimer et les copier, consultez la section Gérer les ensembles de données.

Limites des ensembles de données

Les ensembles de données BigQuery sont soumis aux limitations suivantes :

  • Vous ne pouvez définir l'emplacement géographique qu'au moment de la création. Une fois qu'un ensemble de données a été créé, l'emplacement devient immuable et ne peut plus être modifié dans l'interface utilisateur Web de BigQuery, via l'outil de ligne de commande, ou en appelant les méthodes API patch ou update.
  • Toutes les tables référencées dans une requête doivent être stockées dans des ensembles de données au même endroit.

  • Lors de la copie d'une table, les ensembles de données contenant la table source et la table de destination doivent se trouver au même emplacement.

  • Les noms d'ensembles de données doivent être uniques par projet.
  • À mesure que vous approchez des milliers d'ensembles de données pour un projet, les performances de l'interface utilisateur Web commencent à se dégrader et les ensembles de données deviennent plus long à répertorier.

Créer des ensembles de données

Vous pouvez créer des ensembles de données en accédant à l'UI Web de BigQuery, en utilisant la commande CLI bq mk ou en appelant la méthode API datasets.insert.

Lorsque vous créez un ensemble de données dans BigQuery, il doit avoir un nom unique par projet. Les noms d'ensembles de données :

  • peuvent contenir jusqu'à 1 024 caractères ;
  • peuvent contenir des lettres (majuscules ou minuscules), des chiffres et des traits de soulignement ;

  • sont sensible à la casse (mydataset et MyDataset peuvent coexister dans le même projet).

Les noms d'ensembles de données ne peuvent pas :

  • contenir des espaces ou des caractères spéciaux (tels que -, &, @ ou %).

Autorisations requises

Pour créer un ensemble de données, vous devez détenir le rôle primitif au niveau du projet ou un rôle IAM prédéfini qui comprend les autorisations bigquery.datasets.create. Les rôles IAM prédéfinis au niveau du projet qui sont présentés ci-dessous incluent les autorisations bigquery.datasets.create :

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

Créer un ensemble de données

Pour créer un ensemble de données, procédez comme suit :

UI Web

  1. Dans le volet de navigation, cliquez sur la flèche vers le bas flèche vers le bas à côté du nom de votre projet, puis sur Créer un ensemble de données.

  2. Dans la boîte de dialogue Create Dataset (Créer un ensemble de données), procédez comme suit :

    • Pour Dataset ID (ID de l'ensemble de données), renseignez un ensemble de données unique.
    • Pour Data location (Emplacement des données), sélectionnez un emplacement pour l'ensemble de données. La valeur par défaut est Non spécifié : elle définit l'emplacement de l'ensemble de données sur US. Une fois l'ensemble de données créé, l'emplacement ne peut plus être modifié.

    • Pour Data expiration (Expiration des données), choisissez l'une des options suivantes :

      • Never (Jamais) : (Par défaut) Les tables créées dans l'ensemble de données ne sont jamais supprimées automatiquement. Vous devez les supprimer manuellement.
      • In [INTEGER] days (Dans [INTEGER] jours) : Toutes les tables créées dans l'ensemble de données sont supprimées [INTEGER] jours après leur création. Cette valeur est appliquée si vous ne définissez pas de délai d'expiration pour la table lors de sa création.

        Créer un ensemble de données

    • Cliquez sur OK.

Ligne de commande

Exécutez la commande bq mk avec l'indicateur --location pour créer un ensemble de données. Les paramètres facultatifs incluent --default_table_expiration et --description. Pour créer un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données, au format suivant : [PROJECT_ID]:[DATASET].
bq --location=[LOCATION] mk --dataset --default_table_expiration [INTEGER] --description [DESCRIPTION] [PROJECT_ID]:[DATASET]

Où :

  • [LOCATION] est l'emplacement de l'ensemble de données. Une fois l'ensemble de données créé, la zone ne peut plus être modifiée. Vous pouvez spécifier une valeur par défaut pour votre zone à l'aide du fichier .bigqueryrc.

  • [INTEGER] est la durée de vie par défaut (en secondes) des tables nouvellement créées. La valeur minimale est de 3 600 secondes (une heure). Le délai d'expiration correspond à l'heure actuelle plus la valeur entière. Toute table créée dans l'ensemble de données est supprimée lorsque le nombre de secondes défini par la valeur [INTEGER] au moment de sa création est écoulé. Cette valeur est appliquée si vous ne définissez pas de délai d'expiration pour la table lors de sa création.

  • [DESCRIPTION] est une description de l'ensemble de données entre guillemets.
  • [PROJECT_ID] correspond à l'ID de votre projet.
  • [DATASET] est le nom de l'ensemble de données que vous créez.

Par exemple, la commande suivante crée un ensemble de données nommé mydataset avec la zone de données définie sur US, une expiration de table par défaut de 3 600 secondes (1 heure) et une description de This is my dataset. Au lieu d'utiliser l'indicateur --dataset, la commande utilise le raccourci -d. Si vous omettez -d et --dataset, la commande crée un ensemble de données par défaut.

bq --location=US mk -d --default_table_expiration 3600 --description "This is my dataset." mydataset

Vous pouvez saisir la commande bq ls pour confirmer la création de l'ensemble de données. Vous pouvez également créer une table lorsque vous créez un ensemble de données à l'aide du format : bq mk -t [DATASET].[TABLE]. Pour en savoir plus sur la création des tables, consultez la section Créer une table.

API

Appelez la méthode datasets.insert avec une ressource d'ensemble de données définie.

C#

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

public void CreateDataset(string datasetId, BigQueryClient client)
{
    var dataset = client.GetOrCreateDataset(datasetId);
}

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")
meta := &bigquery.DatasetMetadata{
	Location: "US", // Create the dataset in the US.
}
if err := client.Dataset(datasetID).Create(ctx, meta); err != nil {
	return err
}

Java

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

Dataset dataset = null;
DatasetInfo datasetInfo = DatasetInfo.newBuilder(datasetName).build();
try {
  // the dataset was created
  dataset = bigquery.create(datasetInfo);
} catch (BigQueryException e) {
  // the dataset was not created
}

Node.js

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

// Imports the Google Cloud client library
const BigQuery = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = "your-project-id";
// const datasetId = "my_new_dataset";

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

// Creates a new dataset
bigquery
  .createDataset(datasetId)
  .then(results => {
    const dataset = results[0];
    console.log(`Dataset ${dataset.id} created.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

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

use Google\Cloud\BigQuery\BigQueryClient;

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

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->createDataset($datasetId);
printf('Created dataset %s' . PHP_EOL, $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 sur l'API BigQuery Python.

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

# Create a DatasetReference using a chosen dataset ID.
# The project defaults to the Client's project if not specified.
dataset_ref = client.dataset(dataset_id)

# Construct a full Dataset object to send to the API.
dataset = bigquery.Dataset(dataset_ref)
# Specify the geographic location where the dataset should reside.
dataset.location = 'US'

# Send the dataset to the API for creation.
# Raises google.api_core.exceptions.AlreadyExists if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset)  # API request

Ruby

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

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id

bigquery.create_dataset dataset_id

puts "Created dataset: #{dataset_id}"

Affecter des contrôles d'accès aux ensembles de données

Vous partagez l'accès aux tables et vues BigQuery à l'aide des rôles IAM au niveau du projet et des contrôles d'accès au niveau des ensembles de données. Actuellement, vous ne pouvez pas appliquer de contrôles d'accès directement aux tables ou aux vues.

Les contrôles d'accès au niveau du projet déterminent les utilisateurs, les groupes et les comptes de service autorisés à accéder à tous les ensembles de données, tables, vues et données de table dans un projet. Les contrôles d'accès au niveau des ensembles de données déterminent les utilisateurs, les groupes et les comptes de service autorisés à accéder aux tables, aux vues et aux données de table dans un ensemble de données spécifique.

Par exemple, si vous attribuez le rôle bigquery.dataOwner à un utilisateur au niveau du projet, cet utilisateur est autorisé à créer, mettre à jour et supprimer des tables et des vues dans tous les ensembles de données du projet. Si vous attribuez le rôle OWNER au niveau de l'ensemble de données, l'utilisateur n'est autorisé à créer, mettre à jour et supprimer des tables et des vues que dans cet ensemble de données. Le rôle primitif OWNER au niveau de l'ensemble de données équivaut au rôle bigquery.dataOwner de l'ensemble de données.

Si vous affectez des rôles plus restrictifs aux utilisateurs ou aux groupes au niveau du projet, vous devez également accorder l'accès aux ensembles de données individuels. Par exemple, si vous accordez à un utilisateur ou à un groupe d'utilisateurs le rôle bigquery.user au niveau du projet, l'utilisateur concerné pourra créer des ensembles de données et exécuter des tâches de requête sur les tables de ces ensembles de données. Pour interroger des tables dans des ensembles de données que l'utilisateur n'a pas créés, vous devez attribuer à l'utilisateur un accès READER minimal au niveau de l'ensemble de données pour chaque ensemble de données à interroger. Le rôle primitif READER au niveau de l'ensemble de données équivaut au rôle bigquery.dataViewer de l'ensemble de données.

Pour en savoir plus sur les rôles IAM prédéfinis au niveau du projet et les contrôles d'accès au niveau des ensembles de données, consultez la section Contrôle des accès.

Autorisations requises

Pour appliquer ou mettre à jour les contrôles d'accès 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 un rôle IAM au niveau du projet qui comprend les autorisations bigquery.datasets.update. Les rôles IAM prédéfinis au niveau du projet qui sont présentés ci-dessous 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 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 de l'ensemble de données, consultez la section Rôles primitifs pour les ensembles de données.

Contrôler l'accès aux ensembles de données

Vous pouvez appliquer des contrôles d'accès à un ensemble de données après sa création à l'aide de l'interface utilisateur Web classique de BigQuery ou de la commande CLI bq update. Les contrôles des accès ne peuvent pas être appliqués lors de la création de l'ensemble de données à l'aide de l'UI ou de l'outil de ligne de commande.

L'API vous permet d'appliquer des contrôles d'accès pendant la création de votre ensemble de données en appelant la méthode datasets.insert, ou une fois votre ensemble de données créé en appelant la méthode datasets.patch.

Lorsque vous appliquez des contrôles d'accès à un ensemble de données, vous pouvez accorder l'accès aux utilisateurs et groupes suivants :

  • Utilisateur par e-mail : permet à un compte Google individuel d'accéder à l'ensemble de données.
  • Groupe par e-mail : permet à tous les membres d'un groupe Google d'accéder à l'ensemble de données.
  • Domaine : permet à tous les utilisateurs et groupes d'un domaine Google d'accéder à l'ensemble de données.
  • Tous les utilisateurs authentifiés : permet à tous les titulaires d'un compte Google d'accéder à l'ensemble de données (l'ensemble de données devient public).
  • Propriétaires du projet : permet à tous les propriétaires du projet d'accéder à l'ensemble de données.
  • Lecteurs du projet : permet à tous les lecteurs du projet d'accéder à l'ensemble de données.
  • Éditeurs du projet : permet à tous les éditeurs du projet d'accéder à l'ensemble de données.
  • Vue autorisée : permet à une vue d'accéder à l'ensemble de données.

Pour affecter des contrôles d'accès à un ensemble de données, procédez comme suit :

UI Web

Ces étapes illustrent l'affectation de contrôles d'accès à un ensemble de données via l'interface utilisateur Web classique de BigQuery. Il n'est actuellement pas possible d'affecter des contrôles d'accès à l'aide de l'interface utilisateur Web de BigQuery.
  1. Cliquez sur la flèche du menu déroulant à droite de l'ensemble de données et sélectionnez Partager l'ensemble de données.

  2. Dans la boîte de dialogue Partager l'ensemble de données, pour Ajouter des personnes, cliquez sur le menu déroulant situé à gauche du champ, puis sélectionnez l'option appropriée.

  3. Saisissez une valeur dans la zone de texte. Par exemple, si vous avez choisi Utilisateur par e-mail ou Groupe par e-mail, renseignez l'adresse e-mail de l'utilisateur.

  4. À droite du champ Add People (Ajouter des personnes), cliquez sur Can view (Consultation autorisée) et choisissez le rôle approprié dans la liste.

    Ajouter des personnes à un ensemble de données

  5. Cliquez sur Add (Ajouter), puis sur Save changes (Enregistrer les modifications).

Ligne de commande

  1. Écrivez les informations sur l'ensemble de données existant (y compris les contrôles d'accès) dans un fichier JSON à l'aide de la commande show. Si l'ensemble de données se trouve dans un projet autre que votre projet par défaut, ajoutez l'ID de ce projet au nom de l'ensemble de données, au format suivant : [PROJECT_ID]:[DATASET].

    bq show --format=prettyjson [PROJECT_ID]:[DATASET] > [PATH_TO_FILE]
    

    Où :

    • [PROJECT_ID] correspond à l'ID de votre projet.
    • [DATASET] est le nom de votre ensemble de données.
    • [PATH_TO_FILE] est le chemin d'accès au fichier JSON sur votre ordinateur local.

    Exemples :

    Saisissez la commande suivante pour écrire les contrôles d'accès pour mydataset dans un fichier JSON. mydataset se trouve dans votre projet par défaut.

    bq show --format=prettyjson mydataset > /tmp/mydataset.json
    

    Saisissez la commande suivante pour écrire les contrôles d'accès pour mydataset dans un fichier JSON. mydataset se trouve dans myotherproject.

    bq show --format=prettyjson myotherproject:mydataset > /tmp/mydataset.json
    
  2. Apportez vos modifications à la section "access" du fichier JSON. Vous pouvez ajouter ou supprimer n'importe quelle entrée specialGroup : projectOwners, projectWriters, projectReaders et allAuthenticatedUsers. Vous pouvez également ajouter, supprimer ou modifier n'importe lequel des éléments suivants : userByEmail, groupByEmail et domain.

    Par exemple, la section d'accès du fichier JSON d'un ensemble de données peut se présenter sous la forme suivante :

    {
     "access": [
      {
       "role": "READER",
       "specialGroup": "projectReaders"
      },
      {
       "role": "WRITER",
       "specialGroup": "projectWriters"
      },
      {
       "role": "OWNER",
       "specialGroup": "projectOwners"
      },
      {
       "role": "READER",
       "specialGroup": "allAuthenticatedUsers"
      },
      {
       "role": "READER",
       "domain": "[DOMAIN_NAME]"
      },
      {
       "role": "WRITER",
       "userByEmail": "[USER_EMAIL]"
      },
      {
       "role": "READER",
       "groupByEmail": "[GROUP_EMAIL]"
      }
     ],
     ...
    }
    

  3. Une fois les modifications effectuées, utilisez la commande update avec l'indicateur --source pour inclure le fichier JSON. Si l'ensemble de données se trouve dans un projet autre que votre projet par défaut, ajoutez l'ID de ce projet au nom de l'ensemble de données, au format suivant : [PROJECT_ID]:[DATASET].

    bq update --source [PATH_TO_FILE] [PROJECT_ID]:[DATASET]
    

    Où :

    • [PATH_TO_FILE] est le chemin d'accès au fichier JSON sur votre ordinateur local.
    • [PROJECT_ID] correspond à l'ID de votre projet.
    • [DATASET] est le nom de votre ensemble de données.

    Exemples :

    Saisissez la commande suivante pour mettre à jour les contrôles d'accès pour mydataset. mydataset se trouve dans votre projet par défaut.

    bq update --source /tmp/mydataset.json mydataset
    

    Saisissez la commande suivante pour mettre à jour les contrôles d'accès pour mydataset. mydataset se trouve dans myotherproject.

    bq update --source /tmp/mydataset.json myotherproject:mydataset
    
  4. Pour vérifier les modifications de vos contrôles d'accès, saisissez de nouveau la commande show sans écrire les informations dans un fichier.

    bq show --format=prettyjson [DATASET]

    ou

    bq show --format=prettyjson [PROJECT_ID]:[DATASET]

API

Appelez datasets.insert avec une ressource d'ensemble de données définie afin d'appliquer les contrôles d'accès lors de la création de l'ensemble de données. Appelez datasets.patch et servez-vous de la propriété access de la ressource d'ensemble de données pour mettre à jour vos contrôles d'accès.

Comme la méthode datasets.update remplace la ressource d'ensemble de données, il est préférable d'utiliser la méthode datasets.patch afin de mettre à jour les contrôles d'accès.

Pour en savoir plus, consultez la section Ensembles de données.

Go

Définissez la propriété dataset.access_entries avec les contrôles d'accès pour un ensemble de données. Appelez ensuite la fonction client.update_dataset() pour mettre à jour la propriété.

// 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
}
// Append a new access control entry to the existing access list.
update := bigquery.DatasetMetadataToUpdate{
	Access: append(meta.Access, &bigquery.AccessEntry{
		Role:       bigquery.ReaderRole,
		EntityType: bigquery.UserEmailEntity,
		Entity:     "sample.bigquery.dev@gmail.com"},
	),
}

// Leverage the ETag for the update to assert there's been no modifications to the
// dataset since the metadata was originally read.
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

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 sur l'API BigQuery Python.

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

entry = bigquery.AccessEntry(
    role='READER',
    entity_type='userByEmail',
    entity_id='sample.bigquery.dev@gmail.com')
assert entry not in dataset.access_entries
entries = list(dataset.access_entries)
entries.append(entry)
dataset.access_entries = entries

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

assert entry in dataset.access_entries

Utiliser des ensembles de données

Obtenir des informations sur les ensembles de données

Vous pouvez obtenir des informations sur les ensembles de données en accédant à l'UI Web de BigQuery, en utilisant la commande CLI bq show ou en appelant la méthode API datasets.get.

Autorisations requises

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

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 de l'ensemble de données, consultez la section Rôles primitifs pour les ensembles de données.

Obtenir des informations sur les ensembles de données

Pour obtenir des informations sur les ensembles de données d'un projet, procédez comme suit :

UI Web

Cliquez sur le nom de l'ensemble de données. La page Dataset Details (Détails de l'ensemble de données) affiche la description, les détails et les tables de l'ensemble de données.

Afficher l'ensemble de données

Par défaut, les ensembles de données anonymes sont masqués dans l'interface utilisateur Web de BigQuery. Pour afficher des informations sur les ensembles de données anonymes, utilisez l'interface de ligne de commande ou l'API.

Ligne de commande

Exécutez la commande bq show. L'indicateur --format peut être utilisé pour contrôler la sortie. Si vous souhaitez obtenir des informations sur un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet à l'ensemble de données au format suivant : [PROJECT_ID]:[DATASET].

Pour afficher des informations sur un ensemble de données anonyme, 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 anonyme dans la commande bq show.

bq show --format=prettyjson [PROJECT_ID]:[DATASET]

Où :

  • [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 un ensemble de données anonyme _1234abcd56efgh78ijkl1234 dans votre projet par défaut :

bq show --format=prettyjson _1234abcd56efgh78ijkl1234

API

Appelez la méthode API datasets.get et indiquez tous les paramètres pertinents.

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")
meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}

fmt.Printf("Dataset ID: %s\n", datasetID)
fmt.Printf("Description: %s\n", meta.Description)
fmt.Println("Labels:")
for k, v := range meta.Labels {
	fmt.Printf("\t%s: %s", k, v)
}
fmt.Println("Tables:")
it := client.Dataset(datasetID).Tables(ctx)

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

Java

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

DatasetId datasetId = DatasetId.of(projectId, datasetName);
Dataset dataset = bigquery.getDataset(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 sur l'API BigQuery Python.

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

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

# View dataset properties
print('Dataset ID: {}'.format(dataset_id))
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_ref))  # API request(s)
if tables:
    for table in tables:
        print('\t{}'.format(table.table_id))
else:
    print('\tThis dataset does not contain any tables.')

Répertorier des ensembles de données

Vous pouvez répertorier des ensembles de données en accédant à l'UI Web de BigQuery, en utilisant la commande CLI bq ls ou en appelant la méthode API datasets.list.

Autorisations requises

Lorsque vous répertoriez des ensembles de données, seuls les ensembles de données pour lesquels vous disposez des autorisations bigquery.datasets.get sont renvoyés. Cela inclut tous les ensembles de données pour lesquels un accès READER vous a été accordé au niveau de l'ensemble de données. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.datasets.get, à l'exception de bigquery.jobUser. Si vous êtes affecté à un rôle IAM prédéfini au niveau du projet autre que bigquery.jobUser, vous êtes autorisé à répertorier tous les ensembles de données du projet.

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 de l'ensemble de données, consultez la section Rôles primitifs pour les ensembles de données.

Répertorier les ensembles de données dans un projet

Pour répertorier les ensembles de données dans un projet, procédez comme suit :

UI Web

Les ensembles de données sont répertoriés par projet dans le volet de navigation de l'interface utilisateur Web.

Ligne de commande

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'indicateur --format. Si vous répertoriez un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'indicateur --project_id à la commande.

Pour répertorier tous les ensembles de données d'un projet, y compris les ensembles de données anonymes, servez-vous de l'indicateur --all ou du raccourci -a.

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

bq ls --format=prettyjson --project_id [PROJECT_ID]

Où :

  • [PROJECT_ID] est le nom de votre projet.

Exemples :

Saisissez la commande suivante pour répertorier les ensembles de données dans votre projet par défaut.

bq ls --format=prettyjson

Saisissez la commande suivante pour répertorier les ensembles de données dans myotherproject.

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 anonymes. Dans le résultat, les ensembles de données anonymes commencent par un trait de soulignement.

bq ls -a --format=prettyjson

API

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

C#

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

public List<BigQueryDataset> ListDatasets(BigQueryClient client)
{
    var datasets = client.ListDatasets().ToList();
    return datasets;
}

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)
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	fmt.Println(dataset.DatasetID)
}

Java

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

// List datasets in the default project
Page<Dataset> datasets = bigquery.listDatasets(DatasetListOption.pageSize(100));
for (Dataset dataset : datasets.iterateAll()) {
  // do something with the dataset
}
// List datasets in a specified project
Page<Dataset> datasets = bigquery.listDatasets(projectId, DatasetListOption.pageSize(100));
for (Dataset dataset : datasets.iterateAll()) {
  // do something with the dataset
}

Node.js

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

// Imports the Google Cloud client library
const BigQuery = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = "your-project-id";

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

// Lists all datasets in the specified project
bigquery
  .getDatasets()
  .then(results => {
    const datasets = results[0];
    console.log('Datasets:');
    datasets.forEach(dataset => console.log(dataset.id));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP 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 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 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 sur l'API BigQuery Python.

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

datasets = list(client.list_datasets())
project = client.project

if datasets:
    print('Datasets in project {}:'.format(project))
    for dataset in datasets:  # API request(s)
        print('\t{}'.format(dataset.dataset_id))
else:
    print('{} project does not contain any datasets.'.format(project))

Ruby

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

# project_id = "Your Google Cloud project ID"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id

bigquery.datasets.each do |dataset|
  puts dataset.dataset_id
end

Obtenir des métadonnées d'ensembles de données à l'aide de métatables

BigQuery offre des tables spéciales qui représentent les métadonnées, telles que la liste des tables et les vues d'un ensemble de données. Les "métatables" sont en lecture seule. Pour accéder aux métadonnées sur les tables et les vues dans un ensemble de données, servez-vous de la métatable __TABLES_SUMMARY__ dans l'instruction de requête SELECT. Vous pouvez exécuter la requête en accédant à l'UI Web de BigQuery, en utilisant l'outil de ligne de commande bq query ou en appelant la méthode API jobs.insert et en configurant une tâche de requête.

Une requête qui utilise la métatable __TABLES_SUMMARY__ ressemble à ce qui suit :

    SELECT [FIELD] FROM [DATASET].__TABLES_SUMMARY__

Où :

  • DATASET est le nom de votre ensemble de données.
  • FIELD est l'une des valeurs suivantes :
Valeur Description
project_id Nom du projet.
dataset_id Nom de l'ensemble de données.
table_id Nom de la table ou de la vue.
creation_time Heure à laquelle la table ou la vue a été créée, en millisecondes, depuis le 1er janvier 1970 UTC.
type Un entier représentant le type de table : une table régulière (1) ou une vue (2).

Autorisations requises

Pour exécuter une tâche de requête utilisant la métatable __TABLES_SUMMARY__, vous devez disposer des autorisations bigquery.jobs.create. Les rôles IAM suivants, prédéfinis au niveau du projet, incluent les autorisations bigquery.jobs.create :

Vous devez également détenir le rôle READER au niveau de l'ensemble de données ou un rôle IAM au niveau du projet qui comprend les autorisations bigquery.tables.getData. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.tables.getData, à l'exception de bigquery.user, bigquery.jobUser et bigquery.metadataViewer.

Limitations de la métatable

Les métatables BigQuery sont soumises aux limitations suivantes :

  • En règle générale, __TABLES_SUMMARY__ est relativement rapide pour les ensembles de données contenant quelques milliers de tables. Pour les ensembles de données plus importants, __TABLES_SUMMARY__ devient de plus en plus lent et peut dépasser les ressources disponibles.
  • Les métatables ne peuvent pas être utilisées avec la méthode tables.insert.
  • Les métatables ne peuvent pas être utilisées en tant que tables de destination.
  • Les métatables ne sont pas compatibles avec les décorateurs de tables en ancien SQL.
  • Les métatables n'apparaissent pas lorsque vous répertoriez les tables dans un ensemble de données.

Exemples de métatables

La requête suivante récupère toutes les métadonnées pour l'ensemble de données bigquery-public-data.samples.

UI Web

#standardSQL
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

Ligne de commande

bq --location=US query --use_legacy_sql=false '
SELECT
  *
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

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

+----------------------+------------+-----------------+---------------+------+
| project_id           | dataset_id |    table_id     | creation_time | type |
+----------------------+------------+-----------------+---------------+------+
| bigquery-public-data | samples    | github_nested   | 1348782587310 |    1 |
| bigquery-public-data | samples    | github_timeline | 1335915950690 |    1 |
| bigquery-public-data | samples    | gsod            | 1335916040125 |    1 |
| bigquery-public-data | samples    | natality        | 1335916045005 |    1 |
| bigquery-public-data | samples    | shakespeare     | 1335916045099 |    1 |
| bigquery-public-data | samples    | trigrams        | 1335916127449 |    1 |
| bigquery-public-data | samples    | wikipedia       | 1335916132870 |    1 |
+----------------------+------------+-----------------+---------------+------+

La requête suivante extrait toutes les tables et les vues de l'ensemble de données bigquery-public-data.samples.

UI Web

#standardSQL
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

Ligne de commande

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

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

+-----------------+
|    table_id     |
+-----------------+
| github_nested   |
| github_timeline |
| gsod            |
| natality        |
| shakespeare     |
| trigrams        |
| wikipedia       |
+-----------------+

La requête suivante répertorie le type de chacune des tables de l'ensemble de données bigquery-public-data.samples.

UI Web

#standardSQL
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`

Ligne de commande

bq --location=US query --use_legacy_sql=false '
SELECT
  table_id, type
FROM
  `bigquery-public-data.samples.__TABLES_SUMMARY__`'

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

+-----------------+------+
|    table_id     | type |
+-----------------+------+
| github_nested   |   1  |
| github_timeline |   1  |
| gsod            |   1  |
| natality        |   1  |
| shakespeare     |   1  |
| trigrams        |   1  |
| wikipedia       |   1  |
+-----------------+------+

Étapes suivantes

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

Envoyer des commentaires concernant…

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