Paginate results in InstantSearch Android
On this page
Pagination gives you complete control over how you retrieve query results. You can implement standard paging or retrieve specific record subsets that ignore page boundaries.
You can set pagination defaults at indexing time and override them at query time.
Pagination at indexing time
At indexing time, you can set up two defaults:
hitsPerPage
- the number of hits returned for every pagepaginationLimitedTo
- controls the number of hits you can retrieve for a given query
Pagination at query time
- You can retrieve a specific page by using the
page
parameter - You can specify specific record subsets by using the
offset
andlength
parameters - You can override the default for
hitsPerPage
Response details
To help paginate results, Algolia provides information about the current state of the pagination in the JSON response.
1
2
3
4
5
6
7
8
{
[...],
"page": 0,
"nbHits": 40,
"nbPages": 2,
"hitsPerPage": 20,
"exhaustiveNbHits": true
}
page
returns the current page (this value starts at 0)hitsPerPage
returns the maximum number of hits returned for each pagenbPages
returns the number of pages available for the current querynbHits
returns the number of hits that the search query matchedexhaustiveNbHits
returns a boolean indicating if the nbHits count was exhaustive or approximateexhaustiveTypo
returns a boolean indicating if the typo-tolerance search was exhaustive or approximate (only included when typo-tolerance is enabled)
Exhaustive hits
Usually, Algolia returns an accurate number of total hits.
However, if a query returns many hits, Algolia approximates the count to avoid scanning all of your index.
This approximation protects other search and indexing operations.
If your API response includes the exhaustive.nbHits
parameter,
the number of hits is approximate.
Retrieving specific pages
At query time, you can pass in the page
parameter to access a specific results page. 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 overridden as an index setting or as a query parameter.
1
2
3
4
5
6
index.search('query', {
page: 2,
hitsPerPage: 5
}).then(({ hits }) => {
console.log(hits);
});
Pagination limitations
Default number of hits per query
By default, Algolia limits the maximum number of hits retrieved from a paginated query to 20,000. This restriction ensures optimal performance and hinders third parties from extracting your data. Usually, the default of 1,000 hits is more than enough.
Overriding the default limits
To retrieve more hits (for example, for an ecommerce category page or an infinite scroll experience), you can raise the default pagination limit:
1
2
3
index.setSettings({
paginationLimitedTo: 5000
});
Increasing the pagination limit might decrease performance. Only set this number as large as necessary.
Paging beyond the limit
If you send a request for a page that doesn’t exist or is out-of-range, that is, when page >= nbPages
, Algolia doesn’t return an error. Instead, it returns 0 results.
Retrieving a subset of records (with offset and length)
In most cases, you only need page
and hitsPerPage
to add pagination.
However, if you want to insert items, such as ads, into the results without affecting pagination, use the offset
and length
parameters. They allow you to specify the records to retrieve, not the page.
The offset
parameter lets you specify the starting record, and length
sets the number of records returned. For example, if you have 100 records in your result set, broken down into 10 pages (hitsPerPage=10
), you can retrieve subsets as follows (offset
is zero-based):
- Records 50 to 80 (
offset=49
andlength = 30
). - Records 21 to 25 (
offset=20
andlength = 5
).
With the InstantSearch UI libraries, you can only use page
and hitsPerPage
to implement pagination.