En este documento, se describe cómo desplazarse por los datos de tablas y los resultados de la consulta mediante la API de REST de BigQuery.
Desplázate por los resultados mediante la API
Todos los métodos *collection*.list
muestran resultados paginados en determinadas circunstancias. La propiedad maxResults
controla el número 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 . |
100,000 | 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 se encuentra por debajo de 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.
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.getQueryResult
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 de la cantidad total de filas. Si tus resultados ocupan más de una página de datos, los datos que resulten tendrán 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.
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. Si deseas obtener más información, consulta la documentación de referencia de la API de C# de BigQuery.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que se encuentran 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.
Comienza a usarlo
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Go de BigQuery.
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 que se encuentran 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 Node.js de BigQuery.
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. Si deseas obtener más información, consulta la documentación de referencia de la API de PHP de BigQuery.
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 esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.
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. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.
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 las siguientes maneras:
Si solo deseas que se muestren los valores de la lista si los valores han cambiado:
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 resultado HTTP 304 "Not Modified" y no hay valores. Un ejemplo de esto podría ser una página web donde los usuarios pueden completar, de manera periódica, información que se encuentra almacenada en BigQuery. Puedes evitar hacer llamadas redundantes a las listas en BigQuery si no hay cambios en tus datos con el encabezado if-none-match con ETags.
Si solo deseas que se muestren los valores de la lista si los valores han cambiado:
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ó.
Paginación a través de resultados de consultas
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 que se encuentran 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.
Python
El método QueryJob.result
muestra un iterable de los resultados de la consulta. O, como alternativa:
- Lee la propiedad
QueryJob.destination
. Si no se configura, la API establecerá esta propiedad como 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 esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.