Query

High-level wrapper for datastore queries.

The fundamental API here overloads the 6 comparison operators to represent filters on property values, and supports AND and OR operations (implemented as functions – Python’s ‘and’ and ‘or’ operators cannot be overloaded, and the ‘&’ and ‘|’ operators have a priority that conflicts with the priority of comparison operators).

For example:

class Employee(Model):
    name = StringProperty()
    age = IntegerProperty()
    rank = IntegerProperty()

  @classmethod
  def demographic(cls, min_age, max_age):
      return cls.query().filter(AND(cls.age >= min_age,
                                    cls.age <= max_age))

  @classmethod
  def ranked(cls, rank):
      return cls.query(cls.rank == rank).order(cls.age)

for emp in Employee.seniors(42, 5):
    print emp.name, emp.age, emp.rank

The ‘in’ operator cannot be overloaded, but is supported through the IN() method. For example:

Employee.query().filter(Employee.rank.IN([4, 5, 6]))

Sort orders are supported through the order() method; unary minus is overloaded on the Property class to represent a descending order:

Employee.query().order(Employee.name, -Employee.age)

Besides using AND() and OR(), filters can also be combined by repeatedly calling .filter():

query1 = Employee.query()  # A query that returns all employees
query2 = query1.filter(Employee.age >= 30)  # Only those over 30
query3 = query2.filter(Employee.age < 40)  # Only those in their 30s

A further shortcut is calling .filter() with multiple arguments; this implies AND():

query1 = Employee.query()  # A query that returns all employees
query3 = query1.filter(Employee.age >= 30,
                       Employee.age < 40)  # Only those in their 30s

And finally you can also pass one or more filter expressions directly to the .query() method:

query3 = Employee.query(Employee.age >= 30,
                        Employee.age < 40)  # Only those in their 30s

Query objects are immutable, so these methods always return a new Query object; the above calls to filter() do not affect query1. On the other hand, operations that are effectively no-ops may return the original Query object.

Sort orders can also be combined this way, and .filter() and .order() calls may be intermixed:

query4 = query3.order(-Employee.age)
query5 = query4.order(Employee.name)
query6 = query5.filter(Employee.rank == 5)

Again, multiple .order() calls can be combined:

query5 = query3.order(-Employee.age, Employee.name)

The simplest way to retrieve Query results is a for-loop:

for emp in query3:
    print emp.name, emp.age

Some other methods to run a query and access its results:

:meth:`Query.iter`() # Return an iterator; same as iter(q) but more
    flexible.
:meth:`Query.fetch`(N) # Return a list of the first N results
:meth:`Query.get`() # Return the first result
:meth:`Query.count`(N) # Return the number of results, with a maximum of N
:meth:`Query.fetch_page`(N, start_cursor=cursor) # Return (results, cursor,
    has_more)

All of the above methods take a standard set of additional query options, either in the form of keyword arguments such as keys_only=True, or as QueryOptions object passed with options=QueryOptions(…). The most important query options are:

  • keys_only: bool, if set the results are keys instead of entities.

  • limit: int, limits the number of results returned.

  • offset: int, skips this many results first.

  • start_cursor: Cursor, start returning results after this position.

  • end_cursor: Cursor, stop returning results after this position.

  • batch_size: int, hint for the number of results returned per RPC.

  • prefetch_size: int, hint for the number of results in the first RPC.

  • produce_cursors: bool, return Cursor objects with the results.

All of the above methods except for iter() have asynchronous variants as well, which return a Future; to get the operation’s ultimate result, yield the Future (when inside a tasklet) or call the Future’s get_result() method (outside a tasklet):

:meth:`Query.fetch_async`(N)
:meth:`Query.get_async`()
:meth:`Query.count_async`(N)
:meth:`Query.fetch_page_async`(N, start_cursor=cursor)

Finally, there’s an idiom to efficiently loop over the Query results in a tasklet, properly yielding when appropriate:

it = query1.iter()
while (yield it.has_next_async()):
    emp = it.next()
    print emp.name, emp.age
class google.cloud.ndb.query.QueryOptions(config=None, client=None, **kwargs)[source]

Bases: google.cloud.ndb._options.ReadOptions

ancestor
callback
copy(**kwargs)
deadline
distinct_on
end_cursor
filters
force_writes
global_cache_timeout
group_by
items()
keys_only
kind
limit
max_memcache_items
memcache_timeout
namespace
offset
classmethod options(wrapped)
order_by
orders
project
projection
propagation
read_consistency
read_policy
retries
classmethod slots()
start_cursor
timeout
transaction
use_cache
use_datastore
use_global_cache
use_memcache
class google.cloud.ndb.query.PropertyOrder(name, reverse=False)[source]

Bases: object

The sort order for a property name, to be used when ordering the results of a query.

Parameters

  • name (str) – The name of the model property to use for ordering.

  • reverse (bool) – Whether to reverse the sort order (descending) or not (ascending). Default is False.

name
reverse
class google.cloud.ndb.query.RepeatedStructuredPropertyPredicate(name, match_keys, entity_pb)[source]

Bases: object

A predicate for querying repeated structured properties.

Called by model.StructuredProperty._compare. This is used to handle queries of the form:

Squad.query(Squad.members == Member(name="Joe", age=24, rank=5))

This query should find any squad with a member named “Joe” whose age is 24 and rank is 5.

Datastore, on its own, can find all squads with a team member named Joe, or a team member whose age is 24, or whose rank is 5, but it can’t be queried for all 3 in a single subentity. This predicate must be applied client side, therefore, to limit results to entities where all the keys match for a single subentity.

Parameters

  • name (str) – Name of the repeated structured property being queried (e.g. “members”).

  • match_keys (list[str]) – Property names to check on the subentities being queried (e.g. [“name”, “age”, “rank”]).

  • entity_pb (google.cloud.datastore_v1.proto.entity_pb2.Entity) – A partial entity protocol buffer containing the values that must match in a subentity of the repeated structured property. Should contain a value for each key in match_keys.

match_keys
match_values
name
class google.cloud.ndb.query.ParameterizedThing[source]

Bases: object

Base class for Parameter and ParameterizedFunction.

This exists purely for isinstance() checks.

class google.cloud.ndb.query.Parameter(key)[source]

Bases: google.cloud.ndb.query.ParameterizedThing

Represents a bound variable in a GQL query.

Parameter(1) corresponds to a slot labeled :1 in a GQL query. Parameter('something') corresponds to a slot labeled :something.

The value must be set (bound) separately.

Parameters

key (Union[str, int]) – The parameter key.

Raises

TypeError – If the key is not a string or integer.

property key

Retrieve the key.

resolve(bindings, used)[source]

Resolve the current parameter from the parameter bindings.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters. This will be modified if the current parameter is in bindings.

Returns

The bound value for the current parameter.

Return type

Any

Raises

BadArgumentError – If the current parameter is not in bindings.

class google.cloud.ndb.query.ParameterizedFunction(func, values)[source]

Bases: google.cloud.ndb.query.ParameterizedThing

Represents a GQL function with parameterized arguments.

For example, ParameterizedFunction(‘key’, [Parameter(1)]) stands for the GQL syntax KEY(:1).

property func
property values
class google.cloud.ndb.query.Node[source]

Bases: object

Base class for filter expression tree nodes.

Tree nodes are considered immutable, even though they can contain Parameter instances, which are not. In particular, two identical trees may be represented by the same Node object in different contexts.

Raises

TypeError – Always, only subclasses are allowed.

resolve(bindings, used)[source]

Return a node with parameters replaced by the selected values.

Note

Both bindings and used are unused by this base class implementation.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters. This will be modified if the current parameter is in bindings.

Returns

The current node.

Return type

Node

class google.cloud.ndb.query.FalseNode[source]

Bases: google.cloud.ndb.query.Node

Tree node for an always-failing filter.

__eq__(other)[source]

Equality check.

An instance will always equal another FalseNode instance. This is because they hold no state.

resolve(bindings, used)

Return a node with parameters replaced by the selected values.

Note

Both bindings and used are unused by this base class implementation.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters. This will be modified if the current parameter is in bindings.

Returns

The current node.

Return type

Node

class google.cloud.ndb.query.ParameterNode[source]

Bases: google.cloud.ndb.query.Node

Tree node for a parameterized filter.

Parameters

  • prop (Property) – A property describing a value type.

  • op (str) – The comparison operator. One of =, !=, <, <=, >, >= or in.

  • param (ParameterizedThing) – The parameter corresponding to the node.

Raises
__getnewargs__()[source]

Private API used to specify __new__ arguments when unpickling.

Note

This method only applies if the pickle protocol is 2 or greater.

Returns

A tuple containing the internal state: the property, operation and parameter.

Return type

Tuple[Property, str, ParameterizedThing]

resolve(bindings, used)[source]

Return a node with parameters replaced by the selected values.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters.

Returns

A node corresponding to the value substituted.

Return type

Union[DisjunctionNode, FilterNode, FalseNode]

class google.cloud.ndb.query.FilterNode[source]

Bases: google.cloud.ndb.query.Node

Tree node for a single filter expression.

For example FilterNode("a", ">", 3) filters for entities where the value a is greater than 3.

Warning

The constructor for this type may not always return a FilterNode. For example:

  • The filter name != value is converted into (name > value) OR (name < value) (a DisjunctionNode)

  • The filter name in (value1, ..., valueN) is converted into (name = value1) OR ... OR (name = valueN) (also a DisjunctionNode)

  • The filter name in () (i.e. a property is among an empty list of values) is converted into a FalseNode

  • The filter name in (value1,) (i.e. a list with one element) is converted into name = value1, a related FilterNode with a different opsymbol and value than what was passed to the constructor

Parameters

  • name (str) – The name of the property being filtered.

  • opsymbol (str) – The comparison operator. One of =, !=, <, <=, >, >= or in.

  • value (Any) – The value to filter on / relative to.

Raises

TypeError – If opsymbol is "in" but value is not a basic container (list, tuple, set or frozenset)

__getnewargs__()[source]

Private API used to specify __new__ arguments when unpickling.

Note

This method only applies if the pickle protocol is 2 or greater.

Returns

A tuple containing the internal state: the name, opsymbol and value.

Return type

Tuple[str, str, Any]

resolve(bindings, used)

Return a node with parameters replaced by the selected values.

Note

Both bindings and used are unused by this base class implementation.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters. This will be modified if the current parameter is in bindings.

Returns

The current node.

Return type

Node

class google.cloud.ndb.query.PostFilterNode[source]

Bases: google.cloud.ndb.query.Node

Tree node representing an in-memory filtering operation.

This is used to represent filters that cannot be executed by the datastore, for example a query for a structured value.

Parameters

predicate (Callable[[Any], bool]) – A filter predicate that takes a datastore entity (typically as a protobuf) and returns True or False if the entity matches the given filter.

__getnewargs__()[source]

Private API used to specify __new__ arguments when unpickling.

Note

This method only applies if the pickle protocol is 2 or greater.

Returns

A tuple containing a single value, the predicate attached to this node.

Return type

Tuple[Callable[[Any], bool],]

predicate
resolve(bindings, used)

Return a node with parameters replaced by the selected values.

Note

Both bindings and used are unused by this base class implementation.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters. This will be modified if the current parameter is in bindings.

Returns

The current node.

Return type

Node

class google.cloud.ndb.query.ConjunctionNode[source]

Bases: google.cloud.ndb.query.Node

Tree node representing a boolean AND operator on multiple nodes.

Warning

The constructor for this type may not always return a ConjunctionNode. For example:

  • If the passed in nodes has only one entry, that single node will be returned by the constructor

  • If the resulting boolean expression has an OR in it, then a DisjunctionNode will be returned; e.g. AND(OR(A, B), C) becomes OR(AND(A, C), AND(B, C))

Parameters

nodes (Tuple[Node, ..]) – A list of nodes to be joined.

Raises

  • TypeError – If nodes is empty.

  • RuntimeError – If the nodes combine to an “empty” boolean expression.

__getnewargs__()[source]

Private API used to specify __new__ arguments when unpickling.

Note

This method only applies if the pickle protocol is 2 or greater.

Returns

The list of stored nodes, converted to a tuple.

Return type

Tuple[Node, ..]

resolve(bindings, used)[source]

Return a node with parameters replaced by the selected values.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters. This will be modified for each parameter found in bindings.

Returns

The current node, if all nodes are already resolved. Otherwise returns a modified ConjunctionNode with each individual node resolved.

Return type

Node

class google.cloud.ndb.query.DisjunctionNode[source]

Bases: google.cloud.ndb.query.Node

Tree node representing a boolean OR operator on multiple nodes.

Warning

This constructor may not always return a DisjunctionNode. If the passed in nodes has only one entry, that single node will be returned by the constructor.

Parameters

nodes (Tuple[Node, ..]) – A list of nodes to be joined.

Raises

TypeError – If nodes is empty.

__getnewargs__()[source]

Private API used to specify __new__ arguments when unpickling.

Note

This method only applies if the pickle protocol is 2 or greater.

Returns

The list of stored nodes, converted to a tuple.

Return type

Tuple[Node, ..]

resolve(bindings, used)[source]

Return a node with parameters replaced by the selected values.

Parameters

  • bindings (dict) – A mapping of parameter bindings.

  • used (Dict[Union[str, int], bool]) – A mapping of already used parameters. This will be modified for each parameter found in bindings.

Returns

The current node, if all nodes are already resolved. Otherwise returns a modified DisjunctionNode with each individual node resolved.

Return type

Node

google.cloud.ndb.query.AND

alias of google.cloud.ndb.query.ConjunctionNode

google.cloud.ndb.query.OR

alias of google.cloud.ndb.query.DisjunctionNode

class google.cloud.ndb.query.Query(kind=None, filters=None, ancestor=None, order_by=None, orders=None, project=None, app=None, namespace=None, projection=None, distinct_on=None, group_by=None, default_options=None)[source]

Bases: object

Query object.

Parameters

  • kind (str) – The kind of entities to be queried.

  • filters (FilterNode) – Node representing a filter expression tree.

  • ancestor (key.Key) – Entities returned will be descendants of ancestor.

  • order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

  • orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

  • project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

  • app (str) – Deprecated. Synonym for project.

  • namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

  • projection (list[str]) – The fields to return as part of the query results.

  • distinct_on (list[str]) – The field names used to group query results.

  • group_by (list[str]) – Deprecated. Synonym for distinct_on.

  • default_options (QueryOptions) – QueryOptions object.

Raises

TypeError – If any of the arguments are invalid.

__iter__(**kwargs)

Get an iterator over query results.

Parameters

  • keys_only (bool) – Return keys instead of entities.

  • limit (Optional[int]) – Maximum number of query results to return. If not specified, there is no limit.

  • projection (list[str]) – The fields to return as part of the query results.

  • offset (int) – Number of query results to skip.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) – DEPRECATED: An object containing options values for some of these arguments.

Returns

An iterator.

Return type

QueryIterator

analyze()[source]

Return a list giving the parameters required by a query.

When a query is created using gql, any bound parameters are created as ParameterNode instances. This method returns the names of any such parameters.

Returns

required parameter names.

Return type

list[str]

bind(*positional, **keyword)[source]

Bind parameter values. Returns a new Query object.

When a query is created using gql, any bound parameters are created as ParameterNode instances. This method receives values for both positional (:1, :2, etc.) or keyword (:something, :other, etc.) bound parameters, then sets the values accordingly. This mechanism allows easy reuse of a parameterized query, by passing the values to bind here.

Parameters

  • positional (list[Any]) – One or more positional values to bind.

  • keyword (dict[Any]) – One or more keyword values to bind.

Returns

A new query with the new bound parameter values.

Return type

Query

Raises

google.cloud.ndb.exceptions.BadArgumentError – If one of the positional parameters is not used in the query.

count(limit=None, **kwargs)[source]

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

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

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

Note

The legacy GAE version of NDB claims this is more efficient than just calling len(q.fetch(limit)). Since Datastore does not provide API for count, this version ends up performing the fetch underneath hood. We can specify keys_only to save some network traffic, making this call really equivalent to len(q.fetch(limit, keys_only=True)). We can also avoid marshalling NDB key objects from the returned protocol buffers, but this is a minor savings–most applications that use NDB will have their performance bound by the Datastore backend, not the CPU. Generally, any claim of performance improvement using this versus the equivalent call to fetch is exaggerated, at best.

Parameters

  • limit (Optional[int]) – Maximum number of query results to return. If not specified, there is no limit.

  • projection (list[str]) – The fields to return as part of the query results.

  • offset (int) – Number of query results to skip.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) – DEPRECATED: An object containing options values for some of these arguments.

Returns

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

Return type

Optional[Union[google.cloud.datastore.entity.Entity, key.Key]]

count_async(limit=None, **kwargs)[source]

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

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

Returns

See Query.count() for eventual result.

Return type

tasklets.Future

fetch(limit=None, **kwargs)[source]

Run a query, fetching results.

Parameters

  • limit (Optional[int]) – Maximum number of results to fetch. data:None or data:0 indicates no limit.

  • keys_only (bool) – Return keys instead of entities.

  • projection (list[str]) – The fields to return as part of the query results.

  • offset (int) – Number of query results to skip.

  • limit – Maximum number of query results to return. If not specified, there is no limit.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) – DEPRECATED: An object containing options values for some of these arguments.

Returns

The query results.

Return type

List([model.Model])

fetch_async(limit=None, **kwargs)[source]

Run a query, asynchronously fetching the results.

Parameters

  • keys_only (bool) – Return keys instead of entities.

  • projection (list[str]) – The fields to return as part of the query results.

  • offset (int) – Number of query results to skip.

  • limit (Optional[int]) – Maximum number of query results to return. If not specified, there is no limit.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) – DEPRECATED: An object containing options values for some of these arguments.

Returns

Eventual result will be a List[model.Model] of the

results.

Return type

tasklets.Future

fetch_page(page_size, **kwargs)[source]

Fetch a page of results.

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

To fetch the next page, you pass the cursor returned by one call to the next call using the start_cursor argument. A common idiom is to pass the cursor to the client using _datastore_query.Cursor.urlsafe() and to reconstruct that cursor on a subsequent request using the urlsafe argument to _datastore_query.Cursor.

Note

This method relies on cursors which are not available for queries that involve OR, !=, IN operators. This feature is not available for those queries.

Parameters

  • page_size (int) – The number of results per page. At most, this many

  • keys_only (bool) – Return keys instead of entities.

  • projection (list[str]) – The fields to return as part of the query results.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) –

    DEPRECATED: An object containing options

    values for some of these arguments.

    results will be returned.

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 indicates whether there are (likely) more results after that.

Return type

Tuple[list, _datastore_query.Cursor, bool]

fetch_page_async(page_size, **kwargs)[source]

Fetch a page of results.

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

Returns

See Query.fetch_page() for eventual result.

Return type

tasklets.Future

filter(*filters)[source]

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

Parameters

filters (list[Node]) – One or more instances of Node.

Returns

A new query with the new filters applied.

Return type

Query

Raises

TypeError – If one of the filters is not a Node.

get(**kwargs)[source]

Get the first query result, if any.

This is equivalent to calling q.fetch(1) and returning the first result, if any.

Parameters

  • keys_only (bool) – Return keys instead of entities.

  • projection (list[str]) – The fields to return as part of the query results.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) – DEPRECATED: An object containing options values for some of these arguments.

Returns

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

Return type

Optional[Union[google.cloud.datastore.entity.Entity, key.Key]]

get_async(**kwargs)[source]

Get the first query result, if any.

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

Returns

See Query.get() for eventual result.

Return type

tasklets.Future

property is_distinct

True if results are guaranteed to contain a unique set of property values.

This happens when every property in distinct_on is also in projection.

iter(**kwargs)[source]

Get an iterator over query results.

Parameters

  • keys_only (bool) – Return keys instead of entities.

  • limit (Optional[int]) – Maximum number of query results to return. If not specified, there is no limit.

  • projection (list[str]) – The fields to return as part of the query results.

  • offset (int) – Number of query results to skip.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) – DEPRECATED: An object containing options values for some of these arguments.

Returns

An iterator.

Return type

QueryIterator

map(callback, **kwargs)[source]

Map a callback function or tasklet over the query results.

Parameters

  • callback (Callable) – A function or tasklet to be applied to each result; see below.

  • keys_only (bool) – Return keys instead of entities.

  • projection (list[str]) – The fields to return as part of the query results.

  • offset (int) – Number of query results to skip.

  • limit (Optional[int]) – Maximum number of query results to return. If not specified, there is no limit.

  • batch_size (Optional[int]) – Number of results to fetch in a single RPC call. Affects efficiency of queries only. Larger batch sizes use more memory but make fewer RPC calls.

  • prefetch_size (Optional[int]) – Overrides batch size for first batch returned.

  • produce_cursors (bool) – Whether to generate cursors from query.

  • start_cursor – Starting point for search.

  • end_cursor – Endpoint point for search.

  • timeout (Optional[int]) – Override the gRPC timeout, in seconds.

  • deadline (Optional[int]) – DEPRECATED: Synonym for timeout.

  • read_consistency – If not in a transaction, defaults to ndb.EVENTUAL for potentially faster query results without having to wait for Datastore to apply pending changes to all returned records. Otherwise consistency with current transaction is maintained.

  • read_policy – DEPRECATED: Synonym for read_consistency.

  • transaction (bytes) – Transaction ID to use for query. Results will be consistent with Datastore state for that transaction. Implies read_policy=ndb.STRONG.

  • options (QueryOptions) – DEPRECATED: An object containing options values for some of these arguments.

  • pass_batch_info_callback – DEPRECATED: No longer implemented.

  • merge_future – DEPRECATED: No longer implemented.

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. The callback can return whatever it wants.

Returns

When the query has run to completion and all callbacks have

returned, map() returns a list of the results of all callbacks.

Return type

Any

map_async(callback, **kwargs)[source]

Map a callback function or tasklet over the query results.

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

Returns

See Query.map() for eventual result.

Return type

tasklets.Future

order(*props)[source]

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

Parameters

props (list[Union[str, google.cloud.ndb.model.Property]]) – One or more model properties to sort by.

Returns

A new query with the new order applied.

Return type

Query

run_to_queue(queue, conn, options=None, dsquery=None)[source]

Run this query, putting entities into the given queue.

google.cloud.ndb.query.gql(query_string, *args, **kwds)[source]

Parse a GQL query string.

Parameters

  • query_string (str) – Full GQL query, e.g. ‘SELECT * FROM Kind WHERE prop = 1 ORDER BY prop2’.

  • args – If present, used to call bind().

  • kwds – If present, used to call bind().

Returns

a query instance.

Return type

Query

Raises

google.cloud.ndb.exceptions.BadQueryError – When bad gql is passed in.