Paginated Results

The Query API includes methods for returning paginated results. A paginated result prevents all query results from being returned at one time, potentially exceeding system memory. It allows you to incrementally return and process query results in batches.

In the following code snippet, a PaginatedResult object is returned that is limited to the first 10 User objects.

1
2
3
 PaginatedResult<User> results =  Query.from(User.class)
                                       .select(0, 10);
 List<User> users = results.getItems();

In the previous snippet—

  • Line 1 returns a PaginatedResult with select(long offset, int limit). This method specifies the number of objects to return starting at a particular offset. If the offset were set to 5 and the limit set to 15, the method would return 15 instances starting at offset 5.

    Note that the PaginatedResult object only contains the number of objects specified in select(long offset, int limit), which is typically a subset of the total objects retrieved. For example, a query might return a total of 1,000 objects, which can be determined with the getCount method on PaginatedResult.

  • Line 3 uses the getItems() method to return the objects contained by PaginatedResult.

To iterate query results in batches, use the PaginatedResult methods hasNext() and getNextOffset(). The following snippet builds paginated results in batches of 100 objects.

1
2
3
4
5
6
7
int limit = 100;
Query<User> query = Query.from(User.class);
PaginatedResult<User> result = query.select(0, limit);
while (result.hasNext()) {
     //do something with the current batch of items referenced in the result object
     result = query.select(result.getNextOffset(), limit);
}

In the previous snippet—

  • Line 1 initializes the limit integer to 100. This variable is used to specify the number of items to place in PaginatedResult, and to calculate each successive offset.
  • Line 2 returns a Query with the retrieved User objects.
  • Line 3 returns a PaginatedResult with the first 100 User objects.
  • Lines 4–6 iterate PaginatedResult in batches of 100 items. After each batch is processed, line 6 calculates the next offset and updates PaginatedResult with the next 100 objects. Successive iterations continue until all of the objects retrieved by the query are processed.