Lire des données avec l'API BigQuery à l'aide de la pagination
Ce document explique comment lire les données de table et les résultats de requête avec l'API BigQuery à l'aide de la pagination.
Parcourir des résultats à l'aide de l'API
Toutes les méthodes *collection*.list
renvoient des résultats paginés sous certaines conditions. La propriété maxResults
limite le nombre de résultats par page.
Méthode | Critères de pagination | Valeur maxResults par défaut |
Valeur maxResults maximale |
Valeur maxFieldValues maximale |
---|---|---|---|---|
tabledata.list |
Renvoie des résultats paginés si la réponse est d'une taille supérieure à 10 Mo1 de données ou contient un nombre de lignes supérieur à maxResults . |
Illimité | Illimité | Illimité |
Toutes les autres méthodes *collection*.list |
Renvoie des résultats paginés si le nombre de lignes de la réponse est supérieur à maxResults et inférieur aux limites maximales. |
10 000 | Illimité | 300 000 |
Si le résultat dépasse la limite d'octets ou de champs, il est tronqué pour respecter la limite. Si une ligne est supérieure à la limite d'octets ou de champ définie, tabledata.list
peut renvoyer jusqu'à 100 Mo de données1, ce qui est conforme à la limite maximale de taille de ligne pour les résultats de requête.
Il n'existe pas de taille minimale par page, et certaines pages peuvent renvoyer plus de lignes que d'autres.
1 La taille des lignes est approximative, car elle est basée sur la représentation interne des données de ligne. La limite maximale de taille de ligne est appliquée à certaines étapes de l'exécution de la tâche de requête.
jobs.getQueryResults
peut renvoyer 20 Mo de données, sauf si un volume supérieur est explicitement demandé via l'assistance.
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 contiennent une propriété pageToken
. Pour extraire la page de résultats suivante, effectuez un autre appel list
et incluez la valeur du jeton en tant que paramètre d'URL nommé pageToken
.
La méthode tabledata.list
, qui permet de paginer les données d'une table, utilise une valeur de décalage de ligne ou un jeton de page. Pour en savoir plus, consultez la section Parcourir les données d'une table.
Effectuer des itérations via les résultats des bibliothèques clientes
Les bibliothèques clientes cloud gèrent les détails de bas niveau de la pagination des API et offrent une expérience semblable à celle d'un itérateur qui simplifie l'interaction avec les éléments individuels dans les réponses de la page.
Vous trouverez ci-dessous des exemples de pagination sur des données de table BigQuery.
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.
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.
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.
Par défaut, les bibliothèques clientes Cloud pour Go effectuent automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :
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.
Par défaut, les bibliothèques clientes Cloud pour Node.js effectuent automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :
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.
La pagination s'effectue automatiquement dans les bibliothèques clientes 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.
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.
Par défaut, les bibliothèques clientes Cloud pour Python effectuent automatiquement la pagination. Vous n'avez donc pas besoin d'effectuer cette tâche vous-même. Exemple :
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.
La pagination s'effectue automatiquement dans les bibliothèques clientes Cloud pour Ruby à l'aide de Table#data
et de Data#next
.
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
.
Toutes les méthodes collection.list
(sauf Tabledata) renvoient une propriété etag
dans le résultat. Cette propriété est un hachage des résultats de la page, qui permet de vérifier si la page a été modifiée depuis la dernière requête. Lorsque vous adressez à BigQuery une requête contenant une valeur ETag, BigQuery compare cette valeur à la valeur ETag renvoyée par l'API et répond en fonction de la correspondance entre les deux valeurs. Vous pouvez utiliser les ETag pour éviter les appels de liste redondants comme suit :
Pour renvoyer des valeurs de liste si les valeurs ont changé.
Si vous souhaitez seulement 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 stocké à 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 code d'état
HTTP 304 Not Modified
et aucune valeur. Exemple : une page Web où les utilisateurs peuvent remplir des informations stockées dans BigQuery de façon récurrente. Si vos données ne sont pas modifiées, vous pouvez éviter les appels de liste redondants à BigQuery en utilisant l'en-tête "if-none-match" combiné avec des ETag.Pour renvoyer des valeurs de liste si les valeurs n'ont pas changé.
Si vous ne souhaitez renvoyer une page de valeurs de liste que dans le cas où les valeurs n'ont pas changé, vous pouvez spécifier 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 changé, ou renvoie un message d'erreur 412 "Precondition Failed" (Échec de la condition préalable) en cas de modification de la page.
Parcourir des résultats de requêtes
Chaque requête écrit dans une table de destination. Si aucune table de destination n'est fournie, l'API BigQuery renseigne automatiquement la propriété de table de destination avec une référence à une table anonyme temporaire.
API
Lisez le champ jobs.config.query.destinationTable
pour déterminer la table dans laquelle les résultats de la requête ont été écrits.
Appelez la méthode tabledata.list
pour lire les résultats de la requête.
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.
Pour définir le nombre de lignes renvoyées sur chaque page, utilisez une tâche GetQueryResults
et définissez l'option pageSize
sur l'objet QueryResultsOption
que vous transmettez, comme illustré dans l'exemple suivant :
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
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.
Python
La méthode QueryJob.result
renvoie un itérable des résultats de la requête. Par ailleurs,
- Lisez la propriété
QueryJob.destination
. Si cette propriété n'est pas configurée, elle est définie par l'API sur une référence à une table anonyme temporaire. - Obtenez le schéma de la table avec la méthode
Client.get_table
. - Créez un itérable sur toutes les lignes de la table de destination à l'aide de la méthode
Client.list_rows
.
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.