Leer 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 la paginación.
Desplazarse por los resultados con la API
Todos los métodos *collection*.list
devuelven resultados paginados en determinadas circunstancias. La propiedad maxResults
limita el número de resultados por página.
Método | Criterios de paginación | Valor predeterminado de maxResults |
Valor máximo de maxResults |
Valor máximo de maxFieldValues |
---|---|---|---|---|
tabledata.list |
Devuelve resultados paginados si el tamaño de la respuesta es superior a 10 MB1 de datos o a maxResults
filas. |
Ilimitado | Ilimitado | Ilimitado |
Todos los demás métodos de *collection*.list |
Devuelve resultados paginados si la respuesta tiene más de maxResults filas y menos que los límites máximos. |
10.000 | Ilimitado | 300.000 |
Si el resultado es mayor que el límite de bytes o de campos, se recorta para ajustarse al límite. Si una fila supera el límite de bytes o de campos, tabledata.list
puede devolver hasta 100 MB de datos1, lo que coincide con el límite de tamaño máximo de las filas de los resultados de las consultas.
No hay un tamaño mínimo por página y es posible que algunas páginas devuelvan más filas que otras.
1El tamaño de las filas es aproximado porque se basa en la representación interna de los datos que contienen. Este límite se aplica durante ciertas fases de la ejecución de las tareas de consulta.
jobs.getQueryResults
puede devolver 20 MB de datos, a menos que se solicite explícitamente más a través del equipo de Asistencia.
Una página es un subconjunto del número total de filas. Si los resultados ocupan más de una página de datos, los datos de los resultados tienen una propiedad pageToken
. Para obtener la siguiente página de resultados, haz otra llamada list
e incluye el valor del token como un parámetro de URL llamado pageToken
.
El método tabledata.list
, que se usa para paginar los datos de una tabla, utiliza un valor de desplazamiento de fila o un token de página. Para obtener más información, consulta Navegar por los datos de una tabla.
Iterar los resultados de las bibliotecas de cliente
Las bibliotecas de cliente en la nube gestionan los detalles de bajo nivel de la paginación de la API y proporcionan una experiencia más parecida a un iterador que simplifica la interacción con los elementos individuales de las respuestas de las páginas.
En los siguientes ejemplos se muestra cómo paginar los datos de una tabla de BigQuery.
C#
Antes de probar este ejemplo, sigue las C#instrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API C# de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Java
Antes de probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Go
Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Las bibliotecas de cliente de Cloud para Go paginan automáticamente de forma predeterminada, por lo que no es necesario que implementes la paginación por tu cuenta. Por ejemplo:
Node.js
Antes de probar este ejemplo, sigue las Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Las bibliotecas de cliente de Cloud para Node.js paginan automáticamente de forma predeterminada, por lo que no es necesario que implementes la paginación por tu cuenta. Por ejemplo:
PHP
Antes de probar este ejemplo, sigue las PHPinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API PHP de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
La paginación se realiza automáticamente en las bibliotecas de cliente de Cloud para PHP
mediante la función de generador rows
, que obtiene la página siguiente de
resultados durante la iteración.
Python
Antes de probar este ejemplo, sigue las Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Las bibliotecas de cliente de Cloud para Python paginan automáticamente de forma predeterminada, por lo que no es necesario que implementes la paginación por tu cuenta. Por ejemplo:
Ruby
Antes de probar este ejemplo, sigue las Rubyinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Ruby de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
La paginación se realiza automáticamente en las bibliotecas de cliente de Cloud para Ruby mediante Table#data
y Data#next
.
Solicitar páginas arbitrarias y evitar llamadas de lista redundantes
Cuando te desplazas hacia atrás o vas a páginas concretas mediante valores pageToken
en caché, es posible que los datos de las páginas hayan cambiado desde la última vez que se vieron, pero no hay ninguna indicación clara de que los datos puedan haber cambiado. Para evitarlo, puedes usar la propiedad etag
.
Todos los métodos collection.list
(excepto Tabledata) devuelven una propiedad etag
en el resultado. Esta propiedad es un hash de los resultados de la página que se puede usar para verificar si la página ha cambiado desde la última solicitud. Cuando envías una solicitud a BigQuery con un valor de ETag, BigQuery compara el valor de ETag con el valor de ETag devuelto por la API y responde en función de si los valores de ETag coinciden. Puede usar ETags
para evitar llamadas de lista redundantes de la siguiente manera:
Para devolver los valores de la lista si han cambiado.
Si solo quiere devolver una página de valores de lista si los valores han cambiado, puede hacer una llamada de lista con un ETag almacenado anteriormente mediante el encabezado HTTP "if-none-match". Si el ETag que proporcionas no coincide con el ETag del servidor, BigQuery devuelve una página con nuevos valores de lista. Si las etiquetas ETag coinciden, BigQuery devuelve el código de estado
HTTP 304 Not Modified
y ningún valor. Por ejemplo, una página web en la que los usuarios pueden rellenar periódicamente información que se almacena en BigQuery. Si no hay cambios en tus datos, puedes evitar hacer llamadas de lista redundantes a BigQuery usando el encabezado if-none-match con ETags.Para devolver los valores de la lista si no han cambiado.
Si solo quiere devolver una página de valores de lista si estos no han cambiado, puede usar el encabezado HTTP "if-match". BigQuery compara los valores de ETag y devuelve la página de resultados si estos no han cambiado o devuelve un resultado 412 "Precondition Failed" si la página ha cambiado.
Paginación a través de los resultados de consultas
Cada consulta escribe en una tabla de destino. Si no se proporciona ninguna tabla de destino, la API de BigQuery rellena automáticamente la propiedad de la tabla de destino con una referencia a una tabla anónima temporal.
API
Lee el campo jobs.config.query.destinationTable
para determinar la tabla en la que se han escrito los resultados de la consulta.
Llama a tabledata.list
para leer los resultados de la consulta.
Java
Antes de probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Para definir el número de filas que se devuelven en cada página, usa un GetQueryResults
trabajo y define la opción pageSize
del QueryResultsOption
objeto que envías, 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 Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Python
El método QueryJob.result
devuelve un iterable de los resultados de la consulta. También puedes
- Lee la propiedad
QueryJob.destination
. Si esta propiedad no se configura, la API le asigna 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 Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.