Desplázate por los datos de tablas
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
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.
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 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.
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 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.
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. 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 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 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 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 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 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.
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 Node.js de BigQuery.
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 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.