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 .
- Query Options
- Constructor
- Instance Methods
Query Options
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. |
projection | tuple (or list) of properties (or strings) |
None
|
Operations return entities with only the specified properties
set.
projection=[Article.title, Article.date]
or
projection=['title', 'date']
fetches entities with just those two fields set.
(See
Projection Queries
.)
|
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)
Constructor
Typically, an application creates a
Query
by calling
Model
.query()
. But it's also possible to call
ndb.Query()
.
Arguments
- kind
- Optional kind string. Normally, the name of a entity class.
- ancestor
- Optional ancestor Key.
- filters
- Optional Node representing a filter expression tree.
- orders
-
Optional
datastore_query.Order
object. - app
- Optional app id.
- namespace
- Optional namespace. If not specified, the default namespace at the time the query is executed will be used.
- projection
- Optional list or tuple of properties to project.
- group_by
- Optional list or tuple of properties to group by.
- default_options
-
Optional
QueryOptions
object giving default query options to be used when the query is executed.
Instance Methods
- filter ( filter1, filter2, ... )
-
Returns a new
Query
with additional filter(s) applied. Takes filter arguments as described in Queries .qry.filter( filter1 ).filter( filter2 )
is equivalent toqry.filter( filter1 , filter2 )
- get ( **q_options )
-
Returns the first query result, if any (otherwise
None
). This is similar to callingq.fetch(1)
and returning the first item of the list of results.Arguments
- **q_options
- All query options keyword arguments are supported.
- order ( order1 , order2 , ...)
-
Returns a new
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 likeqry.order(-Account.birthday, Account.name)
- bind ( ...values... )
-
This function is for use with GQL queries that use parameter
bindings (
: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 likeqry.bind(region = "USA", threshold = 49)
.Returns a new
Query
object with the parameter values bound. - count ( limit =None, **q_options )
-
Returns the number of query results, up to a limit.
This returns the same result as
len(q.fetch(limit))
but more efficiently.Arguments
- limit
- How many results to count at most
- **q_options
- All query options keyword arguments and context options are supported.
Future
whose result is a number.
This is the asynchronous version of
count()
.
Arguments
- limit
- How many results to count at most
- **q_options
- All query options keyword arguments are supported.
Future
whose result is a list of results.
This is the asynchronous version of
fetch()
.
Arguments
- page_size
- At most this many results will be returned.
- **q_options
- All query options keyword arguments are supported.
(
results
,
cursor
,
more
)
:
- results list of query results
-
cursor
a
query cursor
pointing
to the "next" batch of results. If there are no more results, this might
be
None
. -
more
bool
indicating whether there are (likely) more results after this batch. IfFalse
, there are no more results; ifTrue
, there are probably more results.
To fetch the next page,
pass the cursor returned by one call to the next call using
start_cursor=
cursor
.
A common idiom is to pass the cursor to
the client using
cursor
.urlsafe()
and to reconstruct that cursor on a subsequent request using
Cursor(urlsafe=
string
)
.
None
). This is the asynchronous version
of
get()
.
Arguments
- **q_options
- All query options keyword arguments are supported.
Returns a QueryIterator object.
Arguments
- callback
- A function or tasklet to be applied to each result.
- pass_batch_into_callback
-
If
True
, calls the callback with batch information arguments as described below. - merge_future
-
Optional
Future
subclass; see below. - **q_options
- All query options keyword arguments are supported.
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.