Charger des données par lot

Vous pouvez charger des données dans BigQuery à partir de Cloud Storage ou d'un fichier local en tant qu'opération par lot. Les données sources peuvent avoir l'un des formats suivants :

  • Avro
  • CSV (Comma-Separated Values)
  • JSON (délimité par un retour à la ligne)
  • ORC
  • Parquet
  • Exportations Datastore stockées dans Cloud Storage
  • Exportations Firestore stockées dans Cloud Storage

Vous pouvez configurer des chargements récurrents de Cloud Storage vers BigQuery à l'aide du service de transfert de données BigQuery.

Faites l'essai

Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de BigQuery en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

Profiter d'un essai gratuit de BigQuery

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 de ce document et créer un ensemble de données pour stocker les données.

Autorisations requises

Pour charger des données dans BigQuery, vous devez disposer d'autorisations IAM pour exécuter une tâche de chargement et charger des données dans des tables et partitions BigQuery. Si vous chargez des données à partir de Cloud Storage, vous devez également disposer d'autorisations IAM pour accéder au bucket contenant vos données.

Autorisations pour charger des données dans BigQuery

Pour charger des données dans une nouvelle table ou partition BigQuery, ou pour ajouter ou écraser une table ou une partition existante, vous avez besoin des autorisations IAM suivantes :

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.jobs.create

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour charger des données dans une table ou une partition BigQuery :

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (inclut l'autorisation bigquery.jobs.create)
  • bigquery.user (inclut l'autorisation bigquery.jobs.create)
  • bigquery.jobUser (inclut l'autorisation bigquery.jobs.create)

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez créer et mettre à jour des tables à l'aide d'une tâche de chargement dans les 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 charger des données à partir de Cloud Storage

Pour obtenir les autorisations nécessaires pour charger des données à partir d'un bucket Cloud Storage, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Storage (roles/storage.admin) sur le bucket. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour charger des données à partir d'un bucket Cloud Storage. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour charger des données à partir d'un bucket Cloud Storage :

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

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

Créer un ensemble de données

Créez un ensemble de données BigQuery pour stocker vos données.

Charger des données depuis Cloud Storage

BigQuery permet de charger des données à partir de l'une des classes de stockage Cloud Storage suivantes :

  • Standard
  • Nearline
  • Coldline
  • Archiver

Pour savoir comment charger des données dans BigQuery, consultez la page correspondant à votre format de données :

Pour apprendre à configurer un chargement récurrent de Cloud Storage vers BigQuery, consultez la page Transferts Cloud Storage.

Considérations relatives aux emplacements

Lorsque vous chargez des données à partir de Cloud Storage, elles doivent être colocalisées avec votre ensemble de données BigQuery.

  • Vous pouvez charger des données à partir d'un bucket Cloud Storage situé dans n'importe quel emplacement, si votre ensemble de données BigQuery se trouve dans l'emplacement multirégional US.

  • Bucket multirégional : Si le bucket Cloud Storage à partir duquel vous souhaitez effectuer le chargement se trouve dans un bucket multirégional, votre ensemble de données BigQuery peut se trouver dans le même bucket multirégional ou dans toute région unique incluse dans le même bucket multirégional. Par exemple, si le bucket Cloud Storage se trouve dans la région EU, votre ensemble de données BigQuery peut se trouver dans l'emplacement multirégional EU ou dans n'importe quelle région de EU.

  • Bucket birégional : si le bucket Cloud Storage à partir duquel vous souhaitez effectuer le chargement se trouve dans un bucket birégional, votre ensemble de données BigQuery peut être situé dans des régions incluses dans le bucket birégional, ou dans un emplacement multirégional qui inclut la zone birégionale. Par exemple, si votre bucket Cloud Storage est situé dans la région EUR4, votre ensemble de données BigQuery peut se trouver dans la région unique "Finlande" (europe-north1) ou "Pays-Bas" (europe-west4) unique, ou dans l'emplacement multirégional EU.

  • Bucket à région unique : si le bucket Cloud Storage à partir duquel vous souhaitez effectuer le chargement se trouve dans une région unique, votre ensemble de données BigQuery peut se trouver dans la même région, ou dans l'emplacement multirégional qui inclut l'emplacement régional unique. Par exemple, si votre bucket Cloud Storage se trouve dans la région Finlande (europe-north1), votre ensemble de données BigQuery peut se trouver dans l'emplacement multirégional Finlande ou EU.

  • Si votre ensemble de données BigQuery se trouve dans la région asia-northeast1, votre bucket Cloud Storage peut être situé dans l'emplacement multirégional EU.

Pour en savoir plus sur les emplacements Cloud Storage, consultez la section Emplacements des buckets dans la documentation de Cloud Storage.

Vous ne pouvez pas modifier l'emplacement d'un ensemble de données après sa création. Toutefois, vous pouvez créer une copie de l'ensemble de données ou le déplacer manuellement. Pour en savoir plus, consultez les pages suivantes :

Récupérer l'URI Cloud Storage

Pour charger des données à partir d'une source de données Cloud Storage, vous devez fournir l'URI Cloud Storage.

Le chemin d'accès à la ressource Cloud Storage contient le nom du bucket et l'objet (nom de fichier). Par exemple, si le bucket Cloud Storage est nommé mybucket et que le fichier de données s'appelle myfile.csv, le chemin d'accès à la ressource sera gs://mybucket/myfile.csv.

BigQuery n'accepte pas les chemins de ressource Cloud Storage qui incluent plusieurs barres obliques consécutives après la double barre oblique initiale. Le nom des objets Cloud Storage peut contenir plusieurs barres obliques ("/") consécutives. Toutefois, BigQuery convertit les barres obliques consécutives en une seule. Par exemple, le chemin d'accès à la ressource suivant, bien qu'il soit valide dans Cloud Storage, ne fonctionne pas dans BigQuery : gs://bucket/my//object//name.

Pour récupérer le chemin d'accès à la ressource Cloud Storage, procédez comme suit :

  1. Ouvrez la console Cloud Storage.

    Console Cloud Storage

  2. Accédez à l'emplacement de l'objet (fichier) contenant les données source.

  3. Cliquez sur le nom de l'objet souhaité.

    La page Détails de l'objet s'affiche.

  4. Copiez la valeur fournie dans le champ gsutil URI, qui commence par gs://.

Pour les exportations Google Datastore, vous ne pouvez spécifier qu'un seul URI, qui doit se terminer par .backup_info ou .export_metadata.

Gestion des caractères génériques dans les URI Cloud Storage

Si vos données sont séparées en plusieurs fichiers, vous pouvez utiliser un caractère générique (*) pour sélectionner plusieurs fichiers. Le caractère générique astérisque doit respecter les règles suivantes :

  • Le caractère générique astérisque peut apparaître à l'intérieur ou à la fin du nom de l'objet.
  • Vous ne pouvez pas utiliser plusieurs astérisques. Par exemple, le chemin gs://mybucket/fed-*/temp/*.csv n'est pas valide.
  • Vous ne pouvez pas utiliser d'astérisque avec le nom du bucket.

Exemples :

  • L'exemple suivant montre comment sélectionner tous les fichiers de tous les dossiers commençant par le préfixe gs://mybucket/fed-samples/fed-sample :

    gs://mybucket/fed-samples/fed-sample*

  • L'exemple suivant montre comment sélectionner uniquement les fichiers ayant une extension .csv dans le dossier nommé fed-samples et tous les sous-dossiers de fed-samples :

    gs://mybucket/fed-samples/*.csv

  • L'exemple suivant montre comment sélectionner des fichiers avec un modèle de dénomination fed-sample*.csv dans le dossier nommé fed-samples. Cet exemple ne sélectionne pas les fichiers dans les sous-dossiers de fed-samples.

    gs://mybucket/fed-samples/fed-sample*.csv

Lorsque vous utilisez l'outil de ligne de commande bq, vous devrez peut-être échapper l'astérisque sur certaines plates-formes.

Vous ne pouvez pas utiliser de caractère générique astérisque lorsque vous chargez des données d'exportation Datastore ou Firestore à partir de Cloud Storage.

Limites

Vous êtes soumis aux limitations suivantes lorsque vous chargez des données dans BigQuery à partir d'un bucket Cloud Storage :

  • Si l'emplacement de votre ensemble de données est défini sur une valeur autre que l'emplacement multirégional US, le bucket Cloud Storage doit se trouver dans la même région que l'ensemble de données, ou figurer dans le même emplacement multirégional que celui-ci.
  • BigQuery ne garantit pas la cohérence des données pour les sources de données externes. Les modifications apportées aux données sous-jacentes lors de l'exécution d'une requête peuvent entraîner un comportement inattendu.
  • BigQuery n'est pas compatible avec la gestion des versions d'objets Cloud Storage. Si vous incluez un numéro de génération dans l'URI Cloud Storage, la tâche de chargement échoue.

Selon le format de vos données sources Cloud Storage, des limitations supplémentaires peuvent s'appliquer. Pour en savoir plus, consultez les pages suivantes :

Charger des données à partir de fichiers locaux

Vous pouvez charger des données à partir d'une source de données lisible (telle que votre machine locale) en utilisant l'une des méthodes suivantes :

  • Google Cloud Console
  • Commande bq load de l'outil de ligne de commande bq
  • L'API
  • Bibliothèques clientes

Lorsque vous chargez des données à l'aide de la console Google Cloud ou de l'outil de ligne de commande bq, une tâche de chargement est automatiquement créée.

Pour charger des données depuis une source de données locale, procédez comme suit :

Console

  1. Ouvrez la page BigQuery dans la console Google Cloud.

    Accéder à BigQuery

  2. Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.

  3. Développez l'option Actions puis cliquez sur Ouvrir.

  4. Dans le panneau de détails, cliquez sur Créer une table.

  5. Dans la section Source de la page Créer une table :

    • Dans le champ Create table from (Créer une table à partir de), sélectionnez Upload (Importer).
    • Dans le champ Sélectionner un fichier, cliquez sur Parcourir.
    • Accédez au fichier et cliquez sur Ouvrir. Notez que les caractères génériques et les listes d'éléments séparés par une virgule ne sont pas acceptés pour les fichiers locaux.
    • Dans le champ File format (Format de fichier), sélectionnez CSV, JSON (délimité par un retour à la ligne), Avro, Parquet ou ORC.

  6. Dans la section Destination de la page Créer une table :

    • Dans le champ Projet, sélectionnez le projet approprié.
    • Dans le champ Ensemble de données, sélectionnez l'ensemble de données approprié.
    • Dans le champ Table, saisissez le nom de la table que vous créez dans BigQuery.
    • Vérifiez que Type de table est défini sur Table native.

  7. Dans la section Schema (Schéma), saisissez la définition du schéma.

    • Pour les fichiers CSV et JSON, vous pouvez cocher l'option Auto-detect (Détection automatique) pour activer la détection automatique de schéma. Les informations de schéma sont auto-décrites dans les données sources pour d'autres types de fichiers compatibles.

    • Vous pouvez également saisir les informations du schéma manuellement en utilisant les méthodes suivantes :

      • En cliquant sur Modifier sous forme de texte, puis en saisissant le schéma de la table en tant que tableau JSON :

      • Utilisez l'option Ajouter un champ pour saisir manuellement le schéma.

  8. Sélectionnez les éléments applicables dans la section Options avancées. Pour en savoir plus sur les options disponibles, consultez les options CSV et les options JSON.

  9. (Facultatif) Dans la section Options avancées, sélectionnez la disposition en écriture :

    • Écrire si la table est vide : n'écrit les données que si la table est vide.
    • Ajouter à la table : ajoute les données à la fin de la table. Il s'agit du paramètre par défaut.
    • Écraser la table : efface toutes les données existantes de la table avant d'écrire les nouvelles données.

  10. Cliquez sur Créer une table.

bq

Exécutez la commande bq load, spécifiez source_format et incluez le chemin d'accès au fichier local.

(Facultatif) Spécifiez l'option --location et définissez la valeur correspondant à votre emplacement.

Si vous chargez des données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : PROJECT_ID:DATASET.

bq --location=LOCATION load \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

Remplacez les éléments suivants :

  • LOCATION : votre position. L'option --location est facultative. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'option sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc.
  • FORMAT : CSV, AVRO, PARQUET, ORC ou NEWLINE_DELIMITED_JSON.
  • project_id : ID de votre projet.
  • dataset : ensemble de données existant.
  • table : nom de la table dans laquelle vous chargez des données.
  • path_to_source : chemin d'accès au fichier local.
  • schema : schéma valide. Ce schéma peut être un fichier JSON local ou il peut être intégré à la commande. Vous pouvez également utiliser l'option --autodetect au lieu de fournir une définition de schéma.

En outre, vous pouvez ajouter des options pour les options qui vous permettent de contrôler la manière dont BigQuery analyse vos données. Par exemple, vous pouvez utiliser l'option --skip_leading_rows pour ignorer les lignes d'en-tête dans un fichier CSV. Pour en savoir plus, consultez les sections Options CSV et Options JSON.

Exemples :

La commande suivante charge un fichier JSON local délimité par un retour à la ligne (mydata.json) dans une table nommée mytable de mydataset de votre projet par défaut. Le schéma est défini dans un fichier de schéma local nommé myschema.json.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

La commande suivante charge un fichier CSV local (mydata.csv) dans une table nommée mytable de mydataset du projet myotherproject. Le schéma est défini de manière intégrée au format FIELD:DATA_TYPE, FIELD:DATA_TYPE.

    bq load \
    --source_format=CSV \
    myotherproject:mydataset.mytable \
    ./mydata.csv \
    qtr:STRING,sales:FLOAT,year:STRING

La commande suivante charge un fichier CSV local (mydata.csv) dans une table nommée mytable de mydataset de votre projet par défaut. Le schéma est défini à l'aide de la fonctionnalité de détection automatique du schéma.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    ./mydata.csv

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.

Le code suivant montre comment charger un fichier CSV local dans une nouvelle table BigQuery. Pour charger un fichier local d'un autre format, utilisez la classe d'options de mise à jour pour le format approprié à partir de la classe de base JobCreationOptions au lieu de UploadCsvOptions.


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

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.

            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

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.

Le code suivant montre comment charger un fichier CSV local dans une nouvelle table BigQuery. Pour charger un fichier local d'un autre format, définissez la propriété DataFormat de NewReaderSource sur le format approprié.

import (
	"context"
	"fmt"
	"os"

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

// importCSVFromFile demonstrates loading data into a BigQuery table using a file on the local filesystem.
func importCSVFromFile(projectID, datasetID, tableID, filename 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: %v", err)
	}
	defer client.Close()

	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	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.

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.

Le code suivant montre comment charger un fichier CSV local dans une nouvelle table BigQuery. Pour charger un fichier local d'un autre format, définissez FormatOptions sur le format approprié.

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

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.

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.

Le code suivant montre comment charger un fichier CSV local dans une nouvelle table BigQuery. Pour charger un fichier local d'un autre format, définissez le paramètre metadata de la fonction load sur le format approprié.

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

async function loadLocalFile() {
  // Imports a local file into a table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const filename = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

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.

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.

Le code suivant montre comment charger un fichier CSV local dans une nouvelle table BigQuery. Pour charger un fichier local d'un autre format, définissez sourceFormat sur le format approprié.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';
// $tableId    = 'The BigQuery table ID';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . 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.

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.

Le code suivant montre comment charger un fichier CSV local dans une nouvelle table BigQuery. Pour charger un fichier local d'un autre format, définissez la propriété LoadJobConfig.source_format sur le format approprié.

from google.cloud import bigquery

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

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.CSV, skip_leading_rows=1, autodetect=True,
)

with open(file_path, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_id, job_config=job_config)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

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.

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.

Le code suivant montre comment charger un fichier CSV local dans une nouvelle table BigQuery. Pour charger un fichier local d'un autre format, définissez le paramètre format de la méthode Table#load_job sur le format approprié.

require "google/cloud/bigquery"

def load_from_file dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows into #{table.id}"
end

Limites

Le chargement de données à partir d'une source de données locale est soumis aux limites suivantes :

  • Les caractères génériques et les listes d'éléments séparés par une virgule ne sont pas compatibles avec le chargement de fichiers depuis une source de données locale. Les fichiers doivent être chargés individuellement.
  • Lorsque vous utilisez la console Google Cloud, les fichiers chargés à partir d'une source de données locale ne peuvent pas dépasser 100 Mo. Dans le cas de fichiers plus volumineux, chargez-les à partir de Cloud Storage.
  • Les tâches de chargement utilisent un pool d'emplacements partagé par défaut. BigQuery ne garantit pas la capacité disponible de ce pool partagé, ni le débit obtenu. Vous pouvez également acheter des emplacements dédiés pour exécuter des tâches de chargement. Pour en savoir plus, consultez les Tarifs d'ingestion de données.

Charger des données compressées et non compressées

Pour les formats Avro, Parquet et ORC, BigQuery accepte le chargement de fichiers dans lesquels les données de ces fichiers ont été compressées à l'aide d'un codec compatible. Cependant, BigQuery ne permet pas de charger des fichiers dans des formats qui ont eux-mêmes été compressés, par exemple à l'aide de l'utilitaire gzip.

Le format binaire Avro est le format préconisé pour le chargement des données compressées. Les données Avro sont plus rapides à charger, car elles peuvent être lues en parallèle, même lorsque les blocs de données sont compressés. Pour obtenir la liste des codecs de compression acceptés, consultez la page Compression de fichiers Avro.

Le format binaire Parquet est également un choix judicieux, car l'encodage par colonne de Parquet se traduit généralement par un meilleur taux de compression et des fichiers moins volumineux. Les fichiers Parquet exploitent également les techniques de compression qui permettent de charger les fichiers en parallèle. Pour obtenir la liste des codecs de compression compatibles, consultez la section Compression de fichiers Parquet.

Le format binaire ORC offre des avantages semblables à ceux du format Parquet. Les données dans les fichiers ORC sont rapides à charger, car les bandes de données peuvent être lues en parallèle. Les lignes de chaque bande de données sont chargées de manière séquentielle. Pour optimiser le temps de chargement, utilisez une taille de bande de données d'environ 256 Mo au maximum. Pour obtenir la liste des codecs de compression compatibles, consultez la section Compression ORC.

Pour les autres formats de données tels que CSV et JSON, BigQuery peut charger les fichiers non compressés beaucoup plus rapidement que les fichiers compressés, car les fichiers non compressés peuvent être lus en parallèle. Les fichiers non compressés étant plus volumineux, leur utilisation peut entraîner des restrictions de bande passante et une augmentation des coûts de stockage pour les données stockées dans Cloud Storage avant leur chargement dans BigQuery. Gardez à l'esprit que l'ordre des lignes n'est pas garanti pour les fichiers compressés ou non compressés. Il est important de prendre en compte ces compromis en fonction de votre cas d'utilisation.

En général, si la bande passante est limitée, compressez vos fichiers CSV et JSON à l'aide de gzip avant de les télécharger sur Cloud Storage. gzip est le seul type de compression de fichiers compatible pour les fichiers CSV et JSON lors du chargement de données dans BigQuery. Si la vitesse de chargement est importante pour votre application et que vous avez beaucoup de bande passante pour charger vos données, conservez vos fichiers non compressés.

Ajouter des données à une table ou écraser une table

Vous pouvez charger des données supplémentaires dans une table à partir de fichiers sources ou en ajoutant des résultats de requête. Si le schéma des données ne correspond pas au schéma de la table ou de la partition de destination, vous pouvez mettre à jour le schéma lorsque vous y ajoutez des données ou lorsque vous l'écrasez.

Si vous mettez à jour le schéma lors de l'ajout de données, BigQuery vous permet d'effectuer les opérations suivantes :

  • Ajouter des champs
  • Changer des champs REQUIRED en NULLABLE

Si vous écrasez une table, le schéma est toujours remplacé. Les mises à jour de schéma ne sont pas limitées lorsque vous écrasez une table.

Dans la console Google Cloud, utilisez l'option Préférence d'écriture pour spécifier l'action à entreprendre lorsque vous chargez des données à partir d'un fichier source ou d'un résultat de requête. L'outil de ligne de commande bq et l'API incluent les options suivantes :

Option de la console Option de l'outil bq Propriété de l'API BigQuery Description
Écrire si la table est vide Aucun WRITE_EMPTY N'écrit les données que si la table est vide.
Ajouter à la table --noreplace ou --replace=false. Si --replace n'est pas spécifié, les données sont ajoutées par défaut. WRITE_APPEND (Par défaut) Ajoute les données à la fin de la table.
Écraser la table --replace ou --replace=true WRITE_TRUNCATE Efface toutes les données existantes d'une table avant d'écrire les nouvelles données.

Règles de quotas

Pour en savoir plus sur les règles de quota pour le chargement des données par lot, consultez la section Tâches de chargement de la page "Quotas et limites".

Afficher l'utilisation actuelle des quotas

Vous pouvez afficher l'utilisation actuelle des jobs de requête, de chargement, d'extraction ou de copie en exécutant une requête INFORMATION_SCHEMA pour afficher les métadonnées des tâches exécutées sur une période spécifiée. Vous pouvez comparer votre utilisation actuelle à la limite de quota pour déterminer votre utilisation de quotas pour un type de job particulier. L'exemple de requête suivant utilise la vue INFORMATION_SCHEMA.JOBS pour répertorier le nombre de jobs de requête, de chargement, d'extraction et de copie par projet :

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Tarifs

Le chargement des données par lot dans BigQuery est gratuit. Pour en savoir plus, consultez les tarifs d'ingestion de données BigQuery.

Exemple d'utilisation

Supposons qu'un pipeline de traitement par lot quotidien doit être effectué dans un délai fixe. Les données doivent être disponibles dans le délai indiqué afin de bénéficier d'un traitement ultérieur par un autre processus par lot qui génère des rapports pour une autorité réglementaire. Ce cas d'utilisation est courant dans les secteurs réglementés tels que la finance.

Le chargement par lot de données avec des tâches de chargement est l'approche appropriée pour ce cas d'utilisation, car la latence n'est pas une préoccupation tant que le délai est respecté. Assurez-vous que vos buckets Cloud Storage répondent aux exigences d'emplacement pour le chargement de données dans l'ensemble de données BigQuery.

Le résultat d'une tâche de chargement BigQuery est atomique : tous les enregistrements sont insérés ou aucun. Lorsque vous insérez toutes les données dans une seule tâche de chargement, il est recommandé de créer une table à l'aide de la disposition WRITE_TRUNCATE de la ressource JobConfigurationLoad. Cela est important pour les nouvelles tentatives d'exécution d'une tâche de chargement ayant échoué, car le client peut ne pas être en mesure de faire la distinction entre les tâches ayant échoué et l'échec causé par exemple par la communication de la réussite de l'opération au client.

En supposant que les données à ingérer ont déjà été copiées dans Cloud Storage, une nouvelle tentative avec un intervalle exponentiel entre les tentatives est suffisante pour résoudre les problèmes d'ingestion.

Il est recommandé de ne pas atteindre le quota par défaut de 1 500 chargements par table et par jour d'une tâche par lot quotidienne, même en cas de nouvelles tentatives. Lorsque vous chargez des données de manière incrémentielle, le quota par défaut est suffisant pour exécuter une tâche de chargement toutes les cinq minutes tout en conservant du quota disponible suffisant pour au moins une nouvelle tentative par tâche.