Working with the API > How Do I... > Query a Collection > Data Paging |
When a query returns a large set of data, the results are returned in a series of pages. The client requests the next page after handling the data already received.
On large collections, performance degrades when retrieving the later pages. To avoid stress on the database server, restrict the size of data returned by the query by filtering: Retrieve only the data you actually need.
The client can indicate the number of instances to return in each page using the query parameter limit="n"
. For example:
/qcbin/api/domains/{domain}/projects/{project}/tests?limit=20
If no limit is specified in the query, the number of returned instances on each page is the value of the site parameter REST_API_PAGINATION_DEFAULT_LIMIT
. If the site parameter is not defined, the page size is 100.
If the specified limit
is greater than the maximum page size, an exception is thrown. The maximum page size can be specified by the site parameter REST_API_PAGINATION_MAX_LIMIT
. If the site parameter is not defined, the maximum page size is 2000. The requested page size can be set equal to the maximum by specifying limit=max
.
The query parameter offset
sets the first position to return from the results of the query. The default is 0, which starts the page at the first result. The syntax is offset=<offset>
.
For the returned data format, see the example in Query a Collection.
Get three defects starting at the sixth result |
Copy Code
|
---|---|
GET /qcbin/api/domains/my_domain/projects/REST/defects/?limit=3 & offset=5 HTTP/1.1
Referrer: http://my-server:8080/qcbin/doc/index3.html
Accept: application/json
Accept-Language: en-US
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)
Connection: Keep-Alive
DNT: 1
Host: my-server:8080
Cookie: JSESSIONID=1234567890; JSESSIONID=1234567890; LWSSO_COOKIE_KEY=1234567890; QCSession=1234567890; ALM_USER=1234567890; XSRF-TOKEN=1234567890
|