Icon searching white

Pagination

Last updated 07 November 2017

Response Information

In order to help paginate results, Algolia provides information about the current state of the pagination in the JSON response.

{
  [...],
  "page": 0,
  "nbHits": 40,
  "nbPages": 2,
  "hitsPerPage": 20,
  "exhaustiveNbHits": true
}
  • page returns the current page (note: this value is zero-based)
  • hitsPerPage returns the maximum number of hits returned for each page
  • nbPages returns the number of pages available for the current query
  • nbHits returns the number of hits that the search query matched
  • exhaustiveNbHits returns a boolean indicating if the nbHits count was exhaustive or approximate

Exhaustivity

If possible, Algolia will return the correct number of hits. However, there are some cases where performance needs to be favored over exhaustivity. If a query returns a huge number of results, the engine will approximate the hits count to avoid having to scan the full results set. The boolean exhaustiveNbHits can be leveraged to allow you to either hide or tweak the display of the hits count in this case.

Paginating Results

At query time, you can pass in the page parameter to allow you to access the nth page of results. The hitsPerPage parameter provides a way to set the default number of hits returned for each page. By default, its value is 20, however, this can be overriden either as an index setting or as a query parameter.

index.search({
  query: 'query',
  page: 2,
  hitsPerPage: 5
});

While leveraging page and hitsPerPage is best practice for adding pagination functionality, there may be some cases where it is necessary to conditionally insert items into the results (for example, ads) without impacting the pagination. To achieve this, you will need to use the offset and length parameters instead.

Pagination Limitations

1000 hit limit

By default, Algolia limits the maximum number of hits that can be retrieved via a query to 1000. This restriction is in place to not only guarantee optimal performance, but also to ensure your data cannot be easily extracted. For the vast majority of use cases, the default of 1000 hits is more than enough.

Overriding the Default Limits

In the event of a specific use case that requires being able to retrieve a higher number of hits (for example, powering an e-commerce category page or developing an infinite scroll type of experience), it is possible to raise the default pagination limit via the paginationLimitedTo index setting.

index.setSettings({
  paginationLimitedTo: 5000
});

Increasing the pagination limit may impact performance. We highly recommend setting this number only as large as is actually necessary.

Pagination Errors

If you send a request for a page that does not exist, or is out-of-range (i.e. when page > nbPages), we do not return an error. Instead, we return 0 results.

Browse

Algolia allows you to browse through all objects of an index using the Browse an index method. If you need to retrieve all the content of your index (for backup, SEO purposes or for running a script on it), we recommend leveraging browse as opposed to querying, as this method is optimized for speed. Results will be returned ranked by attributes and custom ranking. Additionally, browse supports almost all of the search parameters, meaning you can easily apply filters to retrieve a subset of results. To view code examples, see our exporting your data tutorial.

What’s next

Continue building your Algolia knowledge with these concepts:

You may also be interested in these tutorials:

© Algolia - Privacy Policy