Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
NDB is an experimental, innovative, and rapidly changing new feature for App Engine. Unfortunately, being on the bleeding edge means that we may make backwards-incompatible changes to NDB. We will inform the community when this feature is no longer experimental.
A Query
object represents an NDB query, a request for
a filtered, sorted list of entities.
This page contains reference documentation. For a general discussion of NDB queries, see Queries.
Many query methods take a standard set of additional
options, either in the form of keyword arguments such as
keys_only=True
, or as
QueryOptions
object passed with
options=QueryOptions(...)
.
Queries support a variety of configuration options.
These are specified by keyword arguments to the Query
methods:
Argument | Type | Default | Description |
---|---|---|---|
keys_only | bool | False | All operations return keys instead of entities. |
offset | int | 0 | Number of query results to skip. |
limit | int | No limit | Maximum number of query results to return. |
batch_size | int | 20 | Batch size. Affects efficiency of queries only; larger batch sizes use more memory but make fewer RPC calls. |
prefetch_size | int | None | Overrides batch size for first batch returned. |
produce_cursors | bool | False
| Generate cursors from query (see Query Iterators. Query Cursors). |
start_cursor | Cursor | None
| Starting point for search (see Query Cursors). |
end_cursor | Cursor | None
| Ending point for search (see Query Cursors). |
deadline | int | Depends on Context
| Overrides RPC deadline (which defaults to 5 seconds if not overriden when
Context created)
|
read_policy | ndb.EVENTUAL_CONSISTENCY
| The read policy. Set to ndb.EVENTUAL_CONSISTENCY to get
perhaps-quicker results without waiting for the Datastore to
apply pending changes to all returned records.
|
To run a query with a specific set of options, pass the keyword arguments to the applicable method:
qry = Employee.query().filter(...).order(...) # Create a query for acct in qry.fetch(10, offset=20): # Skip the first 20 print acct
Occasionally, you might want to keep a set of query options
around and use them in various places. While you could just
keep them in a dictionary and pass this dictionary to the
methods using **kwds
, you can also create a
QueryOptions
object and pass
it using the options keyword argument.
The following two examples are equivalent:
qo = ndb.QueryOptions(keys_only=True, offset=20) results = qry.fetch(10, options=qo) results = qry.fetch(10, keys_only=True, offset=20)
Typically, an application creates a Query
by calling
Model.query()
. But it's also possible to call
ndb.Query()
.
Arguments
datastore_query.Order
object.
Query
with additional filter(s) applied.
Takes filter arguments as described in
Queries.
qry.filter(filter1).filter(filter2)
is equivalent to
qry.filter(filter1, filter2)
None
).
This is similar to calling q.fetch(1)
and returning
the first item of the list of results.
Arguments
Query
with additional sort order(s) applied.
Takes one or more arguments which are properties or "negated" properties.
For example, to sort users by age and "break ties" by name, you might
use something like qry.order(-Account.birthday, Account.name)
:1
, :2
, etc.) or named bindings
(:foo
, :bar
, etc.). It binds the passed
values to the parameters.
To bind parameters, you might call something like
qry.bind("USA", 49)
.
To bind named parameters, you might call something like
qry.bind(region = "USA", threshold = 49)
.
Returns a new Query
object with the parameter values bound.
len(q.fetch(limit))
but more
efficiently.
Arguments
Future
whose result is a number.
This is the asynchronous version of count().
Arguments
Future
whose result is a list of results.
This is the asynchronous version of fetch().
Arguments
start_cursor=cursor
.
A common idiom is to pass the cursor to
the client using cursor.to_websafe_string()
and to reconstruct
that cursor on a subsequent request using
Cursor.from_websafe_string(string)
.
Returns a tuple (results,
cursor, more)
, where
results is a list of query
results, cursor is a cursor pointing just after the last result
returned, and more is a bool
indicating whether there are (likely) more results after that.
None
). This is the asynchronous version
of get().
Arguments
Returns a QueryIterator object.
Arguments
True
, calls the callback with batch information
arguments as described below.
Future
subclass;
see below.
Callback signature The callback is normally called with an entity
as argument. However, if
keys_only=True
is given, it is called
with a Key.
If pass_batch_into_callback=True
is given, the callback is
called with three arguments: the current batch, the index within
the batch, and the entity or Key
at that index.
The callback can
return whatever it wants. If the callback is None
, a trivial
callback is assumed that just returns the entity or key passed in.
Optional merge_future
The merge_future
is an advanced argument
that can be used to override how the callback results are combined
into the overall map()
return value. By default, a list of
callback return values is produced. By substituting one of a
small number of specialized alternatives you can arrange
otherwise. See the source code for
tasklets.MultiFuture
for the default
implementation and a description of
the protocol the merge_future
object must implement. Alternatives from the same
module include QueueFuture
, SerialQueueFuture
and ReducingFuture
.
Returns a list of the results of all the callbacks.
(But see 'optional merge_future
' above.) It returns
when the query has run to completion and all callbacks have returned.