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 de différentes manières :

  • Utiliser Cloud Console
  • En utilisant la commande bq mk de l'outil de ligne de commande bq
  • En appelant la méthode API datasets.insert
  • Utiliser les bibliothèques clientes
  • Copier un ensemble de données existant

Pour connaître la procédure à suivre pour copier un ensemble de données, y compris entre 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é à l'aide de Cloud Console ou de l'outil de ligne de commande bq, ou bien en appelant les méthodes d'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 emplacement.

  • 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 pour chaque projet.

Nommer des ensembles de données

Lorsque vous créez un ensemble de données dans BigQuery, son nom doit être unique pour chaque projet. Le nom de l'ensemble de données peut contenir les éléments suivants :

  • Jusqu'à 1 024 caractères

  • Lettres (majuscules ou minuscules), chiffres et traits de soulignement

Les noms des ensembles de données 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 d'espaces ni de 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 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 IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Créer un ensemble de données

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

Console

  1. Ouvrez la page "BigQuery" dans Cloud Console.

    Accéder à BigQuery

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

bq

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

Remplacez l'élément suivant :

  • 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. Toutes les tables créées dans l'ensemble de données sont supprimées integer1 secondes après leur création. Cette valeur est appliquée si vous ne définissez pas de délai d'expiration lors de la création de la table.

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

Pour vérifier que l'ensemble de données a bien été créé, saisissez la commande bq ls. Vous pouvez également créer une table lorsque vous créez un ensemble de données. Pour cela, exécutez la commande suivante : 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# 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 de 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 de 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 de 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 de 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 dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery 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 de l'API BigQuery 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, with an explicit timeout.
# Raises google.api_core.exceptions.Conflict if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset, timeout=30)  # 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 de 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