pageBy<T> abstract method Null safety

Configures this instance to fetch a section of a larger result set.

This method provides an effective mechanism for paging a result set by ordering rows by some property, offsetting into that ordered set and returning rows starting from that offset. The fetchLimit of this instance must also be configured to limit the size of the page.

The property that determines order is identified by propertyIdentifier. This closure must return a property of of InstanceType. The order is determined by order. When fetching the 'first' page of results, no value is passed for boundingValue. As later pages are fetched, the value of the paging property for the last returned object in the previous result set is used as boundingValue. For example:

    var recentHireQuery = Query<Employee>()
      ..pageBy((e) => e.hireDate, QuerySortOrder.descending);
    var recentHires = await recentHireQuery.fetch();

    var nextRecentHireQuery = Query<Employee>()
      ..pageBy((e) => e.hireDate, QuerySortOrder.descending,
        boundingValue: recentHires.last.hireDate);

Note that internally, pageBy adds a matcher to where and adds a high-priority sortBy. Adding multiple pageBys to an instance has undefined behavior.