google.appengine.ext.ndb.Query

Query object.

Inherits From: expected_type

google.appengine.ext.ndb.Query(
    kind=None,
    ancestor=None,
    filters=None,
    orders=None,
    app=None,
    namespace=None,
    default_options=None,
    projection=None,
    group_by=None
)

Usually constructed by calling Model.query().

See module docstring for examples.

Note that not all operations on Queries are supported by _MultiQuery instances; the latter are generated as necessary when any of the operators !=, IN or OR is used.

kind Optional kind string.
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.
default_options Optional QueryOptions object.
projection Optional list or tuple of properties to project.
group_by Optional list or tuple of properties to group by.

ancestor Accessor for the ancestor (a Key or None).
app Accessor for the app (a string or None).
default_options Accessor for the default_options (a QueryOptions instance or None).
filters Accessor for the filters (a Node or None).
group_by Accessor for the group by properties (a tuple instance or None).
is_distinct True if results are guaranteed to contain a unique set of property values.

This happens when every property in the group_by is also in the projection.

kind Accessor for the kind (a string or None).
namespace Accessor for the namespace (a string or None).
orders Accessor for the filters (a datastore_query.Order or None).
projection Accessor for the projected properties (a tuple instance or None).

Methods

analyze

View source

analyze()

Return a list giving the parameters required by a query.

bind

View source

bind(
    *args, **kwds
)

Bind parameter values. Returns a new Query object.

count

View source

count(
    limit=None, **q_options
)

Count the number of query results, up to a limit.

This returns the same result as len(q.fetch(limit)) but more efficiently.

Note that you must pass a maximum value to limit the amount of work done by the query.

Args
limit How many results to count at most.
**q_options All query options keyword arguments are supported.

Returns:

count_async

View source

count_async(
    limit=None, **q_options
)

Count the number of query results, up to a limit.

This is the asynchronous version of Query.count().

fetch

View source

fetch(
    limit=None, **q_options
)

Fetch a list of query results, up to a limit.

Args
limit How many results to retrieve at most.
**q_options All query options keyword arguments are supported.

Returns
A list of results.

fetch_async

View source

fetch_async(
    limit=None, **q_options
)

Fetch a list of query results, up to a limit.

This is the asynchronous version of Query.fetch().

fetch_page

View source

fetch_page(
    page_size, **q_options
)

Fetch a page of results.

This is a specialized method for use by paging user interfaces.

Args
page_size The requested page size. At most this many results will be returned.

In addition, any keyword argument supported by the QueryOptions class is supported. In particular, to fetch the next page, you pass the cursor returned by one call to the next call using start_cursor=. A common idiom is to pass the cursor to the client using .to_websafe_string() and to reconstruct that cursor on a subsequent request using Cursor.from_websafe_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.

fetch_page_async

View source

fetch_page_async(
    page_size, **q_options
)

Fetch a page of results.

This is the asynchronous version of Query.fetch_page().

filter

View source

filter(
    *args
)

Return a new Query with additional filter(s) applied.

get

View source

get(
    **q_options
)

Get the first query result, if any.

This is similar to calling q.fetch(1) and returning the first item of the list of results, if any, otherwise None.

Args
**q_options All query options keyword arguments are supported.

Returns
A single result, or None if there are no results.

get_async

View source

get_async(
    **q_options
)

Get the first query result, if any.

This is the asynchronous version of Query.get().

iter

View source

iter(
    **q_options
)

Construct an iterator over the query.

Args
**q_options All query options keyword arguments are supported.

Returns
A QueryIterator object.

map

View source

map(
    callback, pass_batch_into_callback=None, merge_future=None, **q_options
)

Map a callback function or tasklet over the query results.

Args
callback A function or tasklet to be applied to each result; see 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. Also, when pass_batch_into_callback is True, it 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 (ignoring produce_cursors).

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 tasklets.MultiFuture for the default implementation and a description of the protocol the merge_future object must implement the default. Alternatives from the same module include QueueFuture, SerialQueueFuture and ReducingFuture.

Returns
When the query has run to completion and all callbacks have returned, map() returns a list of the results of all callbacks. (But see 'optional merge future' above.)

map_async

View source

map_async(
    callback, pass_batch_into_callback=None, merge_future=None, **q_options
)

Map a callback function or tasklet over the query results.

This is the asynchronous version of Query.map().

order

View source

order(
    *args
)

Return a new Query with additional sort order(s) applied.

run_to_queue

View source

run_to_queue(
    queue, conn, options=None, dsquery=None
)

Run this query, putting entities into the given queue.

__iter__

View source

__iter__(
    **q_options
)

Construct an iterator over the query.

Args
**q_options All query options keyword arguments are supported.

Returns
A QueryIterator object.