SDK
SDK C++ v1.x
1

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

This SDK has been deprecated because of stability issues. It is not advised to use it in a production environment.

next #

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

Arguments #

Copied to clipboard!
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.

When processing a large number of documents (i.e. more than 1000), it is advised to use a scroll cursor (see the scroll search option).

It is also the only method that guarantees that all matching documents will be retrieved, without duplicates.

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.

Copied to clipboard!
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.

It is not possible to retrieve more than 10000 items using this method. Beyond that limit, any call to next will throw an Exception.

Copied to clipboard!
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.