next #

Returns a smart pointer to a new SearchResult object containing the next batch of search results.

Arguments #

std::shared_ptr<kuzzleio::SearchResult> next() const;

Behavior of the next method #

In order to be able to compute the next search page, some initial conditions must be met.

Depending on the arguments given to the initial search, the next method will pick one of the following policies, by decreasing order of priority (i.e. a search including a scroll, sort and size will use the scroll policy).

If no policy is applicable, the next method throws an exception.

Usage with scroll #

This is the preferred way to get paginated results.

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

The results that are returned from a scroll request reflect the state of the index at the time the initial search request was performed, like a persistent snapshot.

As such, even if some documents are added or deleted from the database between two calls to next, the result is guaranteed to include all items matching the query at the time the initial search was sent and to not get any duplicate between two search pages.

try {
  for (size_t i = 0; i < 10; i++) {
    kuzzle->document->create("nyc-open-data", "yellow-taxi", "", R"({
      "category": "suv"
    })");
  }
  // Waits documents to be indexed
  kuzzle->index->refresh("nyc-open-data");
  kuzzleio::query_options options = {};
  options.scroll = "1m";
  options.size = 5;
  // Retrieve the first 5 documents
  std::shared_ptr<kuzzleio::SearchResult> results = kuzzle->document->search(
    "nyc-open-data",
    "yellow-taxi",
    R"({
      "query": {
        "match": {
          "category": "suv"
        }
      }
    })",
    options);
  // Retrieve the next 5 documents
  std::shared_ptr<kuzzleio::SearchResult> next_results = results->next();
  std::cout
    << "Successfully retrieved "
    << next_results->fetched()
    << " documents"
    << std::endl;
} catch (kuzzleio::KuzzleException& e) {
  std::cerr << e.what() << std::endl;
}

Usage with sort / size #

If the initial search is given sort and size parameters, the next method will retrieve the next items matching the sort.

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 research between two calls, if updates are applied to the database between two calls, it is possible to miss documents and/or to get duplicates between search pages.

Usage with from / size #

If the initial search is given from and size parameters, the next method will increment the from parameter to retrieve the next results.

Because this method does not freeze the research between two calls, if updates are applied to the database between two calls, it is possible to miss documents and/or to get duplicates between search pages.

try {
  for (size_t i = 0; i < 10; i++) {
    kuzzle->document->create("nyc-open-data", "yellow-taxi", "", R"({
      "category": "suv"
    })");
  }
  // Waits documents to be indexed
  kuzzle->index->refresh("nyc-open-data");
  kuzzleio::query_options options = {};
  options.from = 1;
  options.size = 5;
  // Retrieve the first 5 documents
  std::shared_ptr<kuzzleio::SearchResult> results = kuzzle->document->search(
    "nyc-open-data",
    "yellow-taxi",
    R"({
      "query": {
        "match": {
          "category": "suv"
        }
      }
    })",
    options);
  // Retrieve the next 5 documents
  std::shared_ptr<kuzzleio::SearchResult> next_results = results->next();
  std::cout
    << "Successfully retrieved "
    << next_results->fetched()
    << " documents"
    << std::endl;
} catch (kuzzleio::KuzzleException& e) {
  std::cerr << e.what() << std::endl;
}

Return #

A smart pointer to a new SearchResult containing the next results of the search.