Lee datos con la API de BigQuery mediante paginación
En este documento, se describe cómo leer datos de tablas y resultados de consultas con la API de BigQuery mediante paginación.
Desplázate por los resultados mediante 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 | Valor maxResults predeterminado |
Valor maxResults máximo |
Valor maxFieldValues máximo |
---|---|---|---|---|
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 . |
Ilimitada | Ilimitada | 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, tabledata.list
puede mostrar hasta 100 MB de datos1, que es coherente 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.
1 El tamaño de la fila es aproximado, ya que se basa en la representación interna de los datos de la fila. El tamaño máximo de la fila se aplica durante ciertas etapas de la ejecución del trabajo de consulta.
jobs.getQueryResults
puede mostrar 20 MB de datos, a menos que de forma explícita se solicite una cantidad mayor mediante la asistencia.
Una página es un subconjunto del número total de filas. Si tus resultados ocupan más de una página de datos, los datos tienen una propiedad pageToken
. Para recuperar la página siguiente de resultados, haz otra llamada a list
y, también, incluye el valor del token como un parámetro URL llamado pageToken
.
El método tabledata.list
, que se utiliza para desplazarse por los datos de la tabla, usa un valor de desplazamiento de fila o un token de página. Consulta la página sobre cómo explorar datos de tablas para obtener más información.
Realiza iteraciones en los resultados de las bibliotecas cliente
Las bibliotecas cliente de la nube controlan los detalles de bajo nivel de la paginación de las APIs y proporcionan una experiencia más similar al iterador que simplifica la interacción con los elementos individuales en las respuestas de la página.
Los siguientes ejemplos muestran la paginación a través de 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.
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.
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.
La biblioteca cliente de Cloud para Go se pagina automáticamente de forma predeterminada, por lo que no necesitas implementar la paginación, por ejemplo:
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.
La biblioteca cliente de Cloud para Node.js se pagina automáticamente de forma predeterminada, por lo que no necesitas implementar la paginación, por ejemplo:
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.
La paginación se realiza de forma automática en las bibliotecas cliente de Cloud para PHP mediante la función de generador rows
, que recupera la siguiente página de resultados durante la iteración.
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.
La biblioteca cliente de Cloud para Python se pagina automáticamente de forma predeterminada, por lo que no necesitas implementar la paginación, por ejemplo:
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.
La paginación se realiza de forma automática en las bibliotecas cliente de Cloud para Ruby mediante Table#data
y Data#next
.
Solicita páginas arbitrarias y evita llamadas redundantes a las listas
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, aunque no hay un indicio claro de que así sea. Para mitigar este efecto, 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:
Muestra valores de lista si los valores cambiaron.
Si solo deseas que se muestre una página con los valores de la lista si los valores cambiaron, puedes crear una llamada a la lista con un ETag almacenado con anterioridad mediante el encabezado HTTP "if-none-match". Si el ETag que proporcionas no coincide con el ETag en el servidor, BigQuery muestra una página de valores de lista nuevos. Si los ETags coinciden, BigQuery muestra un código de estado
HTTP 304 Not Modified
y ningún valor. Un ejemplo de esto podría ser una página web en la que los usuarios pueden completar, de manera periódica, información que se encuentra almacenada en BigQuery. Si no hay cambios en los datos, puedes evitar hacer llamadas redundantes a las listas en BigQuery mediante el encabezado if-none-match con ETags.Muestra valores de lista si los valores no cambiaron.
Si solo deseas que se muestre una página con los valores de la lista en caso de que los valores no hayan cambiado, puedes usar el encabezado HTTP "if-match". BigQuery hace coincidir los valores de los ETag y muestra la página de resultados si los resultados no han cambiado, o muestra un resultado 412 "Precondition Failed" si la página cambió.
Desplázate por los resultados de la consulta
Cada consulta escribe en una tabla de destino. Si no se proporciona una tabla de destino, la API de BigQuery propaga automáticamente la propiedad de tabla de destino mediante la referencia a una tabla anónima temporal.
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.
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.
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.