next #

Advances through the search results and returns the next page of items.

Arguments #

Copied to clipboard!

public CompletableFuture<SearchResult> next()

Returns #

Returns a SearchResult object, or null if no more pages are available.

Throw #

This method throws an exception if:

• No pagination strategy can be applied (see below)
• If invoking it would lead to more than 10 000 items being retrieved with the from/size strategy

Pagination strategies #

Depending on the arguments given to the initial search, the next method will pick one of the following strategies, by decreasing order of priority.

Strategy: scroll cursor #

If the original search query is given a scroll parameter, the next method uses a cursor to paginate results.

The results from a scroll request are frozen, and reflect the state of the index at the time the initial search request.
For that reason, this method is guaranteed to return consistent results, even if documents are updated or deleted in the database between two pages retrieval.

This is the most consistent way to paginate results, however, this comes at a higher computing cost for the server.

When using a cursor with the scroll option, Elasticsearch has to duplicate the transaction log to keep the same result during the entire scroll session.
It can lead to memory leaks if ascroll duration too great is provided, or if too many scroll sessions are open simultaneously.

Available since Kuzzle 2.2.0

You can restrict the scroll session maximum duration under the services.storage.maxScrollDuration configuration key.

Copied to clipboard!

Map<String, Object> searchQuery = new HashMap<>();
Map<String, Object> query = new HashMap<>();
Map<String, Object> match = new HashMap<>();
match.put("category", "suv");
query.put("match", match);
searchQuery.put("query", query);
SearchResult results = kuzzle.getDocumentController().search(
  "nyc-open-data",
  "yellow-taxi",
  searchQuery, "1s", 10).get();
// Fetch the matched items by advancing through the result pages
ArrayList<Map<String, Object>> matched = new ArrayList<>();
while (results != null) {
  matched.addAll(results.hits);
  results = results.next().get();
  }
/*
  { _id="suv_no1",
    _score=0.03390155,
    _source=
      { _kuzzle_info=
        { author="-1",
          updater=null,
          updatedAt=null,
          createdAt=1570093133057 },
        category="suv" } }
*/

Strategy: sort / size #

If the initial search contains sort and size parameters, the next method retrieves the next page of results following the sort order, the last item of the current page acting as a live cursor.

To avoid too many duplicates, it is advised to provide a sort combination that will always identify one item only. The recommended way is to use the field _uid which is certain to contain one unique value for each document.

Because this method does not freeze the search results between two calls, there can be missing or duplicated documents between two result pages.

This method efficiently mitigates the costs of scroll searches, but returns less consistent results: it's a middle ground, ideal for real-time search requests.

Strategy: from / size #

If the initial search contains from and size parameters, the next method retrieves the next page of result by incrementing the from offset.

Because this method does not freeze the search results between two calls, there can be missing or duplicated documents between two result pages.

It's the fastest pagination method available, but also the less consistent, and it is not possible to retrieve more than 10000 items using it.
Above that limit, any call to next throws an Exception.

Copied to clipboard!

Map<String, Object> searchQuery = new HashMap<>();
Map<String, Object> query = new HashMap<>();
Map<String, Object> match = new HashMap<>();
match.put("category", "suv");
query.put("match", match);
searchQuery.put("query", query);
SearchResult results = kuzzle.getDocumentController().search(
  "nyc-open-data",
  "yellow-taxi",
  searchQuery, 1, 5).get();
// Fetch the matched items by advancing through the result pages
ArrayList<Map<String, Object>> matched = new ArrayList<>();
while (results != null) {
  matched.addAll(results.hits);
  results = results.next().get();
  }
/*
  { _id="suv_no1",
    _score=0.03390155,
    _source=
      { _kuzzle_info=
        { author="-1",
          updater=null,
          updatedAt=null,
          createdAt=1570093133057 },
        category="suv" } }
*/

:::

Arguments #

Copied to clipboard!

public CompletableFuture<SearchResult?> next()

Returns #

Returns a SearchResult object, or null if no more pages are available.

Throw #

This method throws an exception if:

• No pagination strategy can be applied (see below)
• If invoking it would lead to more than 10 000 items being retrieved with the from/size strategy

Pagination strategies #

Depending on the arguments given to the initial search, the next method will pick one of the following strategies, by decreasing order of priority.

Strategy: scroll cursor #

If the original search query is given a scroll parameter, the next method uses a cursor to paginate results.

The results from a scroll request are frozen, and reflect the state of the index at the time the initial search request.
For that reason, this method is guaranteed to return consistent results, even if documents are updated or deleted in the database between two pages retrieval.

This is the most consistent way to paginate results, however, this comes at a higher computing cost for the server.

When using a cursor with the scroll option, Elasticsearch has to duplicate the transaction log to keep the same result during the entire scroll session.
It can lead to memory leaks if ascroll duration too great is provided, or if too many scroll sessions are open simultaneously.

Available since Kuzzle 2.2.0

You can restrict the scroll session maximum duration under the services.storage.maxScrollDuration configuration key.

Copied to clipboard!

val match: Map<String, Any?> =
HashMap<String, Any?>().apply {
  put("category", "suv")
}
val query: Map<String, Any?> =
HashMap<String, Any?>().apply {
  put("match", match)
}
val searchQuery: Map<String, Any?> =
HashMap<String, Any?>().apply {
  put("query", query)
}
var result: SearchResult? = kuzzle
  .documentController
  .search("nyc-open-data", "yellow-taxi", searchQuery, "1s", 10).get();
    // Fetch the matched items by advancing through the result pages
    val matched: ArrayList<Map<String, Any>> = ArrayList<Map<String, Any>>();
    while (result != null) {
      matched.addAll(result.hits);
      result = result.next().get();
    }
  /*
    { _id="suv_no1",
      _score=0.03390155,
      _source=
        { _kuzzle_info=
          { author="-1",
            updater=null,
            updatedAt=null,
            createdAt=1570093133057 },
          category="suv" } }
  */

Strategy: sort / size #

If the initial search contains sort and size parameters, the next method retrieves the next page of results following the sort order, the last item of the current page acting as a live cursor.

To avoid too many duplicates, it is advised to provide a sort combination that will always identify one item only. The recommended way is to use the field _uid which is certain to contain one unique value for each document.

Because this method does not freeze the search results between two calls, there can be missing or duplicated documents between two result pages.

This method efficiently mitigates the costs of scroll searches, but returns less consistent results: it's a middle ground, ideal for real-time search requests.

Strategy: from / size #

If the initial search contains from and size parameters, the next method retrieves the next page of result by incrementing the from offset.

Because this method does not freeze the search results between two calls, there can be missing or duplicated documents between two result pages.

It's the fastest pagination method available, but also the less consistent, and it is not possible to retrieve more than 10000 items using it.
Above that limit, any call to next throws an Exception.

Copied to clipboard!

val match: Map<String, Any?> =
HashMap<String, Any?>().apply {
  put("category", "suv")
}
val query: Map<String, Any?> =
HashMap<String, Any?>().apply {
  put("match", match)
}
val searchQuery: Map<String, Any?> =
HashMap<String, Any?>().apply {
  put("query", query)
}
var result: SearchResult? = kuzzle
  .documentController
  .search("nyc-open-data", "yellow-taxi", searchQuery, 5, 1).get();
// Fetch the matched items by advancing through the result pages
val matched: ArrayList<Map<String, Any>> = ArrayList<Map<String, Any>>();
while (result != null) {
  matched.addAll(result.hits);
  result = result.next().get();
}
  /*
    { _id="suv_no1",
      _score=0.03390155,
      _source=
        { _kuzzle_info=
          { author="-1",
            updater=null,
            updatedAt=null,
            createdAt=1570093133057 },
          category="suv" } }
  */

:::