Search API - Page Selection Component

[bidoubiwa]

🤖 API Diff

---

Summary

This specification introduces a new pagination system as an alternative to the offset/limit. This pagination component can be used to navigate search results via a page selection.

---

Changes

Previously, the only way to paginate over the search results was by using limit and offset which returned both these fields an estimatedTotalHits.
This feature introduces two new query parameters page and hitsPerPage that lets you paginate over pages more easily. They add 4 new response fields: page, hitsPerPage, totalPages and totalHits.

When one system is used, only the fields of that pagination system are present in the response object.
When multiple fields from different pagination system are used, the offset/limit system is used.

Telemetry:

• Add pagination.most_used_navigation property for Documents Searched POST and Documents Searched GET events

---

Attention To Reviewers

Corner cases may lack in precision.

---

Misc

• Update OpenAPI specification file
• Update telemetry datapoints

[github-actions]

🤖 API change detected:

Modified (2)

• GET /indexes/{indexUid}/search
  • Query parameters added: page, hitsPerPage
  • Response modified: 200
    • Attributes added: page, hitsPerPage, totalHits, totalPages
    • Attributes modified: offset, limit, estimatedTotalHits
• POST /indexes/{indexUid}/search
  • Body modified
    • Attributes added: page, hitsPerPage
  • Response modified: 200
    • Attributes added: page, hitsPerPage, totalHits, totalPages
    • Attributes modified: offset, limit, estimatedTotalHits

View documentation diff

Powered by Bump

[bidoubiwa]

Is this considered breaking change?

[gmourier]

I don't think so because enabling page selection is opt-in and does not change the current behavior (< v0.30) if not used.

[ManyTheFish]

I suggested some small changes that can be ignored.
More generally, I feel that there are too many explanations and examples for a specification.
However, these details could be interesting in the documentation.

Approved!

[gmourier]

@ManyTheFish I've updated the pagination.finite_pagination prototype's property. See 416429c

Since search events are aggregated, it's preferable to know which method was mostly used between exhaustive and estimated, rather than having a boolean set to true as soon one search request used the exhaustive navigation.

[gmourier]

Super minor changes