RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://cloud.google.com/appengine/docs/legacy/standard/java/datastore/query-cursors below:

Query Cursors | App Engine standard environment for Java 8

Stay organized with collections Save and categorize content based on your preferences.

This API is supported for first-generation runtimes and can be used when upgrading to corresponding second-generation runtimes. If you are updating to the App Engine Java 11/17 runtime, refer to the migration guide to learn about your migration options for legacy bundled services.

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

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 GET or 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 the low-level API, the application can use cursors via the QueryResultList, QueryResultIterable, and QueryResultIterator interfaces, which are returned by the PreparedQuery methods asQueryResultList(), asQueryResultIterable(), and asQueryResultIterator(), respectively. Each of these result objects provides a getCursor() method, which in turn returns a Cursor object. The application can get a web-safe string representing the cursor by calling the Cursor object's toWebSafeString() method, and can later use the static method Cursor.fromWebSafeString() to reconstitute the cursor from the string.

The following example demonstrates the use of cursors for pagination:

Caution: Be careful when passing a Datastore cursor to a client, such as in a web form. Although the client cannot change the cursor value to access results outside of the original query, it is possible for it to decode the cursor to expose information about result entities, such as the application ID, entity kind, key name or numeric ID, ancestor keys, and properties used in the query's filters and sort orders. If you don't want users to have access to that information, you can encrypt the cursor, or store it and provide the user with an opaque key. 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 NOT_EQUAL and IN operators are implemented with multiple queries, queries that use them do not support cursors, nor do composite queries constructed with the CompositeFilterOperator.or method.
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 raises an IllegalArgumentException (low-level API), JDOFatalUserException (JDO), or PersistenceException (JPA).

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.

What's next?

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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-08-07 UTC.

[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["This API supports first-generation runtimes and can be used when upgrading to corresponding second-generation runtimes, with a migration guide available for App Engine Java 11/17 users."],["Query cursors are recommended over integer offsets for pagination, allowing applications to retrieve query results in batches without the overhead of a query offset."],["Cursors are opaque base64-encoded strings marking the index position of the last retrieved result, enabling applications to save and use them for subsequent retrievals."],["Unlike offsets, using cursors avoids the cost of retrieving and processing skipped entities, as these entities are still retrieved internally when offsets are used."],["Cursors have limitations, including the requirement to use the exact same query, restrictions with certain operators, and potential invalidation due to App Engine updates, which could raise errors."]]],[]]

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4