English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# NDB Query Class

#### Experimental!

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.

- Query Options
- Constructor
- Instance Methods
  - filter()
  - order()
  - bind()
  - count()
  - count_async()
  - fetch()
  - fetch_async()
  - fetch_page()
  - fetch_page_async()
  - get()
  - get_async()
  - iter()
  - map()
  - map_async()
  - run_to_queue()

## 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.
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

## 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 to `qry.filter(filter1, filter2)`
get(**q_options)
  Returns the first query result, if any (otherwise `None`). This is similar to calling `q.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 like `qry.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 like `qry.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.
count_async(limit, **q_options)
  Asynchronously counts the number of query results, up to a limit; it returns a `Future` whose result is a number. This is the asynchronous version of count().
fetch(limit, **q_options)
  Fetch a list of query results, up to a limit.

  Arguments

  limit
    How many results to count at most
  **q_options
    All query options keyword arguments are supported.
fetch_async(limit, **q_options)
  Asynchronously fetch a list of query results, up to a limit. Returns a `Future` whose result is a list of results. This is the asynchronous version of fetch().
fetch_page(page_size, **q_options)
  Fetch a "page" of results. This is a specialized method for use by paging user interfaces.

  Arguments

  page_size
    At most this many results will be returned.
  **q_options
    All query options keyword arguments are supported. In particular, 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.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.

fetch_page_async(page_size, **q_options)
  Asynchronously fetch a "page" of results. This is the asynchronous version of fetch().
get_async(**q_options)
  Asynchronously returns the first query result, if any (otherwise `None`). This is the asynchronous version of get().
iter(**q_options)
  Constructs and returns an iterator over the query.

  Arguments

  **q_options
    All query options keyword arguments are supported.

  Returns a QueryIterator object.

map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
  Map a callback function or tasklet over the query results. That is, apply the function (or tasklet) to each entity in the query results.

  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.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
  Asynchronously map a callback function or tasklet over the query results. This is the asynchronous version of map().