Charger des données CSV depuis Google Cloud Storage

Charger des fichiers CSV à partir de Cloud Storage

Lorsque vous chargez des données CSV depuis Cloud Storage, vous pouvez les placer dans une nouvelle table ou partition, les ajouter à une table ou une partition existante, ou bien les utiliser pour écraser une table ou une partition. Lorsque les données sont chargées dans BigQuery, elles sont converties au format en colonnes de Capacitor (format de stockage de BigQuery).

Lorsque vous chargez des données depuis Cloud Storage dans une table BigQuery, l'ensemble de données contenant la table doit se trouver dans le même emplacement régional ou multirégional que le bucket Cloud Storage.

Pour plus d'informations sur le chargement de données CSV à partir d'un fichier local, consultez la section Charger des données dans BigQuery à partir d'une source de données locale.

Limites

Lorsque vous chargez des données CSV depuis Cloud Storage dans BigQuery, tenez compte des points suivants :

  • Les fichiers CSV ne prennent pas en charge les données imbriquées ou répétées.
  • Si vous utilisez la compression gzip, BigQuery ne peut pas lire les données en parallèle. Le chargement de données CSV compressées dans BigQuery est plus lent que le chargement de données non compressées.
  • Lorsque vous chargez des données CSV ou JSON, les valeurs des colonnes DATE doivent utiliser le tiret (-) comme séparateur et la date doit avoir le format suivant : YYYY-MM-DD (année-mois-jour).
  • Lorsque vous chargez des données JSON ou CSV, les valeurs des colonnes TIMESTAMP doivent utiliser le tiret (-) comme séparateur pour la partie date de l'horodatage et la date doit être au format suivant : YYYY-MM-DD (année-mois-jour). La partie hh:mm:ss (heure-minute-seconde) de l'horodatage doit utiliser deux points (:) comme séparateur.

Encodage CSV

BigQuery s'attend à ce que les données CSV soient codées en UTF-8. Si vous avez des fichiers CSV avec des données encodées au format ISO-8859-1 (également connu sous le nom de Latin-1), vous devez spécifier explicitement l'encodage lorsque vous chargez vos données pour qu'elles puissent être converties en UTF-8.

Dans les fichiers CSV, les délimiteurs peuvent être des caractères mono-octets ISO-8859-1. Pour utiliser un caractère compris entre 128 et 255, vous devez encoder le caractère en UTF-8. BigQuery convertit la chaîne selon l'encodage ISO-8859-1 et utilise le premier octet de la chaîne codée pour fractionner les données dans leur état binaire brut.

Autorisations requises

Lorsque vous chargez des données dans BigQuery, vous avez besoin d'autorisations au niveau du projet ou de l'ensemble de données afin de pouvoir charger des données dans des tables et partitions BigQuery nouvelles ou existantes. Si vous chargez des données depuis Cloud Storage, vous devez également avoir accès au bucket contenant vos données.

Autorisations BigQuery

Lorsque vous chargez des données dans BigQuery depuis Cloud Storage, vous devez disposer du rôle bigquery.dataOwner ou bigquery.dataEditor au niveau du projet ou de l'ensemble de données. Les deux rôles permettent aux utilisateurs et aux groupes de charger les données dans une nouvelle table, de les ajouter à une table existante ou de les utiliser pour écraser une table.

L'attribution des rôles au niveau du projet donne à l'utilisateur ou au groupe la possibilité de charger les données dans les tables de chaque ensemble de données du projet. L'attribution des rôles au niveau de l'ensemble de données permet à l'utilisateur ou au groupe de charger les données uniquement dans les tables de cet ensemble de données.

Pour en savoir plus sur la configuration de l'accès aux ensembles de données, consultez la section Appliquer des contrôles d'accès aux ensembles de données. Pour plus d'informations sur les rôles IAM dans BigQuery, consultez la section Contrôle d'accès.

Autorisations Cloud Storage

Pour charger les données d'un bucket Cloud Storage, vous devez disposer des autorisations storage.objects.get au niveau du projet ou du bucket concerné. Si vous utilisez un caractère générique dans l'URI, vous devez également disposer des autorisations storage.objects.list.

Le rôle IAM prédéfini storage.objectViewer peut être accordé pour attribuer les autorisations storage.objects.get et storage.objects.list.

Charger des données CSV dans une nouvelle table

Pour charger des données CSV depuis Google Cloud Storage dans une nouvelle table BigQuery, procédez comme suit :

Interface utilisateur Web

  1. Accédez à l'interface utilisateur Web de BigQuery.
    Accéder à l'interface utilisateur Web de BigQuery

  2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Ensuite, cliquez sur l'icône représentant une flèche vers le bas image de la flèche vers le bas, puis sur Create new table (Créer une table). Le processus de chargement des données est identique à celui permettant de créer une table vide.

  3. Dans la section Source Data (Données sources) de la page Create Table (Créer une table), procédez comme suit :

    • Pour le paramètre Location (Emplacement), sélectionnez Google Cloud Storage. Dans le champ "Source", indiquez le paramètre URI Cloud Storage. Notez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur Web de BigQuery. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table que vous créez.
    • Pour le File format (Format de fichier), sélectionnez Comma-separated values (CSV) (Valeurs séparées par des virgules (CSV)).
  4. Dans la section Destination Table (Table de destination) de la page Create Table (Créer une table), procédez comme suit :
    • Pour le paramètre Table Name (Nom de la table), choisissez l'ensemble de données approprié, puis saisissez dans le champ le nom de la table que vous créez dans BigQuery.
    • Vérifiez que le paramètre Table type (Type de table) est défini sur Native table (Table native{).

  5. Dans la section Schema (Schéma), entrez la définition du schéma.

    • Pour les fichiers CSV, vous pouvez cocher l'option Auto-detect (Détection automatique) pour activer la détection automatique de schémas.

      lien vers la détection automatique

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

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

        Ajouter un schéma en tant que tableau JSON

      • En utilisant Add Field (Ajouter un champ) pour saisir manuellement le schéma :

        Ajouter un schéma en utilisant l'ajout de champs

  6. Sélectionnez les éléments applicables dans la section Options, puis cliquez sur Create Table (Créer une table). Pour plus d'informations sur les options disponibles, consultez la section Options CSV.

Ligne de commande

Utilisez la commande bq load, indiquez CSV pour source_format et spécifiez un paramètre URI Cloud Storage. Vous pouvez inclure un seul URI, une liste d'URI séparés par des virgules ou un URI contenant un caractère générique.

Spécifiez l'indicateur --location et définissez la valeur sur votre emplacement.

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

où :

  • [LOCATION] correspond à votre emplacement. L'indicateur --location est facultatif si vos données se trouvent dans l'emplacement multirégional US ou EU. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • [FORMAT] est CSV.
  • [DATASET] est un ensemble de données existant.
  • [TABLE] est le nom de la table dans laquelle vous chargez les données.
  • [PATH_TO_SOURCE] correspond à un URI Cloud Storage complet ou à une liste d'URI séparés par des virgules. Les caractères génériques sont également autorisés.
  • [SCHEMA] est un schéma valide. Ce schéma peut être un fichier JSON local ou il peut être saisi en ligne dans la commande. Vous pouvez également utiliser l'indicateur --autodetect au lieu de fournir une définition de schéma.

En outre, vous pouvez ajouter des indicateurs pour les options CSV, qui vous permettent de contrôler la manière dont BigQuery analyse vos données. Par exemple, vous pouvez utiliser l'indicateur --skip_leading_rows pour ignorer les lignes d'en-tête du fichier CSV et utiliser l'indicateur --encoding pour identifier l'encodage des caractères des données.

Exemples :

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv dans la table mytable de mydataset. Le schéma est défini dans un fichier de schéma local nommé myschema.json. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv dans la table mytable de mydataset. Le schéma est défini en ligne au format [FIELD]:[DATA_TYPE], [FIELD]:[DATA_TYPE]. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv qtr:STRING,sales:FLOAT,year:STRING

    Lorsque vous spécifiez le schéma sur la ligne de commande, vous ne pouvez pas inclure de type RECORD (STRUCT), ni de description de champ, ni spécifier le mode de champ. Tous les modes sont définis comme NULLABLE par défaut. Pour inclure des descriptions de champs, des modes et des types RECORD, fournissez un fichier de schéma JSON.

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv dans la table mytable de mydataset. Le schéma est défini à l'aide de la fonctionnalité de détection automatique de schéma. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --autodetect --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv

  • La commande suivante permet de charger les données de plusieurs fichiers de gs://mybucket/ dans la table mytable de mydataset. L'URI Cloud Storage utilise un caractère générique et le schéma est défini à l'aide de la fonctionnalité de détection automatique de schéma. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --autodetect --source_format=CSV mydataset.mytable gs://mybucket/mydata*.csv

  • La commande suivante permet de charger les données de plusieurs fichiers de gs://mybucket/ dans la table mytable de mydataset. La commande inclut une liste d'URI Cloud Storage séparés par des virgules et le schéma est défini à l'aide de la fonctionnalité de détection automatique de schéma. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --autodetect --source_format=CSV mydataset.mytable "gs://mybucket/myfile.csv,gs://mybucket/myfile2.csv"

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv dans la table mytable de mydataset. Le schéma est défini dans un fichier de schéma local nommé myschema.json et l'indicateur --skip_leading_rows est utilisé pour ignorer les deux premières lignes d'en-tête du fichier CSV. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --skip_leading_rows=2 --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json

API

Définissez les propriétés ci-dessous pour charger des données CSV à l'aide de l'API.

  1. Créez une tâche de chargement qui pointe vers les données sources dans Google Cloud Storage.

  2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource associée à la tâche.

  3. Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Chaque URI peut contenir un caractère générique (*).

  4. Spécifiez le format de données CSV en définissant la propriété configuration.load.sourceFormat sur CSV.

  5. Pour vérifier l'état de la tâche, appelez jobs.get([JOB_ID]*), où [JOB_ID] correspond à l'ID de la tâche renvoyée par la requête initiale.

    • Si status.state = DONE, la tâche a bien été exécutée.
    • Si la propriété status.errorResult est présente, la requête a échoué. Cet objet inclura des informations décrivant le problème rencontré. Lorsqu'une requête échoue, aucune table n'est créée et aucune donnée n'est ajoutée.
    • Si la propriété status.errorResult est absente, la tâche a bien été exécutée. Toutefois, des erreurs non fatales, telles que des problèmes d'importation de lignes, ont pu se produire. Les erreurs non fatales sont répertoriées dans la propriété status.errors de l'objet Tâche renvoyé.

Remarques relatives à l'API :

  • Les tâches de chargement sont atomiques et cohérentes. Si une tâche de chargement échoue, aucune donnée n'est disponible. Si une tâche aboutit, toutes les données sont disponibles.

  • Il est recommandé de générer un ID unique et de le transmettre en tant que jobReference.jobId lorsque vous appelez jobs.insert() pour créer une tâche de chargement. Cette approche offre une protection plus robuste contre les pannes réseau, car le client peut lancer une requête ou effectuer de nouvelles tentatives en utilisant l'ID de tâche connu.

  • L'appel de jobs.insert() sur un ID de tâche donné est idempotent. En d'autres termes, vous pouvez effectuer autant de tentatives que vous le souhaitez avec le même ID de tâche. L'une de ces opérations tout au plus aboutira.

C#

Avant d'essayer cet exemple, suivez les instructions de configuration de C# décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery C#. 

public void ImportDataFromCloudStorage(string projectId, string datasetId,
    string tableId, BigQueryClient client, string fileName, string folder = null)
{
    StorageClient gcsClient = StorageClient.Create();

    using (var stream = new MemoryStream())
    {
        // Set Cloud Storage Bucket name. This uses a bucket named the same as the project.
        string bucket = projectId;
        // If folder is passed in, add it to Cloud Storage File Path using "/" character
        string filePath = string.IsNullOrEmpty(folder) ? fileName : folder + "/" + fileName;
        // Download Google Cloud Storage object into stream
        gcsClient.DownloadObject(projectId, filePath, stream);

        // This example uploads data to an existing table. If the upload will create a new table
        // or if the schema in the JSON isn't identical to the schema in the table,
        // create a schema to pass into the call instead of passing in a null value.
        BigQueryJob job = client.UploadJson(datasetId, tableId, null, stream);
        // Use the job to find out when the data has finished being inserted into the table,
        // report errors etc.

        // Wait for the job to complete.
        job.PollUntilCompleted();
    }
}

Go

Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de 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")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
gcsRef.SkipLeadingRows = 1
gcsRef.Schema = bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.StringFieldType},
}
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
loader.WriteDisposition = bigquery.WriteEmpty

job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}

if status.Err() != nil {
	return fmt.Errorf("Job completed with error: %v", status.Err())
}

Java

Avant d'essayer cet exemple, suivez les instructions de configuration de Java décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java. 

Job job = table.load(FormatOptions.csv(), sourceUri);
// Wait for the job to complete
try {
  Job completedJob =
      job.waitFor(
          RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
          RetryOption.totalTimeout(Duration.ofMinutes(3)));
  if (completedJob != null && completedJob.getStatus().getError() == null) {
    // Job completed successfully
  } else {
    // Handle error case
  }
} catch (InterruptedException e) {
  // Handle interrupted wait
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration de Node.js décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Node.js.

Utilisez la méthode Table.load() pour charger des données à partir d'un fichier CSV dans Cloud Storage. Fournissez une définition de schéma explicite via le paramètre de métadonnées :

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

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

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

// Instantiates clients
const bigquery = new BigQuery({
  projectId: projectId,
});

const storage = new Storage({
  projectId: projectId,
});

// Configure the load job. For full list of options, see:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
const metadata = {
  sourceFormat: 'CSV',
  skipLeadingRows: 1,
  schema: {
    fields: [
      {name: 'name', type: 'STRING'},
      {name: 'post_abbr', type: 'STRING'},
    ],
  },
};

// Loads data from a Google Cloud Storage file into the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .load(storage.bucket(bucketName).file(filename), metadata)
  .then(results => {
    const job = results[0];

    // load() waits for the job to finish
    assert.equal(job.status.state, 'DONE');
    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;
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Définissez la valeur de autodetect sur true pour que BigQuery déduise le schéma à partir d'un échantillon des données d'entrée :

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

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

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

// Instantiates clients
const bigquery = new BigQuery({
  projectId: projectId,
});

const storage = new Storage({
  projectId: projectId,
});

// Configure the load job. For full list of options, see:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
const metadata = {
  sourceFormat: 'CSV',
  skipLeadingRows: 1,
  autodetect: true,
};

// Loads data from a Google Cloud Storage file into the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .load(storage.bucket(bucketName).file(filename), metadata)
  .then(results => {
    const job = results[0];

    // load() waits for the job to finish
    assert.equal(job.status.state, 'DONE');
    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;
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

Avant d'essayer cet exemple, suivez les instructions de configuration de PHP décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery PHP. 

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Storage\StorageClient;
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';
// $bucketName = 'The Cloud Storage bucket Name';
// $objectName = 'The Cloud Storage object Name';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// load the storage object
$storage = new StorageClient([
    'projectId' => $projectId,
]);
$object = $storage->bucket($bucketName)->object($objectName);
// create the import job
$loadConfig = $table->loadFromStorage($object);
// determine the source format from the object name
if ('.backup_info' === substr($objectName, -12)) {
    $loadConfig->sourceFormat('DATASTORE_BACKUP');
} elseif ('.json' === substr($objectName, -5)) {
    $loadConfig->sourceFormat('NEWLINE_DELIMITED_JSON');
}
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('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 de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.

Utilisez la méthode Client.load_table_from_uri() pour charger des données à partir d'un fichier CSV dans Cloud Storage. Fournissez une définition de schéma explicite en définissant la propriété LoadJobConfig.schema sur une liste d'objets SchemaField.

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

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField('name', 'STRING'),
    bigquery.SchemaField('post_abbr', 'STRING')
]
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv'

load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(dataset_ref.table('us_states')).num_rows == 50

Définissez la propriété LoadJobConfig.autodetect sur True pour que BigQuery déduise le schéma à partir d'un échantillon des données d'entrée :

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

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.autodetect = True
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv'
load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(dataset_ref.table('us_states')).num_rows == 50

Ruby

Avant d'essayer cet exemple, suivez les instructions de configuration de Ruby décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Ruby. 

# project_id   = "Your Google Cloud project ID"
# dataset_id   = "ID of the dataset containing table"
# table_id     = "ID of the table to import data into"
# storage_path = "Storage path to file to import, eg. gs://bucket/file.csv"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id
table    = dataset.table table_id

puts "Importing data from Cloud Storage file: #{storage_path}"
load_job = table.load_job storage_path

puts "Waiting for load job to complete: #{load_job.job_id}"
load_job.wait_until_done!

puts "Data imported"

Ajouter ou écraser des données dans une table avec des données CSV

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

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 l'interface utilisateur Web de BigQuery, vous devez utiliser 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. La CLI et l'API incluent les options ci-dessous.

Option de l'interface utilisateur Web Indicateur de la CLI Propriété de l'API BigQuery Description
Écrire si le tableau est vide Aucun WRITE_EMPTY N'écrit les données que si la table est vide.
Ajouter au tableau --noreplace ou --replace=false ; si l'indicateur --[no]replace n'est pas spécifié, les données sont ajoutées par défaut. WRITE_APPEND (Valeur par défaut) Ajoute les données à la fin de la table.
Écraser le tableau --replace ou --replace=true WRITE_TRUNCATE Efface toutes les données existantes d'une table avant d'écrire les nouvelles données.

Pour charger des données CSV depuis Google Cloud Storage, puis les ajouter à une table BigQuery ou les utiliser pour écraser une table BigQuery, procédez comme suit :

Interface utilisateur Web

  1. Accédez à l'interface utilisateur Web de BigQuery.
    Accéder à l'interface utilisateur Web de BigQuery

  2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Ensuite, cliquez sur l'icône représentant une flèche vers le bas image de la flèche vers le bas, puis sur Create new table (Créer une table). Le processus de chargement des données est identique à celui permettant de créer une table vide.

  3. Dans la section Source Data (Données sources) de la page Create Table (Créer une table), procédez comme suit :

    • Pour le paramètre Location (Emplacement), sélectionnez Google Cloud Storage. Dans le champ "Source", indiquez le paramètre URI Cloud Storage. Notez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table à laquelle vous ajoutez des données ou que vous écrasez.
    • Pour le File format (Format de fichier), sélectionnez Comma-separated values (CSV) (Valeurs séparées par des virgules (CSV)).
  4. Dans la section Destination Table (Table de destination) de la page Create Table (Créer une table), procédez comme suit :
    • Pour le paramètre Table name (Nom de la table), choisissez l'ensemble de données approprié, puis saisissez dans le champ le nom de la table à laquelle vous ajoutez des données ou que vous écrasez.
    • Vérifiez que le paramètre Table type (Type de table) est défini sur Native table (Table native{).

  5. Dans la section Schema (Schéma), entrez la définition du schéma.

    • Pour les fichiers CSV, vous pouvez cocher l'option Auto-detect (Détection automatique) pour activer la détection automatique de schémas.

      lien vers la détection automatique

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

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

        Ajouter un schéma en tant que tableau JSON

      • En utilisant Add Field (Ajouter un champ) pour saisir manuellement le schéma :

        Ajouter un schéma en utilisant l'ajout de champs

  6. Dans la section Options, pour l'option Write preference (Préférence d'écriture), choisissez Write if empty (Écrire si le tableau est vide), Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).

    Ajouter un schéma en utilisant l'ajout de champs

  7. Cliquez sur Create a Table (Créer une table).

Ligne de commande

Saisissez la commande bq load avec l'indicateur --replace pour écraser la table. Spécifiez l'indicateur --location et définissez la valeur sur votre emplacement. Utilisez l'indicateur --noreplace pour ajouter des données à la table. Si aucun indicateur n'est spécifié, les données sont ajoutées par défaut.

Lorsque vous ajoutez ou écrasez une table, vous pouvez utiliser l'indicateur --schema_update_option pour mettre à jour le schéma de la table de destination avec le schéma des nouvelles données. Les options suivantes peuvent être utilisées avec l'indicateur --schema_update_option :

  • ALLOW_FIELD_ADDITION : ajoute de nouveaux champs au schéma ; ces nouveaux champs ne peuvent pas être REQUIRED.
  • ALLOW_FIELD_RELAXATION : change les champs obligatoires en champs pouvant être vides ; répétez cette option pour spécifier une liste de valeurs.
bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

où :

  • [LOCATION] correspond à votre emplacement. L'indicateur --location est facultatif si vos données se trouvent dans l'emplacement multirégional US ou EU.Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • [DATASET] est un ensemble de données existant.
  • [TABLE] est le nom de la table dans laquelle vous chargez les données.
  • [PATH_TO_SOURCE] correspond à un URI Cloud Storage complet ou à une liste d'URI séparés par des virgules. Les caractères génériques sont également autorisés.
  • [SCHEMA] est un schéma valide. Ce schéma peut être un fichier JSON local ou il peut être saisi en ligne dans la commande. Vous pouvez également utiliser l'indicateur --autodetect au lieu de fournir une définition de schéma.

En outre, vous pouvez ajouter des indicateurs pour les options CSV, qui vous permettent de contrôler la manière dont BigQuery analyse vos données CSV. Par exemple, vous pouvez utiliser l'indicateur --skip_leading_rows pour ignorer les lignes d'en-tête du fichier CSV et utiliser l'indicateur --encoding pour identifier l'encodage des caractères des données.

Exemples :

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv en écrasant une table nommée mytable dans mydataset. Le schéma est défini à l'aide de la détection automatique de schéma. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --autodetect --replace --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv en ajoutant des données à une table nommée mytable dans mydataset. Le schéma est défini à l'aide d'un fichier de schéma JSON nommé myschema.json. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --autodetect --noreplace --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv en ajoutant des données à une table nommée mytable dans mydataset. Un fichier de schéma JSON local nommé myschema.json est utilisé. La définition de schéma contient de nouveaux champs non présents dans la table de destination. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_ADDITION --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json

  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv en ajoutant des données à une table nommée mytable dans mydataset. Un fichier de schéma JSON local nommé myschema.json est utilisé. La définition de schéma permet de changer (assouplir) deux champs REQUIRED en NULLABLE. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json

API

Définissez les propriétés ci-dessous pour charger des données CSV à l'aide de l'API.

  1. Créez une tâche de chargement qui pointe vers les données sources dans Google Cloud Storage.

  2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource associée à la tâche.

  3. Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Vous pouvez inclure plusieurs URI sous la forme d'une liste d'éléments séparés par une virgule. Notez que les caractères génériques sont également acceptés lorsque vous chargez des données CSV depuis Google Cloud Storage.

  4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur CSV.

  5. Spécifiez la préférence d'écriture en définissant la propriété configuration.load.writeDisposition sur WRITE_TRUNCATE, WRITE_APPEND ou WRITE_EMPTY.

  6. Pour mettre à jour le schéma dans votre tâche de chargement, définissez la propriété configuration.load.schemaUpdateOptions sur ALLOW_FIELD_ADDITION ou ALLOW_FIELD_RELAXATION.

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration de Node.js décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Node.js.

Pour ajouter des lignes à une table existante, définissez la valeur writeDisposition du paramètre metadata sur 'WRITE_APPEND'.

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

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

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

// Instantiates clients
const bigquery = new BigQuery({
  projectId: projectId,
});

const storage = new Storage({
  projectId: projectId,
});

// Configure the load job. For full list of options, see:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
const metadata = {
  sourceFormat: 'CSV',
  skipLeadingRows: 1,
  schema: {
    fields: [
      {name: 'name', type: 'STRING'},
      {name: 'post_abbr', type: 'STRING'},
    ],
  },
  // Set the write disposition to append to an existing table.
  writeDisposition: 'WRITE_APPEND',
};

// Loads data from a Google Cloud Storage file into the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .load(storage.bucket(bucketName).file(filename), metadata)
  .then(results => {
    const job = results[0];

    // load() waits for the job to finish
    assert.equal(job.status.state, 'DONE');
    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;
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Pour remplacer les lignes d'une table existante, définissez la valeur writeDisposition du paramètre metadata sur 'WRITE_TRUNCATE'.

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

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

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

// Instantiates clients
const bigquery = new BigQuery({
  projectId: projectId,
});

const storage = new Storage({
  projectId: projectId,
});

// Configure the load job. For full list of options, see:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
const metadata = {
  sourceFormat: 'CSV',
  skipLeadingRows: 1,
  schema: {
    fields: [
      {name: 'name', type: 'STRING'},
      {name: 'post_abbr', type: 'STRING'},
    ],
  },
  // Set the write disposition to append to an existing table.
  writeDisposition: 'WRITE_TRUNCATE',
};

// Loads data from a Google Cloud Storage file into the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .load(storage.bucket(bucketName).file(filename), metadata)
  .then(results => {
    const job = results[0];

    // load() waits for the job to finish
    assert.equal(job.status.state, 'DONE');
    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;
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Python

Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.

Pour ajouter des lignes à une table existante, définissez la propriété LoadJobConfig.write_disposition sur la constante SourceFormat WRITE_APPEND.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

previous_rows = client.get_table(table_ref).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv'
load_job = client.load_table_from_uri(
    uri,
    table_ref,
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(table_ref).num_rows == previous_rows + 50

Pour remplacer les lignes d'une table existante, définissez la propriété LoadJobConfig.write_disposition sur la constante SourceFormat WRITE_TRUNCATE.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

previous_rows = client.get_table(table_ref).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv'
load_job = client.load_table_from_uri(
    uri,
    table_ref,
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(table_ref).num_rows == 50

Options CSV

Pour modifier la façon dont BigQuery analyse les données CSV, spécifiez des options supplémentaires dans l'interface utilisateur, la CLI ou l'API. Pour plus d'informations sur le format CSV, consultez RFC 4180.

Option CSV Option de l'interface utilisateur Web Indicateur de la CLI Propriété de l'API BigQuery Description
Délimiteur de champ Délimiteur de champ : virgule, tabulation, barre verticale, autre -F ou --field_delimiter fieldDelimiter (Facultatif) Le séparateur des champs dans un fichier CSV. Le séparateur peut être n'importe quel caractère ISO-8859-1 à un octet. Pour utiliser un caractère compris entre 128 et 255, vous devez encoder le caractère en UTF8. BigQuery convertit la chaîne selon l'encodage ISO-8859-1 et utilise le premier octet de la chaîne codée pour fractionner les données dans leur état binaire brut. BigQuery prend également en charge la séquence d'échappement "\ t" pour spécifier la tabulation comme séparateur. La valeur par défaut est une virgule (,).
Lignes d'en-tête Lignes d'en-tête à ignorer --skip_leading_rows skipLeadingRows (Facultatif) Un entier indiquant le nombre de lignes d'en-tête dans les données source.
Nombre d'enregistrements incorrects autorisés Nombre d'erreurs autorisées --max_bad_records maxBadRecords (Facultatif) Nombre maximal d'enregistrements incorrects pouvant être ignorés par BigQuery lors de l'exécution de la tâche. Si le nombre d'enregistrements incorrects dépasse cette valeur, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est 0, ce qui nécessite que tous les enregistrements soient valides.
Caractères de retour à la ligne Autoriser les nouvelles lignes entre guillemets --allow_quoted_newlines allowQuotedNewlines (Facultatif) Indique s'il faut autoriser les sections de données entre guillemets contenant des caractères de retour à la ligne dans un fichier CSV. La valeur par défaut est false.
Valeurs NULL personnalisées Aucune --null_marker nullMarker (Facultatif) Spécifie une chaîne représentant une valeur nulle dans un fichier CSV. Par exemple, si vous spécifiez "\N", BigQuery interprète "\N" comme une valeur nulle lors du chargement d'un fichier CSV. La valeur par défaut est la chaîne vide. Si vous définissez cette propriété sur une valeur personnalisée, BigQuery génère une erreur si une chaîne vide est présente pour tous les types de données, à l'exception de STRING et BYTE. Pour les colonnes STRING et BYTE, BigQuery interprète la chaîne vide comme une valeur vide.
Colonnes facultatives finales Autoriser les lignes irrégulières --allow_jagged_rows allowJaggedRows (Facultatif) Acceptez les lignes pour lesquelles il manque des colonnes facultatives finales. Les valeurs manquantes sont traitées comme des valeurs nulles. Si la valeur est false, les enregistrements contenant des colonnes finales manquantes sont traités comme des enregistrements incorrects et, s'il y a trop d'enregistrements incorrects, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est false. Applicable uniquement au format CSV, ignoré pour les autres formats.
Valeurs inconnues Ignorer les valeurs inconnues --ignore_unknown_values ignoreUnknownValues (Facultatif) Indique si BigQuery doit autoriser des valeurs supplémentaires qui ne sont pas représentées dans le schéma de la table. Si le champ est défini sur true, les valeurs supplémentaires sont ignorées. Si la valeur est false, les enregistrements comportant des colonnes supplémentaires sont traités comme des enregistrements incorrects et, si le nombre d'enregistrements incorrects est trop élevé, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est false. La propriété sourceFormat détermine ce que BigQuery traite comme une valeur supplémentaire : CSV : colonnes finales ; JSON : valeurs nommées ne correspondant à aucun nom de colonne
Guillemets Aucun --quote quote (Facultatif) Valeur utilisée pour citer des sections de données dans un fichier CSV. BigQuery convertit la chaîne selon l'encodage ISO-8859-1 et utilise le premier octet de la chaîne codée pour fractionner les données dans leur état binaire brut. La valeur par défaut est un guillemet double (""). Si vos données ne contiennent pas de sections entre guillemets, définissez la valeur de la propriété sur une chaîne vide. Si vos données contiennent des caractères de retour à la ligne entre guillemets, vous devez également définir la propriété allowQuotedNewlines sur true.
Encodage Aucun -E ou --encoding encoding (Facultatif) Codage des caractères des données. Les valeurs prises en charge sont UTF-8 ou ISO-8859-1. La valeur par défaut est UTF-8. BigQuery décode les données après que les données brutes ont été fractionnées à l'aide des valeurs des propriétés quote et fieldDelimiter.
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Cette page
Commentaires sur la documentation
BigQuery
Commentaires sur le produit
Besoin d'aide ? Consultez notre page d'assistance.