Query cursors allow an application to retrieve a query's results in convenient batches, and are recommended over using integer offsets for pagination. See Queries for more information on structuring queries for your app.
Query cursors allow an application to retrieve a query's results in convenient
batches without incurring the overhead of a query offset. After performing a
retrieval operation, the application can obtain a
cursor, which is an opaque base64-encoded string marking the index position of
the last result retrieved. The application can save this string, for example in
Datastore, in Memcache, in a Task Queue task payload, or embedded in
a web page as an HTTP
POST parameter, and can then use the cursor as
the starting point for a subsequent retrieval operation to obtain the next batch
of results from the point where the previous retrieval ended. A retrieval can
also specify an end cursor, to limit the extent of the result set returned.
Offsets versus cursors
Although Datastore supports integer offsets, you should avoid using them. Instead, use cursors. Using an offset only avoids returning the skipped entities to your application, but these entities are still retrieved internally. The skipped entities do affect the latency of the query, and your application is billed for the read operations required to retrieve them. Using cursors instead of offsets lets you avoid all these costs.
Query cursor example
In Python, an application obtains a cursor after retrieving query results by
cursor() method. To
retrieve additional results from the point of the cursor, the application
prepares a similar query with the same entity kind, filters, and sort orders,
and passes the cursor to the query's
with_cursor() method before performing the
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)
Limitations of cursors
Cursors are subject to the following limitations:
- A cursor can be used only by the same application that performed the original query, and only to continue the same query. To use the cursor in a subsequent retrieval operation, you must reconstitute the original query exactly, including the same entity kind, ancestor filter, property filters, and sort orders. It is not possible to retrieve results using a cursor without setting up the same query from which it was originally generated.
- Because the
INoperators are implemented with multiple queries, queries that use them do not support cursors.
- Cursors don't always work as expected with a query that uses an inequality filter or a sort order on a property with multiple values. The de-duplication logic for such multiple-valued properties does not persist between retrievals, possibly causing the same result to be returned more than once.
- New App Engine releases might change internal implementation details,
invalidating cursors that depend on them. If an application attempts to use a
cursor that is no longer valid, Datastore
Cursors and data updates
The cursor's position is defined as the location in the result list after the last result returned. A cursor is not a relative position in the list (it's not an offset); it's a marker to which Datastore can jump when starting an index scan for results. If the results for a query change between uses of a cursor, the query notices only changes that occur in results after the cursor. If a new result appears before the cursor's position for the query, it will not be returned when the results after the cursor are fetched. Similarly, if an entity is no longer a result for a query but had appeared before the cursor, the results that appear after the cursor do not change. If the last result returned is removed from the result set, the cursor still knows how to locate the next result.
When retrieving query results, you can use both a start cursor and an end cursor to return a continuous group of results from Datastore. When using a start and end cursor to retrieve the results, you are not guaranteed that the size of the results will be the same as when you generated the cursors. Entities may be added or deleted from Datastore between the time the cursors are generated and when they are used in a query.
- Learn how to specify what a query returns and further control query results.
- Learn the common restrictions for queries on Datastore.
- Understand data consistency and how data consistency works with different types of queries on Datastore.
- Learn the basic syntax and structure of queries for Datastore.