firestore: paginate data with query cursors

Paginate Data with Query Cursors

With query cursors in Cloud Firestore, you can split data returned by a query into batches according to the parameters you define in your query.

Query cursors define the start and end points for a query, allowing you to:

• Return a subset of the data.
• Paginate query results.

However, to define a specific range for a query, you should use the where() method described in Simple Queries.

Add a simple cursor to a query

Use the startAt() or startAfter() methods to define the start point for a query. The startAt()method includes the start point, while the startAfter() method excludes it.

For example, if you use startAt(A) in a query, it returns the entire alphabet. If you use startAfter(A) instead, it returns B-Z.

WEB

SWIFT

OBJECTIVE-C

ANDROID

JAVA

PYTHON

MORE

// Get all cities with population over one million, ordered by population.
[[[ db collectionWithPath :@ "cities" ]
    queryOrderedByField :@ "population" ]
    queryStartingAtValues :@[ @ 1000000 ]];

ViewController.m

 

Similarly, use the endAt() or endBefore() methods to define an end point for your query results.

WEB

SWIFT

OBJECTIVE-C

ANDROID

JAVA

PYTHON

MORE

// Get all cities with population less than one million, ordered by population.
[[[ db collectionWithPath :@ "cities" ]
    queryOrderedByField :@ "population" ]
    queryEndingAtValues :@[ @ 1000000 ]];

ViewController.m

 

Use a document snapshot to define the query cursor

You can also pass a document snapshot to the cursor clause as the start or end point of the query cursor. The values in the document snapshot serve as the values in the query cursor.

For example, take a snapshot of a "San Francisco" document in your data set of cities and populations. Then, use that document snapshot as the start point for your population query cursor. Your query will return all the cities with a population larger than or equal to San Francisco's, as defined in the document snapshot.

WEB

SWIFT

OBJECTIVE-C

ANDROID

JAVA

PYTHON

MORE

[[[ db collectionWithPath :@ "cities" ] documentWithPath :@ "SF" ]
    addSnapshotListener :^( FIRDocumentSnapshot * snapshot , NSError * error ) {
      if ( snapshot == nil ) {
        NSLog (@ "Error retreiving cities: %@" , error );
        return ;
      }
      // Get all cities with a population greater than or equal to San Francisco.
      FIRQuery * sfSizeOrBigger = [[[ db collectionWithPath :@ "cities" ]
          queryOrderedByField :@ "population" ]
          queryStartingAtDocument : snapshot ];
    }];

ViewController.m

 

Paginate a query

Paginate queries by combining query cursors with the limit() method. For example, use the last document in a batch as the start of a cursor for the next batch.

WEB

SWIFT

OBJECTIVE-C

ANDROID

JAVA

PYTHON

MORE

FIRQuery * first = [[[ db collectionWithPath :@ "cities" ]
    queryOrderedByField :@ "population" ]
    queryLimitedTo : 25 ];
[ first addSnapshotListener :^( FIRQuerySnapshot * snapshot , NSError * error ) {
  if ( snapshot == nil ) {
    NSLog (@ "Error retreiving cities: %@" , error );
    return ;
  }
  if ( snapshot . documents . count == 0 ) { return ; }
  FIRDocumentSnapshot * lastSnapshot = snapshot . documents . lastObject ;

  // Construct a new query starting after this document,
  // retreiving the next 25 cities.
  FIRQuery * next = [[[ db collectionWithPath :@ "cities" ]
      queryOrderedByField :@ "population" ]
      queryStartingAfterDocument : lastSnapshot ];
  // Use the query for pagination.
  // ...
}];

ViewController.m

 

Set multiple cursor conditions

To add more granularity to your cursor's start or end point, you can specify multiple conditions in the cursor clause. This is particularly useful if your data set includes fields where the first condition in a cursor clause would return multiple results. Use multiple conditions to further specify the start or end point and reduce ambiguity.

For example, in a data set containing all the cities named "Springfield" in the United States, there would be multiple start points for a query set to start at "Springfield":

Cities
Name	State
Springfield	Massachusetts
Springfield	Missouri
Springfield	Wisconsin

To start at a specific Springfield, you could add the state as a secondary condition in your cursor clause.

WEB

SWIFT

OBJECTIVE-C

ANDROID

JAVA

PYTHON

MORE

// Will return all Springfields
[[[[ db collectionWithPath :@ "cities" ]
    queryOrderedByField :@ "name" ]
    queryOrderedByField :@ "state" ]
    queryStartingAtValues :@[ @ "Springfield" ]];
// Will return "Springfield, Missouri" and "Springfield, Wisconsin"
[[[[ db collectionWithPath :@ "cities" ]
   queryOrderedByField :@ "name" ]
   queryOrderedByField :@ "state" ]
   queryStartingAtValues :@[ @ "Springfield" , @ "Missouri" ]];

ViewController.m