Paging Cumulocity IoT queries
Queries support paging when requesting multiple responses from Cumulocity IoT. The number of objects requested by queries are controlled using the following query parameters: pageSize and currentPage.
pageSize represents a batching parameter for getting multiple responses from Cumulocity IoT. A larger
pageSize does fewer requests to Cumulocity IoT to retrieve all the objects, but each request is larger. By default,
pageSize is set to 1000. There is an upper limit of 2000.
currentPage can be set to retrieve a specific page of results for a given
pageSize. If you set
currentPage, then only a single page is requested. If
currentPage is not set (default), all the pages are requested.
Note:
It is not recommended to set a small pageSize unless you are requesting a single page. To do this, you must set currentPage. Set currentPage to 1 to retrieve the first pageSize results. A warning is logged if pageSize is below 50 and currentPage is not set.
For more details on query result paging and the above query parameters, see the information on the REST implementation in the
Cumulocity IoT - API Specifications at
https://cumulocity.com/api/.
Examples
The following example shows a FindEvent query where the first 50 events are requested:
// Example 1: A FindEvent query where the first 50 responses are requested.
com.apama.cumulocity.FindEvent request := new com.apama.cumulocity.FindEvent;
// ... adding other query params ...
request.params.add("pageSize", "50");
request.params.add("currentPage", "1");
send request to com.apama.cumulocity.FindEvent.CHANNEL;
The next two examples demonstrate how to request a range of events where we are not just interested in the first page of results.
In the second example, pageSize is also set to 50, but currentPage is set to 3, thus requesting the 101st to 150th events:
// Example 2: A FindEvent query where the 101st-150th responses are requested
com.apama.cumulocity.FindEvent request := new com.apama.cumulocity.FindEvent;
//... adding other query params ...
request.params.add("pageSize", "50");
request.params.add("currentPage", "3");
send request to com.apama.cumulocity.FindEvent.CHANNEL;
As a general rule, if currentPage is greater than 1 and the number of objects you require is not a factor of the start of the range (or if the number of responses required is greater than the upper limit of pageSize), multiple requests are needed to retrieve the objects of interest. As the second example above retrieves 50 events starting after the 100th response (and as 50 is a factor of 100), only 1 request is required.
The third example illustrates a situation where multiple queries are required. 40 events are to be retrieved, starting after the 60th response. As 40 is not a factor of 60, you should set pageSize to 20 (the largest common factor of 60 and 40) and send two requests: one where currentPage is set to 4 (this retrieves the 61st-80th events), and another where currentPage is set to 5 (this retrieves the 81st-100th events).
// Example 3: Two FindEvent queries retrieving the 61st-100th events
// First request retrieves 61st-80th events
com.apama.cumulocity.FindEvent request1 := new com.apama.cumulocity.FindEvent;
// ... adding other query params ....
request1.params.add("pageSize", "20");
request1.params.add("currentPage", "4");
send request1 to com.apama.cumulocity.FindEvent.CHANNEL;
// Second request retrieves 81st-100th events
com.apama.cumulocity.FindEvent request2 := new com.apama.cumulocity.FindEvent;
// ... adding other query params ....
request2.params.add("pageSize", "20");
request2.params.add("currentPage", "5");
send request2 to com.apama.cumulocity.FindEvent.CHANNEL;