Class Query (2.4.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.

Inheritance

builtins.object > Query

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, =, <, <=, >, >=):

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

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,
    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

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

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.