Class Query (1.11.0)

Query(
    client,
    kind=None,
    project=None,
    namespace=None,
    ancestor=None,
    filters=(),
    projection=(),
    order=(),
    distinct_on=(),
)

A Query against the Cloud Datastore.

This class serves as an abstraction for creating a query over data stored in the Cloud Datastore.

Parameters
Name	Description
`client`	`Client` The client used to connect to Datastore.
`kind`	`str` The kind to query.
`project`	`str` (Optional) The project associated with the query. If not passed, uses the client's value.
`namespace`	`str` (Optional) The namespace to which to restrict results. If not passed, uses the client's value.
`ancestor`	`Key` (Optional) key of the ancestor to which this query's results are restricted.
`filters`	`tuple[str, str, str]` Property filters applied by this query. The sequence is `(property_name, operator, value)`.
`projection`	`sequence of string` fields returned as part of query results.
`order`	`sequence of string` field names used to order query results. Prepend `-` to a field name to sort it in descending order.
`distinct_on`	`sequence of string` field names used to group query results.

Properties

ancestor

The ancestor key for the query.

Returns
Type	Description
`Key or None`	The ancestor for the query.

distinct_on

Names of fields used to group query results.

Returns
Type	Description
`sequence of string`	The "distinct on" fields set on the query.

filters

Filters set on the query.

Returns
Type	Description
`tuple[str, str, str]`	The filters set on the query. The sequence is `(property_name, operator, value)`.

kind

Get the Kind of the Query.

Returns
Type	Description
`str`	The kind for the query.

namespace

This query's namespace

Returns
Type	Description
`str or None`	the namespace assigned to this query

order

Names of fields used to sort query results.

Returns
Type	Description
`sequence of string`	The order(s) set on the query.

project

Get the project for this Query.

Returns
Type	Description
`str`	The project for the query.

projection

Fields names returned by the query.

Returns
Type	Description
`sequence of string`	Names of fields in query results.

Methods

add_filter

add_filter(property_name, operator, value)

Filter the query based on a property name, operator and a value.

Expressions take the form of::

.add_filter('

where property is a property stored on the entity in the datastore and operator is one of OPERATORS (ie, =, <, <=, >, >=)::

from google.cloud import datastore client = datastore.Client() query = client.query(kind='Person') query = query.add_filter('name', '=', 'James') query = query.add_filter('age', '>', 50)

Parameters
Name	Description
`property_name`	`str` A property name.
`operator`	`str` One of `=`, `<`, `<=`, `>`, `>=`.
`value`	`int, str, bool, float, NoneType, datetime.datetime, Key` The value to filter on.

Exceptions
Type	Description
`ValueError	if `operation` is not one of the specified values, or if a filter names `'__key__'` but passes an invalid value (a key is required).

Returns
Type	Description
`Query`	A query object.

fetch

fetch(
    limit=None,
    offset=0,
    start_cursor=None,
    end_cursor=None,
    client=None,
    eventual=False,
)

Execute the Query; return an iterator for the matching entities.

For example::

from google.cloud import datastore client = datastore.Client() query = client.query(kind='Person') result = query.add_filter('name', '=', 'Sally').fetch() list(result) [

Parameters
Name	Description
`limit`	`int` (Optional) limit passed through to the iterator.
`offset`	`int` (Optional) offset passed through to the iterator.
`start_cursor`	`bytes` (Optional) cursor passed through to the iterator.
`end_cursor`	`bytes` (Optional) cursor passed through to the iterator.
`client`	`Client` (Optional) client used to connect to datastore. If not supplied, uses the query's value.
`eventual`	`bool` (Optional) Defaults to strongly consistent (False). Setting True will use eventual consistency, but cannot be used inside a transaction or will raise ValueError.

Returns
Type	Description
`Iterator`	The iterator for the query.

key_filter

key_filter(key, operator="=")

Filter on a key.

Parameters
Name	Description
`key`	`Key` The key to filter on.
`operator`	`str` (Optional) One of `=`, `<`, `<=`, `>`, `>=`. Defaults to `=`.

keys_only

keys_only()

Set the projection to include only keys.