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

NameDescription
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
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, =, <, <=, >, >=, !=, IN, NOT_IN):

.. 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 =, <, <=, >, >=, !=, IN, NOT_IN.

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,
    read_time=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 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.

Returns
TypeDescription
IteratorThe 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 =, <, <=, >, >=, !=, IN, NOT_IN. Defaults to =.

keys_only

keys_only()

Set the projection to include only keys.