Python 2.7 has reached end of support
and will be
deprecated
on January 31, 2026. After deprecation, you won't be able to deploy Python 2.7
applications, even if your organization previously used an organization policy to
re-enable deployments of legacy runtimes. Your existing Python
2.7 applications will continue to run and receive traffic after their
deprecation date. We recommend that
you
migrate to the latest supported version of Python.
The Query Class
Stay organized with collections
Save and categorize content based on your preferences.
Class Query represents a request on the search service to query the index.
Query is defined in the google.appengine.api.search module.
Introduction
The Query class allows you to specify a query string and other options, such as sort
order, limit, and a cursor, for a search on an index. You set these options by instantiating the
QueryOptions class to the
Query.options parameter.
For example, the following code fragment requests a search for documents where first
occurs in subject and good occurs anywhere, returning at most 20 documents, returning
a single document cursor for the results, sorting by subject in descending order, returning the
author, subject, and summary fields as well as a snippeted field content.
from google.appengine.api import search
...
results = index.search(search.Query(
# Specify the query string using the Search API's Query language.
query_string='subject:first good',
options=search.QueryOptions(
limit=20,
cursor=search.Cursor(),
sort_options=search.SortOptions(
expressions=[
search.SortExpression(expression='subject', default_value='')],
limit=1000),
returned_fields=['author', 'subject', 'summary'],
snippeted_fields=['content'])))
...
You have the option to return a cursor with each set of search results. This cursor allows you to
more easily page through search results. To get a Cursor, specify it in
QueryOptions.cursor and extract the cursor for
the next request from SearchResults.cursor.
This allows you to continue your search from the last found document, as shown below:
...
results = index.search(
search.Query(query_string='subject:first good',
options=search.QueryOptions(cursor=results.cursor)))
Constructor
The constructor for class Query is defined as follows:
-
class Query(query_string, options=None, enable_facet_discovery=False, return_facets=None, facet_options=None, facet_refinements=None)
Request the search service to query an index, specifying parameters for that query.
Arguments
- query_string
The query to match against documents in the index. A query is a boolean expression containing terms. For example, the query job tag:"very important" sent < 2011-02-28 finds documents with the term job in any field, and also contain the phrase very important in a tag field, and a sent date prior to February 28, 2011.
- options
Instantiation of the QueryOptions class with instructions for post-processing search results.
- enable_facet_discovery
Enable the discovery of the most relevant facets used by the documents that satisfy this search query
and return them.
- return_facets
An iterable of FacetRequest or basestring as facet name to
return specific facet with the result.
- facet_options
A FacetOption describing processing of facets.
- facet_refinements
An iterable of FacetRefinement objects or refinement
token strings used to filter out search results based on a facet value.
refinements for different facets will be conjunction and refinements for
the same facet will be disjunction.
Result value
A new instance of class Query.
Exceptions
- TypeError
Raised when query_string is not a string or options is not a QueryOptions object.
- ValueError
Raised when the query_string could not be parsed.
Properties
An instance of class Query has the following properties:
- query_string
Returns the query string to search in this request.
- options
Returns the QueryOptions defining post-processing of the search results.
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-25 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-25 UTC."],[[["\u003cp\u003eThe \u003ccode\u003eQuery\u003c/code\u003e class is used to define and send search requests to an index in the search service, specifying the query string and other search parameters.\u003c/p\u003e\n"],["\u003cp\u003eYou can customize search parameters like sort order, result limits, and cursors for pagination by using the \u003ccode\u003eQueryOptions\u003c/code\u003e class in conjunction with the \u003ccode\u003eQuery\u003c/code\u003e class.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003equery_string\u003c/code\u003e within the \u003ccode\u003eQuery\u003c/code\u003e object represents a boolean expression used to match documents within the index, enabling complex searches.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eQuery\u003c/code\u003e class allows for the retrieval of a cursor from \u003ccode\u003eSearchResults\u003c/code\u003e to enable efficient pagination through large result sets, allowing for continued searches.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eQuery\u003c/code\u003e constructor can handle options related to facet discovery and refinements, providing advanced filtering and analysis of search results.\u003c/p\u003e\n"]]],[],null,["# The Query Class\n\nClass `Query` represents a request on the search service to query the index.\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\n`Query` is defined in the `google.appengine.api.search` module.\n\nIntroduction\n------------\n\nThe `Query` class allows you to specify a query string and other options, such as sort\norder, limit, and a cursor, for a search on an index. You set these options by instantiating the\n[QueryOptions](/appengine/docs/legacy/standard/python/search/queryoptionsclass) class to the\n`Query.options` parameter.\n\nFor example, the following code fragment requests a search for documents where `first`\noccurs in subject and `good` occurs anywhere, returning at most 20 documents, returning\na single document cursor for the results, sorting by subject in descending order, returning the\nauthor, subject, and summary fields as well as a snippeted field content. \n\n```python\nfrom google.appengine.api import search\n\n...\nresults = index.search(search.Query(\n # Specify the query string using the Search API's /appengine/docs/legacy/standard/python/search/query_strings.\n query_string='subject:first good',\n options=search.QueryOptions(\n limit=20,\n cursor=search.Cursor(),\n sort_options=search.SortOptions(\n expressions=[\n search.SortExpression(expression='subject', default_value='')],\n limit=1000),\n returned_fields=['author', 'subject', 'summary'],\n snippeted_fields=['content'])))\n...\n```\n\nYou have the option to return a cursor with each set of search results. This cursor allows you to\nmore easily page through search results. To get a Cursor, specify it in\n[QueryOptions.cursor](/appengine/docs/legacy/standard/python/search/queryoptionsclass) and extract the cursor for\nthe next request from [SearchResults.cursor](/appengine/docs/legacy/standard/python/search/searchresultsclass).\nThis allows you to continue your search from the last found document, as shown below:\n\n```python\n...\nresults = index.search(\n search.Query(query_string='subject:first good',\n options=search.QueryOptions(cursor=results.cursor)))\n```\n\nConstructor\n-----------\n\nThe constructor for class `Query` is defined as follows:\n\n\nclass Query(query_string, options=None, enable_facet_discovery=False, return_facets=None, facet_options=None, facet_refinements=None)\n\n:\n\n Request the search service to query an index, specifying parameters for that query.\n\n \u003cbr /\u003e\n\n:\n\n Arguments\n\n query_string\n\n : The query to match against documents in the index. A query is a boolean expression containing terms. For example, the query `job tag:\"very important\" sent \u003c 2011-02-28 ` finds documents with the term `job` in any field, and also contain the phrase `very important` in a `tag` field, and a `sent` date prior to February 28, 2011.\n\n options\n\n : Instantiation of the [QueryOptions](/appengine/docs/legacy/standard/python/search/queryoptionsclass) class with instructions for post-processing search results.\n\n enable_facet_discovery\n\n : Enable the discovery of the most relevant facets used by the documents that satisfy this search query\n and return them.\n\n return_facets\n\n : An iterable of FacetRequest or basestring as facet name to\n return specific facet with the result.\n\n facet_options\n\n : A FacetOption describing processing of facets.\n\n facet_refinements\n\n : An iterable of FacetRefinement objects or refinement\n token strings used to filter out search results based on a facet value.\n refinements for different facets will be conjunction and refinements for\n the same facet will be disjunction.\n\n Result value\n\n : A new instance of class `Query`.\n\n Exceptions\n\n TypeError\n\n : Raised when `query_string` is not a string or `options` is not a `QueryOptions` object.\n\n ValueError\n\n : Raised when the `query_string` could not be parsed.\n\n Properties\n ----------\n\n An instance of class `Query` has the following properties:\n\n query_string\n\n : Returns the query string to search in this request.\n\n options\n\n : Returns the [QueryOptions](/appengine/docs/legacy/standard/python/search/queryoptionsclass) defining post-processing of the search results."]]
