Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products.

Python 3.10 is now generally available.

google.appengine.ext.ndb.QueryIterator

This iterator works both for synchronous and async callers!

Inherits From: expected_type

For synchronous callers, just use:

for entity in Account.query():

Async callers use this idiom:

it = iter(Account.query()) while (yield it.has_next_async()): entity = it.next()

You can also use q.iter([options]) instead of iter(q); this allows passing query options such as keys_only or produce_cursors.

When keys_only is set, it.next() returns a key instead of an entity.

When produce_cursors is set, the methods it.cursor_before() and it.cursor_after() return Cursor objects corresponding to the query position just before and after the item returned by it.next(). Before it.next() is called for the first time, both raise an exception. Once the loop is exhausted, both return the cursor after the last item returned. Calling it.has_next() does not affect the cursors; you must call it.next() before the cursors move. Note that sometimes requesting a cursor requires a Cloud Datastore roundtrip (but not if you happen to request a cursor corresponding to a batch boundary). If produce_cursors is not set, both methods always raise an exception.

Note that queries requiring in-memory merging of multiple queries (i.e. queries using the IN, != or OR operators) do not support query options.

Methods

cursor_after

View source

Return the cursor after the current item.

You must pass a QueryOptions object with produce_cursors=True for this to work.

If there is no cursor or no current item, raise BadArgumentError. Before next() has returned there is no cursor. Once the loop is exhausted, this returns the cursor after the last item.

cursor_before

View source

Return the cursor before the current item.

You must pass a QueryOptions object with produce_cursors=True for this to work.

If there is no cursor or no current item, raise BadArgumentError. Before next() has returned there is no cursor. Once the loop is exhausted, this returns the cursor after the last item.

has_next

View source

Return whether a next item is available.

See the module docstring for the usage pattern.

has_next_async

View source

Return a Future whose result will say whether a next item is available.

See the module docstring for the usage pattern.

index_list

View source

Return the list of indexes used for this query.

This returns a list of index representations, where an index representation is the same as what is returned by get_indexes().

Before the first result, the information is unavailable, and then None is returned. This is not the same as an empty list -- the empty list means that no index was used to execute the query. (In the dev_appserver, an empty list may also mean that only built-in indexes were used; metadata queries also return an empty list here.)

Proper use is as follows: q = .query() i = q.iter() try: i.next() except Stopiteration: pass indexes = i.index_list() assert isinstance(indexes, list)

Notes:

  • Forcing produce_cursors=False makes this always return None.
  • This always returns None for a multi-query.

probably_has_next

View source

Return whether a next item is (probably) available.

This is not quite the same as has_next(), because when produce_cursors is set, some shortcuts are possible. However, in some cases (e.g. when the query has a post_filter) we can get a false positive (returns True but next() will raise StopIteration). There are no false negatives.

__iter__

View source

Iterator protocol: get the iterator for this iterator, i.e. self.