Importer des données dans BigQuery

Plutôt que de recourir à une tâche pour charger des données dans BigQuery, vous pouvez insérer celles-ci en flux continu (un enregistrement à la fois) à l'aide de la méthode tabledata.insertAll. Cette approche permet d'interroger les données sans attendre l'exécution d'une tâche de chargement.

Ce document présente les contraintes à prendre en considération avant de choisir une approche, y compris en ce qui concerne les quotas d'insertion en flux continu, la disponibilité des données et leur cohérence.

Avant de commencer

  1. Assurez-vous de disposer d'un accès en écriture à l'ensemble de données contenant votre table de destination. Pour écrire des données dans une table, vérifiez que celle-ci existe au préalable, sauf si vous utilisez des modèles de tables. Pour en savoir plus, consultez la section Créer des tables automatiquement à l'aide de modèles.

  2. Consultez les Règles relatives aux quotas d'insertion en flux continu.

  3. Assurez-vous que la facturation est activée pour votre projet Google Cloud Platform.

    Découvrir comment activer la facturation

    L'insertion de données en flux continu n'est pas disponible depuis la version gratuite. Le message d'erreur suivant s'affiche si vous essayez d'utiliser l'insertion en flux continu sans activer la facturation : BigQuery: Streaming insert is not allowed in the free tier. (BigQuery : l'insertion en flux continu n'est pas autorisée dans la version gratuite).

Vérifier la disponibilité des données

Les données insérées en flux continu sont disponibles pour une analyse en temps réel quelques secondes après la première insertion dans une table. Dans de rares circonstances (telles qu'une panne), les données du tampon d'insertion en flux continu peuvent être temporairement indisponibles. Dans ce cas, les requêtes continuent de s'exécuter avec succès, mais ignorent certaines données qui se trouvent encore dans le tampon. Ces requêtes contiennent un avertissement visible dans le champ errors de bigquery.jobs.getQueryResults, dans la réponse à bigquery.jobs.query ou dans le champ status.errors de bigquery.jobs.get.

La mise à disposition des données pour les opérations de copie et d'exportation peut prendre jusqu'à 90 minutes. En outre, lors de l'insertion en flux continu dans une table partitionnée, les données du tampon présentent une valeur NULL pour la pseudo-colonne _PARTITIONTIME. Pour déterminer si des données sont disponibles pour la copie et l'exportation, examinez la réponse tables.get pour une section nommée streamingBuffer. Si cette section est absente, les données doivent être disponibles pour la copie ou l'exportation et présenter une valeur non nulle pour la pseudo-colonne _PARTITIONTIME. Le champ streamingBuffer.oldestEntryTime peut également être utilisé pour identifier l'âge des enregistrements dans le tampon d'insertion en flux continu.

Assurer la cohérence des données

Pour garantir la cohérence des données, vous pouvez fournir un insertId pour chaque ligne insérée. BigQuery conserve cet ID en mémoire pendant au moins une minute. Si vous essayez d'insérer en flux continu le même ensemble de lignes au cours de cette période et que insertId est défini, BigQuery utilise la propriété insertId pour dédupliquer les données de manière optimale.

En présence de certaines conditions d'erreur telles que des erreurs réseau entre votre système et BigQuery ou des erreurs internes à BigQuery, il est possible qu'une nouvelle tentative d'insertion en flux continu soit nécessaire, l'état de l'opération étant impossible à déterminer. Dans ce cas, lors de la nouvelle tentative d'insertion, utilisez le même insertId pour le même ensemble de lignes afin que BigQuery puisse tenter de dédupliquer les données. Pour en savoir plus, consultez la section Résolution des erreurs d'insertion en flux continu.

Dans les rares cas où un centre de données Google perd la connectivité de manière inattendue, la déduplication automatique peut être impossible.

Si vous avez des exigences plus strictes pour vos données, sachez que le service Google Cloud Datastore autorise les transactions.

Désactiver la déduplication de manière optimale

Vous pouvez désactiver la déduplication de manière optimale en omettant le champ insertId pour chaque ligne insérée. Lorsque vous omettez le champ insertId, vous obtenez des quotas d'ingestion en flux continu beaucoup plus élevés pour la région US. Pour plus d'informations, consultez la page Quotas et limites.

Insérer des données en flux continu à plusieurs emplacements

Vous pouvez insérer des données en flux continu dans des ensembles de données situés aux États-Unis et en Europe. Lorsque BigQuery traite la demande insertAll, les données passent par des machines résidant en dehors de l'emplacement de l'ensemble de données. Si vous insérez des données en flux continu depuis un emplacement situé en dehors de celui de l'ensemble de données, vous risquez de rencontrer des taux de latence et d'erreur plus élevés.

Insérer des données en flux continu dans des tables partitionnées par date d'ingestion

Vous pouvez insérer des lignes individuelles en flux continu dans une table partitionnée à l'aide des requêtes insertAll. La partition de destination des données insérées est déduite par défaut de la date actuelle en fonction de l'heure UTC.

Si vous insérez des données en flux continu dans une table partitionnée par date d'ingestion, vous pouvez remplacer la date déduite en fournissant un décorateur de partition dans la requête insertAll. Par exemple, vous avez la possibilité d'insérer des données en flux continu dans la partition correspondant à 2017-03-01 pour la table mydataset.table à l'aide du décorateur de partition suivant :

mydataset.table$20170301

Les données qui arrivent sont temporairement associées à la partition UNPARTITIONED dans le tampon d'insertion en flux continu. Par conséquent, les données du tampon peuvent être exclues d'une requête par le filtrage des valeurs NULL de la partition UNPARTITIONED à l'aide de l'une des pseudo-colonnes ([_PARTITIONTIME] ou [_PARTITIONDATE] selon le type de données préféré).

Lors de l'insertion en flux continu à l'aide d'un décorateur de partition, vous pouvez insérer des données dans des partitions pour la période comprise entre les 31 derniers jours et les 16 prochains jours par rapport à la date actuelle (heure UTC). Pour écrire sur des partitions pour des dates situées en dehors de ces limites autorisées, vous pouvez utiliser des tâches de chargement ou de requête, comme décrit dans la section Ajouter ou écraser des données dans une table partitionnée.

Insérer des données en flux continu dans des tables partitionnées

Vous pouvez insérer des données en flux continu dans une table partitionnée en fonction d'une colonne DATE ou TIMESTAMP située dans la période comprise entre les douze derniers mois et les six prochains mois. Les données qui ne s'appliquent pas à cette période sont refusées.

Lors de l'insertion en flux continu, les données qui s'appliquent à la période comprise entre les sept derniers jours et les trois prochains jours sont placées dans le tampon d'insertion en flux continu, puis extraites vers les partitions correspondantes. Les données qui ne s'appliquent pas à cette période (mais qui correspondent à celle comprise entre les 12 derniers mois et les six prochains mois) sont placées dans un tampon d'insertion en flux continu, puis extraites vers la partition UNPARTITIONED. Lorsque les données non partitionnées sont suffisantes, elles sont chargées dans les partitions correspondantes.

Créer des tables automatiquement à l'aide de modèles

Dans BigQuery, un schéma d'utilisation courant de l'insertion de données en flux continu consiste à diviser une table logique en tables plus petites pour créer des ensembles de données plus restreints (par exemple, par ID utilisateur). Pour créer des ensembles de données plus petits par date, utilisez des tables partitionnées. Pour créer des tables plus petites non basées sur des dates, utilisez des modèles de tables. Dans ce cas, BigQuery crée les tables pour vous.

Pour utiliser un modèle de table avec l'API BigQuery, ajoutez un paramètre templateSuffix à la requête insertAll. Pour l'outil de ligne de commande bq, ajoutez l'indicateur template_suffix à la commande insert. Si BigQuery détecte un paramètre templateSuffix ou l'indicateur template_suffix, il traite la table ciblée en tant que modèle de base, et crée une table qui partage le même schéma que la table ciblée et dont le nom inclut le suffixe spécifié :

<targeted_table_name> + <templateSuffix>

Un modèle de table vous évite de devoir créer chaque table individuellement et de spécifier le schéma de chacune. Il vous suffit de créer un modèle unique et de fournir différents suffixes pour que BigQuery génère les nouvelles tables pour vous. BigQuery place les tables dans les mêmes projet et ensemble de données. La mise à jour du schéma est également facilitée, car vous ne devez mettre à jour que le modèle.

Les tables créées à partir de modèles sont généralement disponibles en quelques secondes. Il arrive en de rares occasions que le processus prenne plus de temps.

Modifier le schéma d'un modèle de table

Si vous modifiez le schéma d'un modèle de table, toutes les tables générées ultérieurement utilisent le schéma mis à jour. Les tables existantes ne sont pas concernées, sauf si elles contiennent toujours un tampon d'insertion en flux continu.

Si vous modifiez le schéma d'un modèle de table avec rétrocompatibilité, le schéma des tables existantes qui contiennent toujours un tampon d'insertion en flux continu est également mis à jour. Sans rétrocompatibilité par contre, toutes les données mises en mémoire tampon utilisant l'ancien schéma seront perdues. En outre, vous ne pourrez pas insérer de nouvelles données en flux continu dans des tables existantes qui utilisent l'ancien schéma, désormais incompatible.

Une fois que vous avez modifié le schéma d'un modèle de table, attendez la propagation des modifications avant d'essayer d'insérer de nouvelles données ou d'interroger des tables générées. Les requêtes d'insertion de nouveaux champs devraient aboutir en quelques minutes. Les tentatives d'interrogation des nouveaux champs peuvent prendre plus de temps, jusqu'à 90 minutes.

Pour modifier le schéma d'une table générée, attendez que l'insertion en flux continu à l'aide du modèle de table se termine et que la section des statistiques d'insertion disparaisse de la réponse tables.get() (ce qui indique qu'aucune donnée n'est mise en mémoire tampon dans la table).

Détails du modèle de table

Valeur du suffixe de modèle
La valeur templateSuffix (ou --template_suffix) ne doit contenir que des lettres (a-z, A-Z), des chiffres (0-9) ou des traits de soulignement (_). La longueur maximale combinée du nom de table et du suffixe de table est de 1 024 caractères.
Quota
Les mêmes quotas s'appliquent à toutes les tables, qu'elles soient basées sur des modèles ou créées manuellement.
Durée de vie
La table générée hérite son délai d'expiration de l'ensemble de données. Comme les données insérées en flux continu, les tables générées ne peuvent pas être immédiatement copiées ni exportées.
Déduplication
La déduplication ne se produit qu'entre des références uniformes à une table de destination. Par exemple, si vous insérez des données en flux continu dans une table générée à l'aide de modèles et d'une commande insertAll standard de façon simultanée, aucune déduplication ne se produit entre les lignes insérées par les modèles et par la commande insertAll standard.
Vues
Le modèle de table et les tables générées ne doivent pas être des vues.

Exemples de cas d'utilisation

Journalisation volumineuse d'événements

Si vous possédez une application qui collecte une grande quantité de données en temps réel, les insertions en flux continu peuvent être un choix judicieux. En général, ces types d'applications présentent les critères suivants :

  • Pas de mode transactionnel – Volume élevé de lignes ajoutées en permanence. L'application peut tolérer un cas de duplication ou d'indisponibilité temporaire des données de manière exceptionnelle.
  • Analyse globale – Les requêtes sont généralement effectuées en vue d'une analyse des tendances, par opposition à une sélection d'enregistrements restreinte ou unique.

Le suivi des événements est un exemple de journalisation volumineuse d'événements. Supposons que vous ayez une application mobile qui suit les événements. Cette application ou les serveurs mobiles peuvent enregistrer indépendamment les interactions des utilisateurs ou les erreurs système et les insérer en flux continu dans BigQuery. Vous pouvez analyser ces données pour déterminer des tendances générales (comme des zones générant un taux élevé d'interactions ou de problèmes) et surveiller les conditions d'erreur en temps réel.

Supprimer manuellement les doublons

Vous pouvez suivre le processus manuel ci-dessous pour vérifier l'absence de ligne en double après l'insertion en flux continu.

  1. Ajoutez la valeur insertId en tant que colonne du schéma de table et incluez insertId dans les données de chaque ligne.
  2. Lorsque l'insertion en flux continu est terminée, exécutez la requête suivante pour rechercher les doublons : 

    #standardSQL
SELECT
  MAX(count) FROM(
  SELECT
    ID_COLUMN,
    count(*) as count
  FROM
    `TABLE_NAME`
  GROUP BY
    ID_COLUMN)

    Si le résultat est supérieur à 1, il existe des doublons.
  3. Pour supprimer les lignes en double, exécutez la requête suivante. Vous devez spécifier une table de destination, autoriser les résultats volumineux et désactiver leur regroupement. 

    #standardSQL
SELECT
  * EXCEPT(row_number)
FROM (
  SELECT
    *,
    ROW_NUMBER()
          OVER (PARTITION BY ID_COLUMN) row_number
  FROM
    `TABLE_NAME`)
WHERE
  row_number = 1

Remarques sur la requête de suppression des doublons :

  • La stratégie la plus sûre consiste à cibler une nouvelle table. Vous pouvez également cibler la table source avec la préférence d'écriture WRITE_TRUNCATE.
  • La requête de suppression des doublons ajoute une colonne row_number avec la valeur 1 à la fin du schéma de table. Elle utilise une instruction SELECT * EXCEPT en langage SQL standard pour exclure la colonne row_number de la table de destination. Le préfixe #standardSQL active le langage SQL standard pour cette requête. Vous pouvez également sélectionner des noms de colonne spécifiques pour omettre cette colonne.
  • Pour interroger des données actives avec doublons supprimés, vous pouvez également créer une vue sur votre table à l'aide de la requête de suppression des doublons. Sachez que le coût de la requête par rapport à la vue est calculé en fonction des colonnes sélectionnées dans votre vue, ce qui peut entraîner de grandes tailles d'octets analysés.

Résolution des erreurs d'insertion en flux continu

Pour en savoir plus, consultez la section Résolution des erreurs d'insertion en flux continu de la page relative au dépannage.

Haut de page

Exemples d'insertions en flux continu

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


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

public class BigQueryTableInsertRows
{
    public void TableInsertRows(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        BigQueryInsertRow[] rows = new BigQueryInsertRow[]
        {
            // The insert ID is optional, but can avoid duplicate data
            // when retrying inserts.
            new BigQueryInsertRow(insertId: "row1") {
                { "name", "Washington" },
                { "post_abbr", "WA" }
            },
            new BigQueryInsertRow(insertId: "row2") {
                { "name", "Colorado" },
                { "post_abbr", "CO" }
            }
        };
        client.InsertRows(datasetId, tableId, rows);
    }
}

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 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")
u := client.Dataset(datasetID).Table(tableID).Inserter()
items := []*Item{
	// Item implements the ValueSaver interface.
	{Name: "Phred Phlyntstone", Age: 32},
	{Name: "Wylma Phlyntstone", Age: 29},
}
if err := u.Put(ctx, items); err != nil {
	return err
}

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java. 

TableId tableId = TableId.of(datasetName, tableName);
// Values of the row to insert
Map<String, Object> rowContent = new HashMap<>();
rowContent.put("booleanField", true);
// Bytes are passed in base64
rowContent.put("bytesField", "Cg0NDg0="); // 0xA, 0xD, 0xD, 0xE, 0xD in base64
// Records are passed as a map
Map<String, Object> recordsContent = new HashMap<>();
recordsContent.put("stringField", "Hello, World!");
rowContent.put("recordField", recordsContent);
InsertAllResponse response =
    bigquery.insertAll(
        InsertAllRequest.newBuilder(tableId)
            .addRow(rowContent)
            // More rows can be added in the same RPC by invoking .addRow() on the builder.
            // You can also supply optional unique row keys to support de-duplication scenarios.
            .build());
if (response.hasErrors()) {
  // If any of the insertions failed, this lets you inspect the errors
  for (Entry<Long, List<BigQueryError>> entry : response.getInsertErrors().entrySet()) {
    // inspect row error
  }
}

Node.js

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Node.js. 

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

async function insertRowsAsStream() {
  // Inserts the JSON objects into my_dataset:my_table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';
  // const rows = [{name: 'Tom', age: 30}, {name: 'Jane', age: 32}];

  // Create a client
  const bigqueryClient = new BigQuery();

  // Insert data into a table
  await bigqueryClient
    .dataset(datasetId)
    .table(tableId)
    .insert(rows);
  console.log(`Inserted ${rows.length} rows`);
}
insertRowsAsStream();

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId   = 'The BigQuery table ID';
// $data = [
//     "field1" => "value1",
//     "field2" => "value2",
// ];

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);

$insertResponse = $table->insertRows([
    ['data' => $data],
    // additional rows can go here
]);
if ($insertResponse->isSuccessful()) {
    print('Data streamed into BigQuery successfully' . PHP_EOL);
} else {
    foreach ($insertResponse->failedRows() as $row) {
        foreach ($row['errors'] as $error) {
            printf('%s: %s' . PHP_EOL, $error['reason'], $error['message']);
        }
    }
}

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 relatif à l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API BigQuery Python. 

# TODO(developer): Uncomment the lines below and replace with your values.
# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'  # replace with your dataset ID
# For this sample, the table must already exist and have a defined schema
# table_id = 'my_table'  # replace with your table ID
# table_ref = client.dataset(dataset_id).table(table_id)
# table = client.get_table(table_ref)  # API request

rows_to_insert = [
    (u'Phred Phlyntstone', 32),
    (u'Wylma Phlyntstone', 29),
]

errors = client.insert_rows(table, rows_to_insert)  # API request

assert errors == []

Ruby

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Ruby dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Ruby. 

require "google/cloud/bigquery"

def table_insert_rows dataset_id = "your_dataset_id", table_id = "your_table_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table    = dataset.table table_id

  row_data = [
    { name: "Alice", value: 5  },
    { name: "Bob",   value: 10 }
  ]
  response = table.insert row_data

  if response.success?
    puts "Inserted rows successfully"
  else
    puts "Failed to insert #{response.error_rows.count} rows"
  end
end

Haut de page

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.