Stay organized with collections Save and categorize content based on your preferences.
When a query call completes normally, it returns the result as a SearchResults object. The results object tells you how many matching documents were found in the index, and how many matched documents were returned. It also includes a list of matching ScoredDocuments. The list usually contains a portion of all the matching documents found, since search returns a limited number of documents each time it's called. By using an offset or a cursor you can retrieve all the matching documents, a subset at a time.
Depending on the value of the limit query option, the number of matching documents returned in the result may be less than the number found. Remember that the number found will be an estimate if the number found accuracy is less than the number found. No matter how you configure the search options, a search() call will find no more than 10,000 matching documents.
If more documents were found than returned, and you want to retrieve all of them, you need to repeat the search using either an offset or a cursor, as explained below.
Note: Your calling code should be prepared to handle exceptions which might be thrown if the query is invalid or there were problems processing it. Scored documentsThe search results will include a list of ScoredDocuments that match the query. You can iterate over the list to process each document in turn:
By default, a scored document contains all the fields of the original document that was indexed. If your query options specified returned_fields, only those fields appear in the fields property of the document. If you created any computed fields by specifying returned_expressions or snippeted_fields they will appear separately in the expressions property of the document.
If your search finds more documents than you can return at once, use an offset to index into the list of matching documents. For example, the default query limit is 20 documents. After you've executed a search the first time (with offset 0) and retrieved the first 20 documents, retrieve the next 20 documents by setting the offset to 20 and running the same search again. Keep repeating the search, incrementing the offset each time by the number of documents returned:
Offsets can be inefficient when iterating over a very large result set.
Using cursorsYou can also use cursors to retrieve a subrange of results. Cursors are useful when you intend to present your search results in consecutive pages and you want to be sure you do not skip any documents in the case where an index could be modified between queries. Cursors are also more efficient when iterating across a very large result set.
In order to use cursors, you must create an initial cursor and include it in the query options. There are two kinds of cursors, per-query and per-result. A per-query cursor causes a separate cursor to be associated with the results object returned by the search call. A per-result cursor causes a cursor to be associated with every scored document in the results.
Using a per-query cursorBy default, a newly constructed cursor is a per-query cursor. This cursor holds the position of the last document returned in the search's results. It is updated with each search. To enumerate all matching documents in an index, execute the same search until the result returns a null cursor:
Using a per-result cursorTo create per-result cursors, you must set the cursor per_result property to true when you create the initial cursor. When the search returns, every document will have a cursor associated with it. You can use that cursor to specify a new search with results that begin with a specific document. Note that when you pass a per-result cursor to search, there will be no per-query cursor associated with the result itself; result.getCursor() will return null so you can't use this to test whether you've retrieved all the matches.
Saving and restoring cursorsA cursor can be serialized as a web-safe string, saved, and then restored for later use:
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-07 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["A completed query returns a `SearchResults` object, detailing the total matching documents and the number returned, including a list of `ScoredDocuments`."],["The number of documents returned might be less than the total found, as searches return a limited number, but all can be retrieved using offsets or cursors."],["`ScoredDocuments` include fields from the original indexed document and any specified computed fields from the query options."],["Offsets allow iterating through matching documents by specifying a starting point, while cursors offer a more efficient way to retrieve results across consecutive pages without missing documents."],["Cursors can be per-query or per-result, with per-query holding the position of the last returned document, and per-result associating a cursor with each document; these cursors can be serialized and restored using web-safe strings."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4