Queries

Create / interact with Google Cloud Datastore queries.

class google.cloud.datastore.query.And(filters)

Bases: google.cloud.datastore.query.BaseCompositeFilter

Class representation of an AND Filter.

class google.cloud.datastore.query.BaseCompositeFilter(operation=Operator.OPERATOR_UNSPECIFIED, filters=None)

Bases: google.cloud.datastore.query.BaseFilter

Base class for a Composite Filter. (either OR or AND).

build_pb(container_pb=None)

Build the protobuf representation based on values in the Composite Filter.

class google.cloud.datastore.query.BaseFilter()

Bases: abc.ABC

Base class for Filters

abstract build_pb(container_pb=None)

Build the protobuf representation based on values in the Filter.

class google.cloud.datastore.query.Iterator(query, client, limit=None, offset=None, start_cursor=None, end_cursor=None, eventual=False, retry=None, timeout=None, read_time=None)

Bases: google.api_core.page_iterator.Iterator

Represent the state of a given execution of a Query.

Parameters
- query (Query) – Query object holding permanent configuration (i.e. things that don’t change on with each page in a results set).
- client (Client) – The client used to make a request.
- limit (int) – (Optional) Limit the number of results returned.
- offset (int) – (Optional) Offset used to begin a query.
- start_cursor (bytes) – (Optional) Cursor to begin paging through query results.
- end_cursor (bytes) – (Optional) Cursor to end paging through query results.
- eventual (bool) – (Optional) Defaults to strongly consistent (False). Setting True will use eventual consistency, but cannot be used inside a transaction or with read_time, otherwise will raise ValueError.
- retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.
- timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.
- read_time (datetime) – (Optional) Runs the query with read time consistency. Cannot be used with eventual consistency or inside a transaction, otherwise will raise ValueError. This feature is in private preview.

class google.cloud.datastore.query.Or(filters)

Bases: google.cloud.datastore.query.BaseCompositeFilter

Class representation of an OR Filter.

class google.cloud.datastore.query.PropertyFilter(property_name, operator, value)

Bases: google.cloud.datastore.query.BaseFilter

Class representation of a Property Filter

build_pb(container_pb=None)

Build the protobuf representation based on values in the Property Filter.

class google.cloud.datastore.query.Query(client, kind=None, project=None, namespace=None, ancestor=None, filters=(), projection=(), order=(), distinct_on=())

Bases: object

A Query against the Cloud Datastore.

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

Parameters
- client (google.cloud.datastore.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](https://python.readthedocs.io/en/latest/library/stdtypes.html#str), [str](https://python.readthedocs.io/en/latest/library/stdtypes.html#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.
Raises

ValueError if project is not passed and no implicit default is set.

OPERATORS( = {'!=': Operator.NOT_EQUAL, '<': Operator.LESS_THAN, '<=': Operator.LESS_THAN_OR_EQUAL, '=': Operator.EQUAL, '>': Operator.GREATER_THAN, '>=': Operator.GREATER_THAN_OR_EQUAL, 'IN': Operator.IN, 'NOT_IN': Operator.NOT_IN )

Mapping of operator strings and their protobuf equivalents.

add_filter(property_name=None, operator=None, value=None, *, filter=None)

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

Expressions take the form of:

.add_filter(
  filter=PropertyFilter('<property>', '<operator>', <value>)
)

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

Both AND and OR operations are supported by passing in a CompositeFilter object to the filter parameter:

.add_filter(
    filter=And(
        [
            PropertyFilter('<property>', '<operator>', <value>),
            PropertyFilter('<property>', '<operator>', <value>)

        ]
    )
)

.add_filter(
    filter=Or(
        [
            PropertyFilter('<property>', '<operator>', <value>),
            PropertyFilter('<property>', '<operator>', <value>)
        ]
    )
)

>>> query = client.query(kind='Person')
>>> query = query.add_filter(filter=PropertyFilter('name', '=', 'James'))
>>> query = query.add_filter(filter=PropertyFilter('age', '>', 50))

Parameters
- property_name (str) – A property name.
- operator (str) – One of =, <, <=, >, >=, !=, IN, NOT_IN.
- value (int, str, bool, float, NoneType, datetime.datetime, google.cloud.datastore.key.Key) – The value to filter on.
- filter (CompositeFilter, PropertyFiler) – A instance of a BaseFilter, either a CompositeFilter or PropertyFilter.
Return type

Query
Returns

A query object.
Raises

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

property ancestor()

The ancestor key for the query.

Return type

Key or None
Returns

The ancestor for the query.

property distinct_on()

Names of fields used to group query results.

Return type

sequence of string
Returns

The “distinct on” fields set on the query.

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

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

For example:

>>> andy = datastore.Entity(client.key('Person', 1234))
>>> andy['name'] = 'Andy'
>>> sally = datastore.Entity(client.key('Person', 2345))
>>> sally['name'] = 'Sally'
>>> bobby = datastore.Entity(client.key('Person', 3456))
>>> bobby['name'] = 'Bobby'
>>> client.put_multi([andy, sally, bobby])
>>> query = client.query(kind='Person')
>>> result = list(query.add_filter(filter=PropertyFilter('name', '=', 'Sally')).fetch())
>>> result
[<Entity('Person', 2345) {'name': 'Sally'}>]

Parameters
- 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 (google.cloud.datastore.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 with read_time, otherwise will raise ValueError.
- retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.
- timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.
- read_time (datetime) – (Optional) use read_time read consistency, cannot be used inside a transaction or with eventual consistency, or will raise ValueError.
Return type

Iterator
Returns

The iterator for the query.

property filters()

Filters set on the query.

Return type

tuple[str, str, str]
Returns

The filters set on the query. The sequence is (property_name, operator, value).

key_filter(key, operator='=')

Filter on a key.

Parameters
- key (google.cloud.datastore.key.Key) – The key to filter on.
- operator (str) – (Optional) One of =, <, <=, >, >=, !=, IN, NOT_IN. Defaults to =.

keys_only()

Set the projection to include only keys.

property kind()

Get the Kind of the Query.

Return type

str
Returns

The kind for the query.

property namespace()

This query’s namespace

Return type

str or None
Returns

the namespace assigned to this query

property order()

Names of fields used to sort query results.

Return type

sequence of string
Returns

The order(s) set on the query.

property project()

Get the project for this Query.

Return type

str
Returns

The project for the query.

property projection()

Fields names returned by the query.

Return type

sequence of string
Returns

Names of fields in query results.