Cursores de consulta

Los cursores de consulta permiten que una aplicación recupere los resultados de una consulta en lotes prácticos, y se recomienda usarlos en lugar de desplazamientos de números enteros para la paginación. Si deseas obtener más información sobre la estructuración de consultas para tu app, revisa Consultas.

Cursores de consulta

Los cursores de consulta permiten que una aplicación recupere los resultados de una consulta en lotes prácticos sin la sobrecarga de un desplazamiento de consulta. Después de realizar una operación de recuperación, la aplicación puede obtener un cursor, que es una string opaca codificada en base64 que marca la posición en el índice del último resultado recuperado. La aplicación puede guardar esta string, por ejemplo, en Datastore, en Memcache, en una carga útil de tareas de la lista de tareas en cola o incorporada en una página web como un parámetro HTTP GET o POST y, luego, usar el cursor como punto de partida para una operación de recuperación posterior a fin de obtener el siguiente lote de resultados desde el punto en que finalizó la recuperación anterior. En una recuperación, también se puede especificar un cursor de fin para limitar la extensión del conjunto de resultados mostrado.

Desplazamientos frente a cursores

Si bien Datastore admite desplazamientos de números enteros, no es recomendable usarlos. En su lugar, usa cursores. Usar un desplazamiento solo evita que se muestren las entidades omitidas en la aplicación, pero se siguen recuperando internamente. Las entidades omitidas afectan a la latencia de la consulta y tu aplicación se factura por las operaciones de lectura necesarias para recuperarlas. Usar cursores en lugar de desplazamientos te permite evitar todos estos costos.

Ejemplo de cursor de consulta

En Python, una aplicación obtiene un cursor después de recuperar resultados de consultas mediante una llamada al método cursor() del objeto Query. Para recuperar resultados adicionales desde el punto del cursor, la aplicación prepara una consulta similar con los mismos filtros, órdenes de clasificación y tipo de entidad, y pasa el cursor al método with_cursor() de la consulta antes de realizar la recuperación:

from google.appengine.api import memcache
from google.appengine.ext import db

# class Person(db.Model): ...
    
# Start a query for all Person entities
people = Person.all()
    
# If the application stored a cursor during a previous request, use it
person_cursor = memcache.get('person_cursor')
if person_cursor:
  people.with_cursor(start_cursor=person_cursor)
    
# Iterate over the results
for person in people:
  # Do something
    
# Get updated cursor and store it for next time
person_cursor = people.cursor()
memcache.set('person_cursor', person_cursor)

Limitaciones de los cursores

Los cursores están sujetos a las siguientes limitaciones:

  • Un cursor solo puede usarse en la misma aplicación que realizó la consulta original y solo para continuar la misma consulta. Para usar el cursor en una operación de recuperación posterior, debes reconstituir la consulta original exactamente, incluidos el mismo de tipo de entidad, filtro de principal, filtros de propiedades y órdenes de clasificación. No es posible recuperar resultados mediante un cursor sin configurar la misma consulta desde la que se generó.
  • Debido a que los operadores != y IN se implementan con varias consultas, aquellas que los usan no admiten cursores.
  • Los cursores no siempre se comportan de la forma esperada con una consulta que usa un filtro de desigualdad o un orden de clasificación en una propiedad con varios valores. La lógica de deduplicación para esas propiedades con varios valores no persiste entre las recuperaciones, lo que, posiblemente, hará que el mismo resultado se muestre más de una vez.
  • Las versiones nuevas de App Engine podrían cambiar los detalles de la implementación interna, lo que invalida los cursores que dependen de ellos. Si una aplicación intenta usar un cursor que ya no es válido, Datastore genera una excepción BadRequestError.

Actualizaciones de datos y cursores

La posición del cursor se define como la ubicación en la lista de resultados que sigue al último resultado que se mostró. Un cursor no es una posición relativa en la lista (no es un desplazamiento), es un marcador al que puede saltar Datastore cuando se inicia un análisis de índice para obtener resultados. Si los resultados de una consulta cambian entre los usos de un cursor, la consulta notará solo los cambios que se producen en los resultados que aparecen después del cursor. Si aparece un resultado nuevo antes de la posición del cursor para la consulta, este no se mostrará cuando se recuperen los resultados que aparecen después del cursor. De igual modo, si una entidad ya no es un resultado para una consulta, pero ha aparecido antes del cursor, los resultados que aparecen después del cursor no se modifican. Si se quita el último resultado que se muestra del conjunto de resultados, el cursor aún podrá localizar el resultado siguiente.

Cuando se recuperan resultados de consulta, puedes usar un cursor de inicio y un cursor de fin para que se muestre un grupo continuo de resultados de Datastore. Cuando se usa un cursor de inicio y de fin para recuperar los resultados, no hay garantía de que el tamaño de los resultados será el mismo que cuando se generaron los cursores. Se pueden agregar o borrar entidades de Datastore desde que se generan los cursores hasta antes de que se los use en una consulta.

Próximos pasos