The Query Class

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.