defquery_offset(index,query_string):offset=0whileTrue:# Build the query using the current offset.options=search.QueryOptions(offset=offset)query=search.Query(query_string=query_string,options=options)# Get the resultsresults=index.search(query)number_retrieved=len(results.results)ifnumber_retrieved==0:break# Add the number of documents found to the offset, so that the next# iteration will grab the next page of documents.offset+=number_retrieved# Process the matched documentsfordocumentinresults:print(document)
defquery_cursor(index,query_string):cursor=search.Cursor()whilecursor:# Build the query using the cursor.options=search.QueryOptions(cursor=cursor)query=search.Query(query_string=query_string,options=options)# Get the results and the next cursorresults=index.search(query)cursor=results.cursorfordocumentinresults:print(document)
defquery_per_document_cursor(index,query_string):cursor=search.Cursor(per_result=True)# Build the query using the cursor.options=search.QueryOptions(cursor=cursor)query=search.Query(query_string=query_string,options=options)# Get the results.results=index.search(query)document_cursor=Nonefordocumentinresults:# discover some document of interest and grab its cursor, for this# sample we'll just use the first document.document_cursor=document.cursorbreak# Start the next search from the document of interest.ifdocument_cursorisNone:returnoptions=search.QueryOptions(cursor=document_cursor)query=search.Query(query_string=query_string,options=options)results=index.search(query)fordocumentinresults:print(document)
保存和恢复游标
您可以将游标序列化为一个 Web 安全字符串,然后进行保护和恢复以供日后使用:
defsaving_and_restoring_cursor(cursor):# Convert the cursor to a web-safe string.cursor_string=cursor.web_safe_string# Restore the cursor from a web-safe string.cursor=search.Cursor(web_safe_string=cursor_string)
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-08-21。"],[[["\u003cp\u003eA completed query returns a \u003ccode\u003eSearchResults\u003c/code\u003e object, detailing the total matching documents and the number returned, including a list of \u003ccode\u003eScoredDocuments\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe 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.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eScoredDocuments\u003c/code\u003e include fields from the original indexed document and any specified computed fields from the query options.\u003c/p\u003e\n"],["\u003cp\u003eOffsets 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.\u003c/p\u003e\n"],["\u003cp\u003eCursors 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.\u003c/p\u003e\n"]]],[],null,["# Handling Search Results\n\nWhen a query call completes normally, it returns the result as a [`SearchResults`](/appengine/docs/legacy/standard/python/search/searchresultsclass) 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`](/appengine/docs/legacy/standard/python/search/scoreddocumentclass). 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.\n| This API is supported for first-generation runtimes and can be used when [upgrading to corresponding second-generation runtimes](/appengine/docs/standard/\n| python3\n|\n| /services/access). If you are updating to the App Engine Python 3 runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/python-differences) to learn about your migration options for legacy bundled services.\n\nResults\n-------\n\n def query_results(index, query_string):\n result = index.search(query_string)\n total_matches = result.number_found\n list_of_docs = result.results\n number_of_docs_returned = len(list_of_docs)\n return total_matches, list_of_docs, number_of_docs_returned\n\nDepending on the value of the `limit` [query option](/appengine/docs/legacy/standard/python/search/options#queryoptions), 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.\n\nIf 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.\n| **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.\n\nScored documents\n----------------\n\nThe search results will include a list of [`ScoredDocuments`](/appengine/docs/legacy/standard/python/search/scoreddocumentclass) that match the query. You can iterate over the list to process each document in turn: \n\n for scored_document in results:\n print(scored_document)\n\nBy default, a scored document contains all the fields of the original document that was indexed. If your [query options](/appengine/docs/legacy/standard/python/search/options#queryoptions) specified `returned_fields`, only those fields appear in the [fields](/appengine/docs/legacy/standard/python/search/documentclass#Document_fields) property of the document. If you created any computed fields by specifying `returned_expressions` or `snippeted_fields` they will appear\nseparately in the [expressions](/appengine/docs/legacy/standard/python/search/scoreddocumentclass#SortExpression_expressions) property of the document.\n\nUsing offsets\n-------------\n\nIf 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: \n\n def query_offset(index, query_string):\n offset = 0\n\n while True:\n # Build the query using the current offset.\n options = search.QueryOptions(offset=offset)\n query = search.Query(query_string=query_string, options=options)\n\n # Get the results\n results = index.search(query)\n\n number_retrieved = len(results.results)\n if number_retrieved == 0:\n break\n\n # Add the number of documents found to the offset, so that the next\n # iteration will grab the next page of documents.\n offset += number_retrieved\n\n # Process the matched documents\n for document in results:\n print(document)\n\nOffsets can be inefficient when iterating over a very large result set.\n\nUsing cursors\n-------------\n\nYou 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.\n\nIn 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.\n\n### Using a per-query cursor\n\nBy 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: \n\n def query_cursor(index, query_string):\n cursor = search.Cursor()\n\n while cursor:\n # Build the query using the cursor.\n options = search.QueryOptions(cursor=cursor)\n query = search.Query(query_string=query_string, options=options)\n\n # Get the results and the next cursor\n results = index.search(query)\n cursor = results.cursor\n\n for document in results:\n print(document)\n\n### Using a per-result cursor\n\nTo 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. \n\n def query_per_document_cursor(index, query_string):\n cursor = search.Cursor(per_result=True)\n\n # Build the query using the cursor.\n options = search.QueryOptions(cursor=cursor)\n query = search.Query(query_string=query_string, options=options)\n\n # Get the results.\n results = index.search(query)\n\n document_cursor = None\n for document in results:\n # discover some document of interest and grab its cursor, for this\n # sample we'll just use the first document.\n document_cursor = document.cursor\n break\n\n # Start the next search from the document of interest.\n if document_cursor is None:\n return\n\n options = search.QueryOptions(cursor=document_cursor)\n query = search.Query(query_string=query_string, options=options)\n results = index.search(query)\n\n for document in results:\n print(document)\n\n### Saving and restoring cursors\n\nA cursor can be serialized as a web-safe string, saved, and then restored for later use: \n\n def saving_and_restoring_cursor(cursor):\n # Convert the cursor to a web-safe string.\n cursor_string = cursor.web_safe_string\n # Restore the cursor from a web-safe string.\n cursor = search.Cursor(web_safe_string=cursor_string)"]]