Usa la paginación con la API de BigQuery
En este documento, se describe cómo leer datos de tablas y resultados de consultas en conjuntos de datos grandes con la paginación de la API de BigQuery.
Con la paginación, BigQuery divide un conjunto de datos grande en fragmentos más pequeños llamados páginas. Para la mayoría de los usuarios, las bibliotecas cliente de Cloud controlan este proceso automáticamente, pero también puedes controlar la paginación de forma manual para casos de uso específicos, como las aplicaciones web.
Usa la paginación automática
Las bibliotecas cliente de Cloud controlan los detalles de bajo nivel de la paginación de la API y proporcionan una experiencia similar a un iterador. Cuando iteras los resultados, la biblioteca recupera automáticamente la siguiente página de datos cuando es necesario.
En los siguientes ejemplos, se muestra cómo iterar automáticamente los datos de tablas de BigQuery.
C#
Antes de probar este ejemplo, sigue las instrucciones de configuración para C# incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para C#.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
PHP
Antes de probar este ejemplo, sigue las instrucciones de configuración para PHP incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Ruby
Antes de probar este ejemplo, sigue las instrucciones de configuración para Ruby incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Controla el tamaño de la página
Puedes especificar la cantidad máxima de filas que se muestran en cada solicitud de red configurando un tamaño de página. Establecer el tamaño de la página es útil para optimizar el uso de la red o ajustar los datos en la memoria.
En la mayoría de las bibliotecas cliente, puedes usar un parámetro max_results o page_size cuando llamas a métodos como list_rows o query.
Usa la paginación manual con tokens de página
La paginación manual es útil para las aplicaciones sin estado, como un servicio web en el que un usuario hace clic en Siguiente para ver el siguiente conjunto de resultados. En este caso, el servidor no mantiene un iterador activo entre las solicitudes.
En su lugar, usa un token de página de la siguiente manera:
- Solicita una página. Llama a la API y recibe un parámetro
pageTokenjunto con las filas. - Reanudar En la siguiente solicitud, vuelve a pasar ese mismo parámetro
pageTokena BigQuery para recuperar el siguiente fragmento de datos.
En los siguientes ejemplos, se muestra cómo recuperar un token de página y usarlo para recuperar la siguiente página de resultados de la búsqueda.
API
Lee el campo jobs.config.query.destinationTable para determinar la tabla en la que se escribieron los resultados de la consulta.
Llama a tabledata.list para leer los resultados de la consulta.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Para establecer la cantidad de filas que se muestran en cada página, usa un trabajo GetQueryResults y establece la opción pageSize del objeto QueryResultsOption que pasas, como se muestra en el siguiente ejemplo:
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Python
El método QueryJob.result muestra un iterable de los resultados de la consulta. O, como alternativa:
- Lee la propiedad
QueryJob.destination. Si la propiedad no está configurada, la API la establece en una referencia a una tabla anónima temporal. - Obtén el esquema de la tabla con el método
Client.get_table. - Crea un iterable en todas las filas de la tabla de destino con el método
Client.list_rows.
Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Optimiza con ETags
Cuando retrocedes la página o saltas a páginas arbitrarias con valores de pageToken almacenados en caché, es posible que los datos de tus páginas hayan cambiado desde la última vez que se vieron. Para mitigar este resultado, puedes usar la propiedad etag.
Cada método collection.list (excepto Tabledata) muestra una propiedad etag en el resultado. Esta propiedad genera un hash de los resultados de la página que se pueden usar para verificar si esta cambió desde la última solicitud. Cuando realizas una solicitud a BigQuery con un valor Etag, BigQuery compara el valor ETag con el valor de ETag que la API mostró y responde si esos valores coinciden. Puedes usar las ETag para evitar llamadas redundantes a las listas de la siguiente manera:
- Para devolver valores solo si cambiaron, haz una llamada a la lista con un ETag almacenado con anterioridad usando el encabezado HTTP
If-None-Match. Si los ETags coinciden, BigQuery devuelve un código de estadoHTTP 304 Not Modifiedy no devuelve datos, lo que ahorra ancho de banda. - Para devolver valores solo si no cambiaron, usa el encabezado HTTP
If-Match. BigQuery devuelve un412 Precondition Failedsi la página cambió.
Referencia: Límites y criterios de la API
Todos los métodos *collection*.list muestran resultados paginados en determinadas circunstancias. La propiedad maxResults limita la cantidad de resultados por página.
| Método | Criterios de paginación | Límite predeterminado de maxResults |
Límite máximo de maxResults |
Límite máximo de maxFieldValues |
|---|---|---|---|---|
tabledata.list |
Muestra resultados paginados si el tamaño de la respuesta supera los
10 MB1 de datos o más de las filas de maxResults. |
Ilimitado | Ilimitado | Ilimitado |
Todos los demás métodos *collection*.list |
Muestra resultados paginados si el tamaño de la respuesta supera las filas en
maxResults y también es inferior a los límites máximos. |
10,000 | Ilimitado | 300,000 |
Si el resultado es mayor que el límite de bytes o campos, el resultado se corta para ajustarlo al límite. Si una fila supera el límite de bytes o campos, el método tabledata.list puede devolver hasta 100 MB de datos1, lo que coincide con el límite máximo de tamaño de fila para los resultados de la consulta.
No hay un tamaño mínimo por página, y algunas páginas pueden mostrar más filas que otras.
El método de la API de REST jobs.getQueryResults puede devolver 20 MB de datos, a menos que solicites explícitamente una cantidad mayor a través del equipo de asistencia.
1 El tamaño de la fila es aproximado, ya que se basa en la representación interna de los datos de la fila. Este se aplica durante ciertas etapas de la ejecución del trabajo de consulta.