App Engine Python SDK  v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
Classes | Functions | Variables
google.appengine.ext.ndb.query Namespace Reference

Classes

class  _MultiQuery
 
class  _SubQueryIteratorState
 
class  ConjunctionNode
 
class  DisjunctionNode
 
class  FalseNode
 
class  FilterNode
 
class  Node
 
class  Parameter
 
class  ParameterizedFunction
 
class  ParameterizedThing
 
class  ParameterNode
 
class  PostFilterNode
 
class  Query
 
class  QueryIterator
 
class  QueryOptions
 
class  RepeatedStructuredPropertyPredicate
 

Functions

def gql
 

Variables

string __author__ = 'guido@google.com (Guido van Rossum)'
 
list __all__
 
 Cursor = datastore_query.Cursor
 
 _ASC = datastore_query.PropertyOrder.ASCENDING
 
 _DESC = datastore_query.PropertyOrder.DESCENDING
 
 _AND = datastore_query.CompositeFilter.AND
 
 _KEY = datastore_types._KEY_SPECIAL_PROPERTY
 
tuple _OPS = frozenset(['=', '!=', '<', '<=', '>', '>=', 'in'])
 
int _MAX_LIMIT = 2
 
 AND = ConjunctionNode
 
 OR = DisjunctionNode
 

Detailed Description

Higher-level Query wrapper.

There are perhaps too many query APIs in the world.

The fundamental API here overloads the 6 comparisons operators to
represent filters on property values, and supports AND and OR
operations (implemented as functions -- Python's 'and' and 'or'
operators cannot be overloaded, and the '&' and '|' operators have a
priority that conflicts with the priority of comparison operators).
For example:

  class Employee(Model):
    name = StringProperty()
    age = IntegerProperty()
    rank = IntegerProperty()

    @classmethod
    def demographic(cls, min_age, max_age):
return cls.query().filter(AND(cls.age >= min_age, cls.age <= max_age))

    @classmethod
    def ranked(cls, rank):
return cls.query(cls.rank == rank).order(cls.age)

  for emp in Employee.seniors(42, 5):
    print emp.name, emp.age, emp.rank

The 'in' operator cannot be overloaded, but is supported through the
IN() method.  For example:

  Employee.query().filter(Employee.rank.IN([4, 5, 6]))

Sort orders are supported through the order() method; unary minus is
overloaded on the Property class to represent a descending order:

  Employee.query().order(Employee.name, -Employee.age)

Besides using AND() and OR(), filters can also be combined by
repeatedly calling .filter():

  q1 = Employee.query()  # A query that returns all employees
  q2 = q1.filter(Employee.age >= 30)  # Only those over 30
  q3 = q2.filter(Employee.age < 40)  # Only those in their 30s

A further shortcut is calling .filter() with multiple arguments; this
implies AND():

  q1 = Employee.query()  # A query that returns all employees
  q3 = q1.filter(Employee.age >= 30,
           Employee.age < 40)  # Only those in their 30s

And finally you can also pass one or more filter expressions directly
to the .query() method:

  q3 = Employee.query(Employee.age >= 30,
                Employee.age < 40)  # Only those in their 30s

Query objects are immutable, so these methods always return a new
Query object; the above calls to filter() do not affect q1.  (On the
other hand, operations that are effectively no-ops may return the
original Query object.)

Sort orders can also be combined this way, and .filter() and .order()
calls may be intermixed:

  q4 = q3.order(-Employee.age)
  q5 = q4.order(Employee.name)
  q6 = q5.filter(Employee.rank == 5)

Again, multiple .order() calls can be combined:

  q5 = q3.order(-Employee.age, Employee.name)

The simplest way to retrieve Query results is a for-loop:

  for emp in q3:
    print emp.name, emp.age

Some other methods to run a query and access its results:

  q.iter() # Return an iterator; same as iter(q) but more flexible
  q.map(callback) # Call the callback function for each query result
  q.fetch(N) # Return a list of the first N results
  q.get() # Return the first result
  q.count(N) # Return the number of results, with a maximum of N
  q.fetch_page(N, start_cursor=cursor) # Return (results, cursor, has_more)

All of the above methods take a standard set of additional query
options, either in the form of keyword arguments such as
keys_only=True, or as QueryOptions object passed with
options=QueryOptions(...).  The most important query options are:

  keys_only: bool, if set the results are keys instead of entities
  limit: int, limits the number of results returned
  offset: int, skips this many results first
  start_cursor: Cursor, start returning results after this position
  end_cursor: Cursor, stop returning results after this position
  batch_size: int, hint for the number of results returned per RPC
  prefetch_size: int, hint for the number of results in the first RPC
  produce_cursors: bool, return Cursor objects with the results

For additional (obscure) query options and more details on them,
including an explanation of Cursors, see datastore_query.py.

All of the above methods except for iter() have asynchronous variants
as well, which return a Future; to get the operation's ultimate
result, yield the Future (when inside a tasklet) or call the Future's
get_result() method (outside a tasklet):

  q.map_async(callback)  # Callback may be a task or a plain function
  q.fetch_async(N)
  q.get_async()
  q.count_async(N)
  q.fetch_page_async(N, start_cursor=cursor)

Finally, there's an idiom to efficiently loop over the Query results
in a tasklet, properly yielding when appropriate:

  it = q.iter()
  while (yield it.has_next_async()):
    emp = it.next()
    print emp.name, emp.age

Function Documentation

def google.appengine.ext.ndb.query.gql (   query_string,
  args,
  kwds 
)
Parse a GQL query string.

Args:
  query_string: Full GQL query, e.g. 'SELECT * FROM Kind WHERE prop = 1'.
  *args, **kwds: If present, used to call bind().

Returns:
  An instance of query_class.

Variable Documentation

list google.appengine.ext.ndb.query.__all__
Initial value:
1 = ['Query', 'QueryOptions', 'Cursor', 'QueryIterator',
2  'RepeatedStructuredPropertyPredicate',
3  'AND', 'OR', 'ConjunctionNode', 'DisjunctionNode',
4  'FilterNode', 'PostFilterNode', 'FalseNode', 'Node',
5  'ParameterNode', 'ParameterizedThing', 'Parameter',
6  'ParameterizedFunction', 'gql',
7  ]