Créer des ensembles de données

Ce document explique comment créer des ensembles de données dans BigQuery.

Vous pouvez créer des ensembles de données avec l'une des méthodes suivantes :

  • utiliser Cloud Console ou l'UI Web classique de BigQuery ;
  • En exécutant la commande CLI bq mk
  • En appelant la méthode API datasets.insert
  • En utilisant les bibliothèques clientes
  • En copiant un ensemble de données existant

Pour connaître la procédure à suivre pour copier un ensemble de données, y compris sur plusieurs régions, consultez la page Copier des 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 Cloud Console, dans l'UI Web classique 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 situés au même endroit.

  • Lorsque vous copiez 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.

  • Lorsque votre projet contient plusieurs milliers d'ensembles de données, les performances de l'interface utilisateur classique ont tendance à se dégrader. Il faut alors plus de temps pour répertorier les ensembles de données.

Nommer des ensembles de données

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 sensibles à 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 au minimum disposer des autorisations bigquery.datasets.create. Les rôles Cloud IAM prédéfinis suivants incluent les autorisations bigquery.datasets.create :

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.user
  • bigquery.admin

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

Créer un ensemble de données

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

Console

  1. Ouvrez l'UI Web de BigQuery dans Cloud Console.

    Accéder à Cloud Console

  2. Dans la section Ressources du panneau de navigation, sélectionnez votre projet.

  3. Dans le panneau des détails situé à droite, cliquez sur Créer un ensemble de données.

  4. Sur la page Create dataset (Créer un ensemble de données), procédez comme suit :

    • Pour ID de l'ensemble de données, indiquez le nom d'un ensemble de données unique.

    • (Facultatif) Dans la liste déroulante permettant d'indiquer l'emplacement des données, sélectionnez un emplacement géographique pour l'ensemble de données. Si vous conservez la valeur définie sur Par défaut, l'emplacement est défini sur US. Une fois l'ensemble de données créé, l'emplacement ne peut plus être modifié.

    • Pour indiquer le délai d'expiration par défaut de la table, 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.
      • Nombre de jours après la création de la table : cette valeur détermine à quel moment une table nouvellement créée dans l'ensemble de données est supprimée. Cette valeur est appliquée si vous ne définissez pas de délai d'expiration pour la table lors de sa création.

    • Cliquez sur Créer un ensemble de données.

UI classique

  1. Dans la barre de navigation, cliquez sur l'icône de flèche vers le bas flèche vers le bas à côté du nom de votre projet, puis sur Create new dataset (Créer un ensemble de données).

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

    • Pour Dataset ID (ID de l'ensemble de données), indiquez le nom d'un ensemble de données unique.

    • Dans la liste déroulante Data location (Emplacement des données), sélectionnez un emplacement pour l'ensemble de données. La valeur par défaut est Unspecified (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 n 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.

        Data expiration (Expiration des données) représente le délai d'expiration par défaut pour les nouvelles tables créées dans l'ensemble de données. Pour le moment, vous ne pouvez pas définir de délai d'expiration de partition par défaut dans l'interface utilisateur Web de BigQuery lors de la création d'un ensemble de données. Vous pouvez toutefois définir le délai d'expiration de partition par défaut après la création de l'ensemble de données, à l'aide de l'outil de ligne de commande ou de l'API.

    • Cliquez sur OK.

CLI

Pour créer un ensemble de données, exécutez la commande bq mk en spécifiant l'option --location. Les paramètres facultatifs sont --default_table_expiration, --default_partition_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 de la manière suivante : project_id:dataset.

bq --location=location mk \
--dataset \
--default_table_expiration integer1 \
--default_partition_expiration integer2 \
--description description \
project_id:dataset

Où :

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

  • integer1 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 [INTEGER] secondes après sa 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.

  • integer2 est la durée de vie par défaut (en secondes) des partitions des tables partitionnées nouvellement créées. Aucune valeur minimale n'est imposée pour le délai d'expiration par défaut des partitions. Le délai d'expiration correspond à la date de la partition plus la valeur entière. Toute partition créée dans une table partitionnée de l'ensemble de données est supprimée [INTEGER2] secondes après sa date. Si vous spécifiez l'option --time_partitioning_expiration lors de la création ou de la mise à jour d'une table partitionnée, le délai d'expiration des partitions défini au niveau de la table est prioritaire sur le délai d'expiration des partitions défini par défaut au niveau de l'ensemble de données.

  • description est une description de l'ensemble de données entre guillemets.

  • project_id est l'ID du 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 l'emplacement des données défini sur US, une valeur de 3 600 secondes (une heure) pour le délai d'expiration par défaut des tables et la description This is my dataset. Au lieu d'utiliser l'option --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

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# décrite 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 en langage C#. 


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryCreateDataset
{
    public BigQueryDataset CreateDataset(
        string projectId = "your-project-id",
        string location = "US"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var createDatasetOptions = new CreateDatasetOptions()
        {
            // Specify the geographic location where the dataset should reside.
            Location = location
        };
        // Create the dataset
        return client.CreateDataset(
            datasetId: "your_new_dataset_id", options: createDatasetOptions);
    }
}

Go

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

import (
	"context"
	"fmt"

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

// createDataset demonstrates creation of a new dataset using an explicit destination location.
func createDataset(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 := &bigquery.DatasetMetadata{
		Location: "US", // See https://cloud.google.com/bigquery/docs/locations
	}
	if err := client.Dataset(datasetID).Create(ctx, meta); err != nil {
		return err
	}
	return nil
}

Java

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

public class CreateDataset {

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

  public static void createDataset(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();

      DatasetInfo datasetInfo = DatasetInfo.newBuilder(datasetName).build();

      Dataset newDataset = bigquery.create(datasetInfo);
      String newDatasetName = newDataset.getDatasetId().getDataset();
      System.out.println(newDatasetName + " created successfully");
    } catch (BigQueryException e) {
      System.out.println("Dataset was not created. \n" + e.toString());
    }
  }
}

Node.js

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

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

async function createDataset() {
  // Creates a new dataset named "my_dataset".

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

  // Specify the geographic location where the dataset should reside
  const options = {
    location: 'US',
  };

  // Create a new dataset
  const [dataset] = await bigquery.createDataset(datasetId, options);
  console.log(`Dataset ${dataset.id} created.`);
}
createDataset();

PHP

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP décrite 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 en langage 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 d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite 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 en langage 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 create.
# dataset_id = "{}.your_dataset".format(client.project)

# Construct a full Dataset object to send to the API.
dataset = bigquery.Dataset(dataset_id)

# TODO(developer): 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.Conflict if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset)  # Make an API request.
print("Created dataset {}.{}".format(client.project, dataset.dataset_id))

Ruby

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

require "google/cloud/bigquery"

def create_dataset dataset_id = "my_dataset", location = "US"
  bigquery = Google::Cloud::Bigquery.new

  # Create the dataset in a specified geographic location
  bigquery.create_dataset dataset_id, location: location

  puts "Created dataset: #{dataset_id}"
end

Étapes suivantes