From 42d7c80d8ee19e5132448b11959d41ce0967b8ae Mon Sep 17 00:00:00 2001 From: Kofi Date: Tue, 14 Jan 2025 14:51:13 -0800 Subject: [PATCH 1/2] Proposed changes to match opster. Added a summary at the top to help distinguish between different methods --- .../paginate-search-results.asciidoc | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/reference/search/search-your-data/paginate-search-results.asciidoc b/docs/reference/search/search-your-data/paginate-search-results.asciidoc index f69fd60be0484..0af1ef8dc53e2 100644 --- a/docs/reference/search/search-your-data/paginate-search-results.asciidoc +++ b/docs/reference/search/search-your-data/paginate-search-results.asciidoc @@ -1,6 +1,18 @@ [[paginate-search-results]] === Paginate search results +Pagination provides a structured way for users to interact with search results by breaking them down into smaller, manageable pieces or "pages." Whether allowing users to select a specific range of pages or implementing an “infinite scroll” experience, pagination helps create a tailored and intuitive user experience. + +The three commonly used pagination techniques are: + +* <>: This method is ideal for creating a defined list of pages that users can select to navigate through the results. +* <>: Designed for seamless navigation, this technique supports “infinite scroll” experiences or enables users to load additional results by pressing a “next” button. +* <>: Historically used to retrieve all matching documents for display or export. However, we now recommend using the <> method in combination with the <> for improved efficiency and reliability. + +[discrete] +[[from-and-size-pagination]] +=== From and size pagination + By default, searches return the top 10 matching hits. To page through a larger set of results, you can use the <>'s `from` and `size` parameters. The `from` parameter defines the number of hits to skip, defaulting @@ -25,7 +37,7 @@ Avoid using `from` and `size` to page too deeply or request too many results at once. Search requests usually span multiple shards. Each shard must load its requested hits and the hits for any previous pages into memory. For deep pages or large sets of results, these operations can significantly increase memory and -CPU usage, resulting in degraded performance or node failures. +CPU usage, resulting in degraded performance or node failures. Deep pagination can be a big performance killer if not managed correctly. By default, you cannot use `from` and `size` to page through more than 10,000 hits. This limit is a safeguard set by the @@ -33,6 +45,8 @@ hits. This limit is a safeguard set by the to page through more than 10,000 hits, use the <> parameter instead. +Pagination is stateless, meaning there is no guarantee that the order of search results will remain consistent when users navigate back and forth between pages. If maintaining consistent result order is desired, the preferred approach is to use the <> to implement a stateful pagination technique. + WARNING: {es} uses Lucene's internal doc IDs as tie-breakers. These internal doc IDs can be completely different across replicas of the same data. When paging search hits, you might occasionally see that documents with the same sort values @@ -43,7 +57,7 @@ are not ordered consistently. === Search after You can use the `search_after` parameter to retrieve the next page of hits -using a set of <> from the previous page. +using a set of <> from the previous page. This approach is ideal for scenarios where users click a "next" or "load more" button, rather than selecting a specific page. Using `search_after` requires multiple search requests with the same `query` and `sort` values. The first step is to run an initial request. The following From b48e1e28dc83ed58b096c6e6934152fde630666b Mon Sep 17 00:00:00 2001 From: Kofi Date: Tue, 14 Jan 2025 15:47:13 -0800 Subject: [PATCH 2/2] rewording --- .../search/search-your-data/paginate-search-results.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/search/search-your-data/paginate-search-results.asciidoc b/docs/reference/search/search-your-data/paginate-search-results.asciidoc index 0af1ef8dc53e2..8f8a01e07043a 100644 --- a/docs/reference/search/search-your-data/paginate-search-results.asciidoc +++ b/docs/reference/search/search-your-data/paginate-search-results.asciidoc @@ -37,7 +37,7 @@ Avoid using `from` and `size` to page too deeply or request too many results at once. Search requests usually span multiple shards. Each shard must load its requested hits and the hits for any previous pages into memory. For deep pages or large sets of results, these operations can significantly increase memory and -CPU usage, resulting in degraded performance or node failures. Deep pagination can be a big performance killer if not managed correctly. +CPU usage, resulting in degraded performance or node failures if not managed correctly. By default, you cannot use `from` and `size` to page through more than 10,000 hits. This limit is a safeguard set by the