Parcourir des résultats de requêtes

Ce document explique comment parcourir les résultats de requêtes à l'aide de l'API REST de BigQuery.

Parcourir des résultats à l'aide de l'API

Toutes les méthodes collection.list renvoient des résultats paginés sous certaines conditions. Le nombre de résultats par page est contrôlé par la propriété maxResults.

Méthode Critères de pagination Valeur maxResults par défaut Valeur maxResults maximale
Tabledata.list Renvoie des résultats paginés si la taille de la réponse est supérieure à 10 Mo de JSON sérialisé ou supérieure au nombre de lignes maxResults. 100 000 100 000
Toutes les autres méthodes collection.list Renvoie les résultats paginés si la réponse a plus de lignes que maxResults. 50 1 000

Si vous définissez maxResults sur une valeur supérieure à la valeur maximale indiquée ci-dessus, les résultats sont paginés en fonction de la valeur maximale.

Une page est un sous-ensemble du nombre total de lignes. Si vos résultats correspondent à plus d'une page de données, les données de résultats vont contenir la propriété pageToken. Pour récupérer la page suivante de résultats, appelez de nouveau la méthode list et incluez la valeur du jeton en tant que paramètre d'URL nommé pageToken.

La méthode bigquery.tabledata.list, qui permet de parcourir les données d'une table, utilise une valeur de décalage de ligne ou un jeton de page. Consultez la section Parcourir les données d'un tableau pour plus d'informations.

Vous trouverez ci-dessous des exemples de pagination sur des résultats de requêtes BigQuery.

C#

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour C# 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.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryBrowseTable
{
    public void BrowseTable(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference tableReference = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        // Load all rows from a table
        PagedEnumerable<TableDataList, BigQueryRow> result = client.ListRows(
            tableReference: tableReference,
            schema: null
        );
        // Print the first 10 rows
        foreach (BigQueryRow row in result.Take(10))
        {
            Console.WriteLine($"{row["corpus"]}: {row["word_count"]}");
        }
    }
}

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 tableIdObject = TableId.of(datasetName, tableName);
// This example reads the result 100 rows per RPC call. If there's no need to limit the number,
// simply omit the option.
TableResult tableData =
    bigquery.listTableData(tableIdObject, TableDataListOption.pageSize(100));
for (FieldValueList row : tableData.iterateAll()) {
  // do something with the row
}

Go

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

Par défaut, la bibliothèque cliente Google Cloud pour Go effectue automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :

table := client.Dataset(datasetID).Table(tableID)
it := table.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

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.

Par défaut, la bibliothèque cliente Google Cloud pour Node.js effectue automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :

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

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

// Creates a client
const bigquery = new BigQuery({projectId});

// Lists rows in the table
const [rows] = await bigquery
  .dataset(datasetId)
  .table(tableId)
  .getRows();

console.log('Rows:');
rows.forEach(row => console.log(row));

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.

La pagination s'effectue automatiquement dans la bibliothèque cliente Google Cloud pour PHP à l'aide de la fonction de générateur rows, qui récupère la page de résultats suivante lors de l'itération.

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';
// $maxResults = 10;

$maxResults = 10;
$startIndex = 0;

$options = [
    'maxResults' => $maxResults,
    'startIndex' => $startIndex
];
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$numRows = 0;
foreach ($table->rows($options) as $row) {
    print('---');
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, $value);
    }
    $numRows++;
}

Python

Avant de tester cet exemple, suivez la procédure de configuration de Python dans le guide de démarrage rapide de BigQuery à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.

Par défaut, la bibliothèque cliente Google Cloud pour Python effectue automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :

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

dataset_ref = client.dataset('samples', project='bigquery-public-data')
table_ref = dataset_ref.table('shakespeare')
table = client.get_table(table_ref)  # API call

# Load all rows from a table
rows = client.list_rows(table)
assert len(list(rows)) == table.num_rows

# Load the first 10 rows
rows = client.list_rows(table, max_results=10)
assert len(list(rows)) == 10

# Specify selected fields to limit the results to certain columns
fields = table.schema[:2]  # first two columns
rows = client.list_rows(table, selected_fields=fields, max_results=10)
assert len(rows.schema) == 2
assert len(list(rows)) == 10

# Use the start index to load an arbitrary portion of the table
rows = client.list_rows(table, start_index=10, max_results=10)

# Print row data in tabular format
format_string = '{!s:<16} ' * len(rows.schema)
field_names = [field.name for field in rows.schema]
print(format_string.format(*field_names))  # prints column headers
for row in rows:
    print(format_string.format(*row))      # prints row data

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.

La pagination s'effectue automatiquement dans la bibliothèque cliente Google Cloud pour Ruby à l'aide de Table#data et de Data#next.

require "google/cloud/bigquery"

def browse_table
  bigquery = Google::Cloud::Bigquery.new project_id: "bigquery-public-data"
  dataset  = bigquery.dataset "samples"
  table    = dataset.table "shakespeare"

  # Load all rows from a table
  rows = table.data

  # Load the first 10 rows
  rows = table.data max: 10

  # Print row data
  rows.each { |row| puts row }
end

Demander des pages arbitraires et éviter les appels de liste redondants

Lorsque vous exécutez une pagination en arrière ou que vous accédez à des pages arbitraires en utilisant les valeurs pageToken mises en cache, il est possible que les données de vos pages aient été modifiées depuis la dernière consultation, mais rien n'indique clairement que c'est le cas. Pour limiter ce problème, vous pouvez utiliser la propriété Etag.

Chaque méthode de collecte de liste (sauf Tabledata) renvoie une propriété Etag dans le résultat. Cette propriété est un hachage des résultats de la page pouvant être utilisés pour vérifier si la page a été modifiée depuis la dernière requête. Lorsque vous adressez une requête à BigQuery avec une valeur ETag, BigQuery compare la valeur Etag actuelle à la valeur ETag renvoyée par l'API et répond en fonction de la correspondance entre les valeurs ETag. Vous pouvez utiliser les ETag pour éviter les appels de liste redondants de la manière suivante :

  • Si vous souhaitez uniquement renvoyer des valeurs de liste en cas de changement de valeurs :

    Si vous souhaitez uniquement renvoyer une page de valeurs de liste en cas de changement de valeurs, vous pouvez effectuer un appel de liste avec un ETag précédemment enregistré à l'aide de L'en-tête HTTP "if-none-match". Si l'ETag que vous fournissez ne correspond pas à l'ETag sur le serveur, BigQuery renvoie une page de nouvelles valeurs de liste. Si les ETag correspondent, BigQuery renvoie un résultat HTTP 304 "non modifié" et aucune valeur. Par exemple, une page Web où les utilisateurs peuvent remplir des informations stockées dans BigQuery de façon récurrente. Vous pouvez éviter de faire des appels de liste redondants à BigQuery si vos données ne sont pas modifiées en vous servant de l'en-tête if-none-match combiné avec des ETag.

  • Si les valeurs n'ont pas été modifiées et que vous souhaitez uniquement renvoyer des valeurs de listes :

    Si les valeurs de liste n'ont pas été modifiées et que vous souhaitez uniquement renvoyer une page de valeurs de liste, vous pouvez utiliser l'en-tête HTTP "if-match". BigQuery vérifie la correspondance entre les valeurs ETag et renvoie la page de résultats si les résultats n'ont pas été changés ou renvoient un message d'erreur 412 "Precondition Failed" en cas de modification de la page.

Remarque : Bien que les ETag soient un excellent moyen d'éviter les appels de liste redondants, vous pouvez appliquer les mêmes méthodes pour déterminer si des objets ont été modifiés. Par exemple, vous pouvez effectuer une requête Get pour une table spécifique et utiliser les ETag pour déterminer si la table a été modifiée avant de renvoyer la réponse complète.


Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.