Pagination

Pagination allows you to control the result set that comes back from Cloud CMS for any operations that produce a list of items. It is called pagination because it gives you a way to organize your record set into pages and then get those pages back, one at a time.

Pagination gives you a way to adjust the result set before it is sent over the wire (and back to you) so that you can have smaller "paged" payloads. Pagination is useful because, most of the time, unless the result set is very small, you're not going to be interested in dealing with all of the items at once.

For example, with pagination, you can do things like query for all of the users in a domain. You might be interested in presenting them on the screen. Let's imagine there are 10,000 users. Well, chances are you probably don't want to show 10,000 users on the screen all at once. Instead, maybe you'd like to only show 50 at a time. Pagination lets you tell Cloud CMS to hand back 50 starting at index 0. Or jump ahead to index 9017 and give back the next 50 (i.e. users 9017 through 9066). That way, you're only getting 50 users at a time. However, you can get back a different 50 each time, as you web application user clicks forward and back.

Specifically, pagination lets you adjust two important properties:

  • skip - how many records you'd like to skip ahead in the total result set before handing back.
  • limit - how many records in total you'd like to have sent over the wire.

Sorting

Pagination also lets you define how the record set should be sorted before it is handed back. The sorting is taken into account during query or lookup time so that the actual cursor into the underlying database is used to optimize performance.

You can sort on zero or more fields. For each field, you can choose to sort in ascending (1) or descending (-1) order. You specify this by passing a JSON object that defines this for any and all fields.

For example, the following could be used to sort users first by their name and second by a nested custom property:

{ "name": 1, "company.name": -1 }

REST API

For methods in the REST API that produce lists of items, you can pass pagination information via request parameters.

For example, the following would hand back a list of 10 principals from a domain starting at index 5 in the result set. There may 1,000 users overall, but you'd only get back 10 (numbers 5 through 14).

We can also pass sorting information along:

Driver methods

You can also pass pagination information via driver methods. Most drivers support pagination as an optional argument into methods that produce lists of objects.

Here we retrieve the same list of 10 users from a domain starting from index 5.

var domain = ...;

domain.listUsers({
    "skip": 5,
    "limit": 10
});

Here we retrieve the same list but we sort by name and company.name:

var domain = ...;

domain.listUsers({
    "skip": 5,
    "limit": 10,
    "sort": {
        "name": 1,
        "company.name": -1
    }
});

We can also perform custom queries and paginate the results:

var domain = ...;

domain.queryUsers({
    "company.name": "Assan Motors"
},{
    "skip": 5,
    "limit": 10,
    "sort": {
        "name": 1,
        "company.name": -1
    }
});