Class Query

A Query against the Cloud Datastore.

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

Inheritance

builtins.object > Query

Properties

ancestor

The ancestor key for the query.

Returns
TypeDescription
Key or NoneThe ancestor for the query.

distinct_on

Names of fields used to group query results.

Returns
TypeDescription
sequence of stringThe "distinct on" fields set on the query.

filters

Filters set on the query.

Returns
TypeDescription
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
TypeDescription
strThe kind for the query.

namespace

This query's namespace

Returns
TypeDescription
str or Nonethe namespace assigned to this query

order

Names of fields used to sort query results.

Returns
TypeDescription
sequence of stringThe order(s) set on the query.

project

Get the project for this Query.

Returns
TypeDescription
strThe project for the query.

projection

Fields names returned by the query.

Returns
TypeDescription
sequence of stringNames 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, =, <, <=, >, >=):

.. testsetup:: query-filter

import uuid

from google.cloud import datastore

client = datastore.Client()

.. doctest:: query-filter

>>> query = client.query(kind='Person')
>>> query = query.add_filter('name', '=', 'James')
>>> query = query.add_filter('age', '>', 50)
Parameters
NameDescription
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
TypeDescription
`ValueErrorif ``operation`` is not one of the specified values, or if a filter names ``'__key__'`` but passes an invalid value (a key is required).
Returns
TypeDescription
QueryA query object.

fetch

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

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

For example:

.. testsetup:: query-fetch

import uuid

from google.cloud import datastore

unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))

.. doctest:: query-fetch

>>> 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('name', '=', 'Sally').fetch())
>>> result
[<Entity('Person', 2345) {'name': 'Sally'}>]

.. testcleanup:: query-fetch

client.delete(andy.key)
client.delete(sally.key)
client.delete(bobby.key)
Parameters
NameDescription
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.

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.

Returns
TypeDescription
`Iterator`The iterator for the query.

key_filter

key_filter(key, operator="=")

Filter on a key.

Parameters
NameDescription
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.