Note:Developers building new applications arestrongly encouraged to use theNDB Client Library, which has several benefitscompared to this client library, such as automatic entity caching via the MemcacheAPI. If you are currently using the older DB Client Library, read theDB to NDB Migration Guide

ClassQuery represents a query for retrieving entities from theApp Engine Datastore. (See also the related classGqlQuery,which defines queries using GQL, a SQL-like query language.)

Query is defined in the modulegoogle.appengine.ext.db.

Note:The index-based query mechanism supports a wide range of queries and is suitable formost applications. However, it does not support some kinds of query common inother database technologies: in particular, joins and aggregate queries aren'tsupported within the Datastore query engine. See Datastore Queries page for limitations on Datastore queries.

Introduction

An application creates a query object for a given entity kind by callingeither theQuery constructordirectly

classSong(db.Model):title=db.StringProperty()composer=db.StringProperty()date=db.DateTimeProperty()q=db.Query(Song)

or the class methodall()of the kind's model class:

q=Song.all()

Without further modification, the resulting instance of classQuery will retrieve all existing entities of the specified kind.Method calls on the object can then be used to customize the query withadditional filter criteria, ancestor conditions, and sort orders:

q.filter('title =','Imagine')q.ancestor(ancestor_key)q.order('-date')

For convenience, all of these methods return the query object itself so thatthey can cascaded in a single statement:

q.filter('title =','Imagine').ancestor(key).order('-date')

The application can then execute the query and access the results in any of the following ways:

• Treat the query object as an iterable, to process matching entities one at a time:

  forsonginq:printsong.title

  This implicitly calls the query'srun()method to generate the matching entities. It is thus equivalent to

  forsonginq.run():printsong.title

  You can set a limit on the number of results to process with the keyword argumentlimit:

  forsonginq.run(limit=5):printsong.title

  The iterator interface does not cache results, so creating a new iterator from the query object reiterates the same query from the beginning.

• Call the query'sget()method, to obtain the first single matching entity found in the Datastore:

  song=q.get()printsong.title

• Call the query'sfetch()method, to obtain a list of all matching entities up to a specified number of results:

  results=q.fetch(limit=5)forsonginresults:printsong.title

  As withrun(), the query object does not cache results, so callingfetch() a second time reissues the same query.

  Note: You should rarely need to use this method; it is almost always better to userun()instead.

Constructor

The constructor for classQuery is defined as follows:

class Query (model_class=None,keys_only=False,cursor=None,namespace=None,projection=None,distinct=False)

Creates an instance of classQuery for retrieving entities from the App Engine Datastore.

Without further modification, the resulting query object will retrieve all existing entities of the kind specified bymodel_class. The instance methodsfilter(),ancestor(), andorder() can then be used to customize the query with additional filter criteria, ancestor conditions, and sort orders.

Arguments

model_class

Model (or Expando) class representing the entity kind to which the query applies.

keys_only

Iftrue, return only keys instead of complete entities.Keys-only queriesare faster and cheaper than those that return complete entities.

cursor

Cursor position at which to resume query.

namespace

Namespace to use for query.

projection

List or tuple of names of properties to return. Only entities possessing the specified properties will be returned. If not specified, entire entities are returned by default.Projection queriesare faster and cheaper than those that return complete entities.

Note: Specifying this parameter may change the query's index requirements.

distinct

In the case ofProjection queries,distinct=True specifies that only completely unique results will be returned in a result set. This will only return the first result for entities which have the same values for the properties that are being projected.

True

Only return the first result for each distinct set of value for properties in the projection.

False

All results are returned.

Instance Methods

Instances of classQuery have the following methods:

filter (property_operator,value)

Adds a property filter to the query. The query will return only entities whose properties satisfy all of its filters.

Arguments

property_operator

String consisting of a property name and an optional comparison operator (=,!=,<,<=,>,>=,IN), separated by a space: for example,'age>'. If just a property name is specified without a comparison operator, the filter compares for equality (=) by default.

value

Value to compare with the property value. For example:

q.filter('height >',42).filter('city =','Seattle')q.filter('user =',users.get_current_user())

The comparison value specified should be of the samevalue typeas that of the property being compared.

ancestor (ancestor)

Adds an ancestor filter to the query. The query will return only entities with the specified ancestor.

Argument

ancestor

Ancestor entity or key.

order (property)

Adds a sort order to the query. If more than one sort order is added, they will be applied in the order specified.

Argument

property

String giving the name of the property on which to sort, optionally preceded by a hyphen (-) to specify descending order. Omitting the hyphen specifies ascending order by default. For example:

# Order alphabetically by last name:q.order('last_name')# Order by height, tallest to shortest:q.order('-height')

projection ()

Returns the tuple of properties in the projection orNone.

is_keys_only ()

Returns a boolean value indicating whether the query is a keys-only query.

run (read_policy=STRONG_CONSISTENCY,deadline=60,offset=0,limit=None,batch_size=20,keys_only=False,projection=None,start_cursor=None,end_cursor=None)

Returns an iterable for looping over the results of the query. This allows you to specify the query's operation with parameter settings and access the results iteratively:

1. Retrieves and discards the number of results specified by theoffset argument.
2. Retrieves and returns up to the maximum number of results specified by thelimit argument.

The loop's performance thus scales linearly with the sum ofoffset +limit. If you know how many results you want to retrieve, you should always set an explicitlimit value.

This method uses asynchronous prefetching to improve performance. By default, it retrieves its results from the Datastore in small batches, allowing the application to stop the iteration and avoid retrieving more results than are needed.

Tip: To retrieve all available results when their number is unknown, setbatch_size to a large value, such as1000.

Tip: If you don't need to change the default argument values, you can just use the query object directly as an iterable to control the loop. This implicitly callsrun() with default arguments.

Arguments

read_policy

Read policy specifying desired level of data consistency:

STRONG_CONSISTENCY

Guarantees the freshest results, but limited to a singleentity group.

EVENTUAL_CONSISTENCY

Can span multiple entity groups, but may occasionally return stale results. In general, eventually consistent queries run faster than strongly consistent queries, but there is no guarantee.

Note: Global (non-ancestor) queries ignore this argument.

deadline

Maximum time, in seconds, to wait for Datastore to return a result before aborting with an error. Accepts either an integer or a floating-point value. Cannot be set higher than the default value (60 seconds), but can be adjusted downward to ensure that a particular operation fails quickly (for instance, to return a faster response to the user, retry the operation, try a different operation, or add the operation to a task queue).

offset

Number of results to skip before returning the first one.

limit

Maximum number of results to return. If omitted or set toNone, all available results will be retrieved by default.

batch_size

Number of results to attempt to retrieve per batch. Iflimit is set, defaults to the specified limit; otherwise defaults to20.

keys_only

Iftrue, return only keys instead of complete entities.Keys-only queriesare faster and cheaper than those that return complete entities.

projection

List or tuple of names of properties to return. Only entities possessing the specified properties will be returned. If not specified, entire entities are returned by default.Projection queriesare faster and cheaper than those that return complete entities.

Note: Specifying this parameter may change the query's index requirements.

start_cursor

Cursor position at which to start query.

end_cursor

Cursor position at which to end query.

get (read_policy=STRONG_CONSISTENCY,deadline=60,offset=0,keys_only=False,projection=None,start_cursor=None,end_cursor=None)

Executes the query and returns the first result, orNone if no results are found.

Arguments

read_policy

Read policy specifying desired level of data consistency:

STRONG_CONSISTENCY

Guarantees the freshest results, but limited to a singleentity group.

EVENTUAL_CONSISTENCY

Can span multiple entity groups, but may occasionally return stale results. In general, eventually consistent queries run faster than strongly consistent queries, but there is no guarantee.

Note: Global (non-ancestor) queries ignore this argument.

deadline

Maximum time, in seconds, to wait for Datastore to return a result before aborting with an error. Accepts either an integer or a floating-point value. Cannot be set higher than the default value (60 seconds), but can be adjusted downward to ensure that a particular operation fails quickly (for instance, to return a faster response to the user, retry the operation, try a different operation, or add the operation to a task queue).

offset

Number of results to skip before returning the first one.

keys_only

Iftrue, return only keys instead of complete entities.Keys-only queriesare faster and cheaper than those that return complete entities.

projection

List or tuple of names of properties to return. Only entities possessing the specified properties will be returned. If not specified, entire entities are returned by default.Projection queriesare faster and cheaper than those that return complete entities.

Note: Specifying this parameter may change the query's index requirements.

start_cursor

Cursor position at which to start query.

end_cursor

Cursor position at which to end query.

fetch (limit,read_policy=STRONG_CONSISTENCY,deadline=60,offset=0,keys_only=False,projection=None,start_cursor=None,end_cursor=None)

Executes the query and returns a (possibly empty) list of results:

1. Retrieves and discards the number of results specified by theoffset argument.
2. Retrieves and returns up to the maximum number of results specified by thelimit argument.

The method's performance thus scales linearly with the sum ofoffset +limit.

Note: This method is merely a thin wrapper around therun()method, and is less efficient and more memory-intensive than usingrun() directly. You should rarely need to usefetch(); it is provided mainly for convenience in cases where you need to retrieve a full in-memory list of query results.

Tip: Thefetch() method is designed to retrieve only the number of results specified by thelimit argument. To retrieve all available results of a query when their number is unknown, userun()with a large batch size, such asrun(batch_size=1000), instead offetch().

Arguments

limit

Maximum number of results to return. If set toNone, all available results will be retrieved.

read_policy

Read policy specifying desired level of data consistency:

STRONG_CONSISTENCY

Guarantees the freshest results, but limited to a singleentity group.

EVENTUAL_CONSISTENCY

Can span multiple entity groups, but may occasionally return stale results. In general, eventually consistent queries run faster than strongly consistent queries, but there is no guarantee.

Note: Global (non-ancestor) queries ignore this argument.

deadline

Maximum time, in seconds, to wait for Datastore to return a result before aborting with an error. Accepts either an integer or a floating-point value. Cannot be set higher than the default value (60 seconds), but can be adjusted downward to ensure that a particular operation fails quickly (for instance, to return a faster response to the user, retry the operation, try a different operation, or add the operation to a task queue).

offset

Number of results to skip before returning the first one.

keys_only

Iftrue, return only keys instead of complete entities.Keys-only queriesare faster and cheaper than those that return complete entities.

projection

List or tuple of names of properties to return. Only entities possessing the specified properties will be returned. If not specified, entire entities are returned by default.Projection queriesare faster and cheaper than those that return complete entities.

Note: Specifying this parameter may change the query's index requirements.

start_cursor

Cursor position at which to start query.

end_cursor

Cursor position at which to end query.

count (read_policy=STRONG_CONSISTENCY,deadline=60,offset=0,limit=1000,start_cursor=None,end_cursor=None)

Returns the number of results matching the query. This is faster by a constant factor than actually retrieving all of the results, but the running time still scales linearly with the sum ofoffset +limit. Unless the result count is expected to be small, it is best to specify alimit argument; otherwise the method will continue until it finishes counting ortimes out.

Arguments

read_policy

Read policy specifying desired level of data consistency:

STRONG_CONSISTENCY

Guarantees the freshest results, but limited to a singleentity group.

EVENTUAL_CONSISTENCY

Can span multiple entity groups, but may occasionally return stale results. In general, eventually consistent queries run faster than strongly consistent queries, but there is no guarantee.

Note: Global (non-ancestor) queries ignore this argument.

deadline

Maximum time, in seconds, to wait for Datastore to return a result before aborting with an error. Accepts either an integer or a floating-point value. Cannot be set higher than the default value (60 seconds), but can be adjusted downward to ensure that a particular operation fails quickly (for instance, to return a faster response to the user, retry the operation, try a different operation, or add the operation to a task queue).

offset

Number of results to skip before counting the first one.

limit

Maximum number of results to count.

start_cursor

Cursor position at which to start query.

end_cursor

Cursor position at which to end query.

index_list ()

Returns a list of indexes used by an executed query, including primary, composite, kind, and single-property indexes.

Caution: Invoking this method on a query that has not yet been executed will raise an AssertionErrorexception.

Note: This feature is not fully supported on the development server. When used with the development server, the result is either the empty list or a list containing exactly one composite index.

For example, the following code prints various information about the indexes used by a query:

# other imports ...importwebapp2fromgoogle.appengine.apiimportusersfromgoogle.appengine.extimportdbclassGreeting(db.Model):author=db.StringProperty()content=db.StringProperty(multiline=True)date=db.DateTimeProperty(auto_now_add=True)classMainPage(webapp2.RequestHandler):defget(self):user=users.get_current_user()q=db.Query(Greeting)q.filter("author =",user.user_id())q.order("-date")q.fetch(100)index_list=q.index_list()forixinindex_list:self.response.out.write("Kind:%s"%ix.kind())self.response.out.write("<br />")self.response.out.write("Has ancestor?%s"%ix.has_ancestor())self.response.out.write("<br />")forname,directioninix.properties():self.response.out.write("Property name: "+name)self.response.out.write("<br />")ifdirection==db.Index.DESCENDING:self.response.out.write("Sort direction: DESCENDING")else:self.response.out.write("Sort direction: ASCENDING")self.response.out.write("<br />")

This produces output like the following for each index:

Kind: GreetingHas ancestor? FalseProperty name: authorSort direction: ASCENDINGProperty name: dateSort direction: DESCENDING

cursor ()

Returns a base64-encodedcursor string denoting the position in the query's result set following the last result retrieved. The cursor string is safe to use in HTTPGET andPOST parameters, and can also be stored in the Datastore or Memcache. A future invocation of the same query can provide this string via thestart_cursor parameter or thewith_cursor()method to resume retrieving results from this position.

Caution: Invoking this method on a query that has not yet been executed will raise an AssertionErrorexception.

Note: Not all queries are compatible with cursors; see theDatastore Queriespage for more information.

with_cursor (start_cursor,end_cursor=None)

Specifies the starting and (optionally) ending positions within a query's result set from which to retrieve results. The cursor strings denoting the starting and ending positions can be obtained by callingcursor()after a previous invocation of the query. The current query must be identical to that earlier invocation, including the entity kind, property filters, ancestor filters, and sort orders.

Arguments

start_cursor

Base64-encoded cursor string specifying where to start the query.

end_cursor

Base64-encoded cursor string specifying where to end the query.