The Cursor
class provides a cursor in the current set search results, allowing you to retrieve the next set based on criteria that you specify. Using cursors improves the performance and consistency of pagination as indexes are updated.
The following shows how to use the cursor to get the next page of results:
# Get the first set of results, and return a cursor with that result set. # The first cursor tells the API to return cursors in the SearchResults object. results = index.search(search.Query(query_string='some stuff', options=search.QueryOptions(cursor=search.Cursor())) # Get the next set of results with a cursor. results = index.search(search.Query(query_string='some stuff', options=search.QueryOptions(cursor=results.cursor)))
If you want to continue search from any one of the ScoredDocuments
in SearchResults
, set Cursor.per_result
to True
:
# get the first set of results, the first cursor is used to specify # that cursors are to be returned in the SearchResults. results = index.search(search.Query(query_string='some stuff', options=search.QueryOptions(cursor=Cursor(per_result=True))) # this shows how to access the per_document cursors returned from a search per_document_cursor = None for scored_document in results: per_document_cursor = scored_document.cursor # get the next set of results results = index.search(search.Query(query_string='some stuff', options=search.QueryOptions(cursor=per_document_cursor)))
The cursor can be cached as a web safe string that can be used to reconstruct the Cursor. For example,
next_cursor = results.cursor next_cursor_url_safe = next_cursor.web_safe_string // save next_cursor_url_safe ... // extract next_cursor_url_safe results = index.search( search.Query(query_string, cursor=search.Cursor(web_safe_string=next_cursor_url_safe)))
Constructor
The constructor for class Cursor
is defined as follows:
-
class Cursor(web_safe_string=None, per_result=False)
Construct an instance of class
Cursor
.Arguments
- per_result
When true, returns a cursor per ScoredDocument in SearchResults. When false, returns a single cursor for all of SearchResults. Ignored if using
QueryOptions.offset
, as the user is responsible for calculating a next offset (if any).- web_safe_string
The cursor string returned from the search service to be interpreted by the search service to get the next set of results.
Result value
A new instance of class
Cursor
.
Exceptions
- ValueError
If the
web_safe_string
provided by the API is not of required format.
Properties
An instance of class Cursor
has the following properties:
- per_result
Returns whether to return a cursor for each ScoredDocument in results.
- web_safe_string
Returns the cursor string generated by the search service.