Parcourir les 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 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 de résultats suivante, effectuez un autre appel de list et incluez la valeur de jeton en tant que paramètre 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 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 int TableDataList(
    string datasetId, string tableId, int pageSize, BigQueryClient client)
{
    int recordCount = 0;
    var result = client.ListRows(datasetId, tableId, null,
        new ListRowsOptions { PageSize = pageSize });
    // If there are more rows than were returned in the first page of results,
    // iterating over the rows will lazily evaluate the results each time,
    // making further requests as necessary.
    foreach (var row in result)
    {
        Console.WriteLine($"{row["title"]}: {row["unique_words"]}");
        recordCount++;
    }
    return recordCount;
}

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.

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

La bibliothèque cliente Google Cloud Client pour Go est automatiquement paginée par défaut. Ainsi, vous n'avez pas besoin d'implémenter la pagination, par 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 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.

La bibliothèque cliente Google Cloud pour Node.js est automatiquement paginée par défaut. Ainsi, vous n'avez pas à implémenter la pagination, par 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: projectId,
});

// Lists rows in the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .getRows()
  .then(results => {
    const rows = results[0];
    console.log('Rows:');
    rows.forEach(row => console.log(row));
  })
  .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.

La pagination se produit automatiquement dans la Bibliothèque cliente Google Cloud pour PHP à l'aide des rows de fonctions de générateur, qui récupèrent 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 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.

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

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

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset containing table"
# table_id   = "ID of the table to display data for"

require "google/cloud/bigquery"

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

table.data.each do |row|
  row.each      do |column_name, value|
    puts "#{column_name} = #{value}"
  end
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…