Page data (limit, offset, total_count)

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.

Pagination enables you to: 

To paginate, use the keywords limit and offset.

Tip:

On large collections, performance degrades when retrieving the later pages. Other ways to avoid stress on the database server, include restricting the size of data returned by the query by retrieving only the data you actually need:

  • Filter the instances to be returned by using a query clause. See Query.

  • Retrieve only the fields you actually need by using a fields clause. See Select fields (fields).

Limit: Specifying the page size in the query

You can indicate the number of instances to return in each page using the query parameter.

limit has the following syntax: limit=<limit_value>

limit_value is an integer and must be greater than 0.

Exampledefects?limit=20

Caution: If the limit query parameter is less than 1 or greater than the maximum page size, an exception is thrown.

Offset: Specifying where to start a page

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.

Offset has the following syntax: offset=<offset_value>

offset_value is an integer and must be greater than or equal to 0.

Example: We have 100 defects in the system. To get 10 defects in places 40 – 49, send the following:

/defects?limit=10&offset=40

See also: