From 7530bc97c6bd3a706415e13462bae02720ca5bd7 Mon Sep 17 00:00:00 2001 From: Kofi Bartlett Date: Tue, 14 Jan 2025 17:54:02 -0800 Subject: [PATCH 1/7] Pagination page changes --- .../paginate-search-results.asciidoc | 20 ++++++++++++++++--- 1 file changed, 17 insertions(+), 3 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..b2d0dec32bdbb 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 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 @@ -629,4 +643,4 @@ GET /my-index-000001/_search?scroll=1m -------------------------------------------------- // TEST[setup:my_index_big] -For append only time-based indices, the `timestamp` field can be used safely. +For append only time-based indices, the `timestamp` field can be used safely. \ No newline at end of file From e1ee2057bfd8944cd87f04a001b58313914c11f5 Mon Sep 17 00:00:00 2001 From: Kofi B Date: Tue, 28 Jan 2025 10:39:35 -0800 Subject: [PATCH 2/7] Update docs/reference/search/search-your-data/paginate-search-results.asciidoc Co-authored-by: George Wallace --- .../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 b2d0dec32bdbb..9efa8cfc69b76 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 if not managed correctly. +CPU usage. If not properly managed, these operations can result in degraded performance or node failures. By default, you cannot use `from` and `size` to page through more than 10,000 hits. This limit is a safeguard set by the From cd95609e1244f675383f0c2cb11691bb39d8a386 Mon Sep 17 00:00:00 2001 From: Kofi B Date: Tue, 28 Jan 2025 10:39:55 -0800 Subject: [PATCH 3/7] Update docs/reference/search/search-your-data/paginate-search-results.asciidoc Co-authored-by: George Wallace --- .../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 9efa8cfc69b76..aa2a91f8e778c 100644 --- a/docs/reference/search/search-your-data/paginate-search-results.asciidoc +++ b/docs/reference/search/search-your-data/paginate-search-results.asciidoc @@ -1,7 +1,7 @@ [[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. +Pagination organizes search results into manageable pages, enhancing user interaction. Whether selecting specific page ranges or using infinite scroll, pagination offers a tailored user experience. The three commonly used pagination techniques are: From 4ece279470074b4a61a43177142f39b4d28e00f4 Mon Sep 17 00:00:00 2001 From: Kofi B Date: Tue, 28 Jan 2025 10:40:21 -0800 Subject: [PATCH 4/7] Update docs/reference/search/search-your-data/paginate-search-results.asciidoc Co-authored-by: George Wallace --- .../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 aa2a91f8e778c..2c070b4306c69 100644 --- a/docs/reference/search/search-your-data/paginate-search-results.asciidoc +++ b/docs/reference/search/search-your-data/paginate-search-results.asciidoc @@ -5,7 +5,7 @@ Pagination organizes search results into manageable pages, enhancing user intera 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. +* <>: Ideal for creating a list of pages that users can navigate. * <>: 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. From 8556206024db4e383ccd8e1bf19d2d6fe319cebd Mon Sep 17 00:00:00 2001 From: Kofi B Date: Tue, 28 Jan 2025 10:40:30 -0800 Subject: [PATCH 5/7] Update docs/reference/search/search-your-data/paginate-search-results.asciidoc Co-authored-by: George Wallace --- .../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 2c070b4306c69..7be361308c234 100644 --- a/docs/reference/search/search-your-data/paginate-search-results.asciidoc +++ b/docs/reference/search/search-your-data/paginate-search-results.asciidoc @@ -6,7 +6,7 @@ Pagination organizes search results into manageable pages, enhancing user intera The three commonly used pagination techniques are: * <>: Ideal for creating a list of pages that users can navigate. -* <>: Designed for seamless navigation, this technique supports “infinite scroll” experiences or enables users to load additional results by pressing a “next” button. +* <>: Supports infinite scroll or allows loading additional results with 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 2717324df5d75e2461fbeefbbe5a07191e93d373 Mon Sep 17 00:00:00 2001 From: Kofi B Date: Tue, 28 Jan 2025 10:40:53 -0800 Subject: [PATCH 6/7] Update docs/reference/search/search-your-data/paginate-search-results.asciidoc Co-authored-by: George Wallace --- .../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 7be361308c234..c101c822e91d3 100644 --- a/docs/reference/search/search-your-data/paginate-search-results.asciidoc +++ b/docs/reference/search/search-your-data/paginate-search-results.asciidoc @@ -7,7 +7,7 @@ The three commonly used pagination techniques are: * <>: Ideal for creating a list of pages that users can navigate. * <>: Supports infinite scroll or allows loading additional results with 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. +* <>: Historically used to retrieve all matching documents. The <> method with the <> is now recommended for better efficiency and reliability. [discrete] [[from-and-size-pagination]] From afedce6de0179c7a64cd2efa8af7c28ed42daec8 Mon Sep 17 00:00:00 2001 From: Kofi B Date: Tue, 28 Jan 2025 10:41:12 -0800 Subject: [PATCH 7/7] Update docs/reference/search/search-your-data/paginate-search-results.asciidoc Co-authored-by: George Wallace --- .../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 c101c822e91d3..bcb26d4a69ffd 100644 --- a/docs/reference/search/search-your-data/paginate-search-results.asciidoc +++ b/docs/reference/search/search-your-data/paginate-search-results.asciidoc @@ -45,7 +45,7 @@ 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. +Pagination is stateless, so search result order may change when navigating between pages. To maintain consistent order, use the <> for stateful pagination. 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