Class Query (2.20.2)

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

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.
`explain_options`	`ExplainOptions` (Optional) Options to enable query profiling for this query. When set, explain_metrics will be available on the iterator returned by query.fetch().

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=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('

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('

       ]
   )

)

.add_filter( filter=Or( [ PropertyFilter('

.. testsetup:: query-filter

import uuid

from google.cloud import datastore
from google.cloud.datastore.query import PropertyFilter

client = datastore.Client()

.. doctest:: query-filter

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

Parameters
Name	Description
`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.
`filter`	`CompositeFilter, PropertyFiler` A instance of a `BaseFilter`, either a `CompositeFilter` or `PropertyFilter`.

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,
    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
from google.cloud.datastore.query import PropertyFilter
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(filter=PropertyFilter('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 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
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 `=`, `<`, `<=`, `>`, `>=`, `!=`, `IN`, `NOT_IN`. Defaults to `=`.

keys_only

keys_only()

Set the projection to include only keys.