Python 2 is no longer supported by the community. We recommend that you migrate Python 2 apps to Python 3.

The Query Class

Class Query represents a request on the search service to query the index.

Query is defined in the module.


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 =
    # Specify the query string using the Search API's Query language.
    query_string='subject:first good',
                search.SortExpression(expression='subject', default_value='')],
        returned_fields=['author', 'subject', 'summary'],

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 =
    search.Query(query_string='subject:first good',


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.



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.


Instantiation of the QueryOptions class with instructions for post-processing search results.


Enable the discovery of the most relevant facets used by the documents that satisfy this search query and return them.


An iterable of FacetRequest or basestring as facet name to return specific facet with the result.


A FacetOption describing processing of facets.


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.



Raised when query_string is not a string or options is not a QueryOptions object.


Raised when the query_string could not be parsed.


An instance of class Query has the following properties:


Returns the query string to search in this request.


Returns the QueryOptions defining post-processing of the search results.