Queries#

Create / interact with Google Cloud Datastore queries.

class google.cloud.datastore.query.Iterator(query, client, limit=None, offset=None, start_cursor=None, end_cursor=None)[source]#

Bases: object

Represent the state of a given execution of a Query.

Parameters:

query (google.cloud.datastore.query.Query) – Query object holding permanent configuration (i.e. things that don’t change on with each page in a results set).
client (google.cloud.datastore.client.Client) – The client used to make a request.
limit (integer) – (Optional) Limit the number of results returned.
offset (integer) – (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.

next_page()[source]#

Fetch a single “page” of query results.

Low-level API for fine control: the more convenient API is to iterate on the current Iterator.

Return type:	tuple, (entities, more_results, cursor)
Returns:	The next page of results.

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

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 (string) – The kind to query.
project (string) – The project associated with the query. If not passed, uses the client’s value.
namespace (string or None) – The namespace to which to restrict results. If not passed, uses the client’s value.
ancestor (google.cloud.datastore.key.Key or None) – key of the ancestor to which this query’s results are restricted.
filters (sequence of (property_name, operator, value) tuples) – property filters applied by this query.
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 = {'>': 3, '<=': 2, '=': 5, '>=': 4, '<': 1}#: Mapping of operator strings and their protobuf equivalents.

add_filter(property_name, operator, value)[source]#

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

Expressions take the form of:

.add_filter('<property>', '<operator>', <value>)

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

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> query = client.query(kind='Person')
>>> query.add_filter('name', '=', 'James')
>>> query.add_filter('age', '>', 50)

Parameters:	property_name (string) – A property name. operator (string) – One of `=`, `<`, `<=`, `>`, `>=`. value (`int`, `str`, `bool`, `float`, `NoneType`, `datetime.datetime`, `google.cloud.datastore.key.Key`) – The value to filter on.
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).

ancestor#

The ancestor key for the query.

Return type:	Key or None
Returns:	The ancestor for the query.

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)[source]#

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

For example:

>>> from google.cloud import datastore
>>> client = datastore.Client()
>>> query = client.query(kind='Person')
>>> query.add_filter('name', '=', 'Sally')
>>> list(query.fetch())
[<Entity object>, <Entity object>, ...]
>>> list(query.fetch(1))
[<Entity object>]

Parameters:	limit (integer or None) – An optional limit passed through to the iterator. offset (integer) – An optional offset passed through to the iterator. start_cursor (bytes) – An optional cursor passed through to the iterator. end_cursor (bytes) – An optional cursor passed through to the iterator. client (`google.cloud.datastore.client.Client`) – client used to connect to datastore. If not supplied, uses the query’s value.
Return type:	`Iterator`
Returns:	The iterator for the query.
Raises:	ValueError if `connection` is not passed and no implicit default has been set.

filters#

Filters set on the query.

Return type:	sequence of (property_name, operator, value) tuples.
Returns:	The filters set on the query.

key_filter(key, operator='=')[source]#

Filter on a key.

Parameters:	key (`google.cloud.datastore.key.Key`) – The key to filter on. operator (string) – (Optional) One of `=`, `<`, `<=`, `>`, `>=`. Defaults to `=`.

keys_only()[source]#: Set the projection to include only keys.

kind#

Get the Kind of the Query.

Return type:	string
Returns:	The kind for the query.

namespace#

This query’s namespace

Return type:	string or None
Returns:	the namespace assigned to this query

order#

Names of fields used to sort query results.

Return type:	sequence of string
Returns:	The order(s) set on the query.

project#

Get the project for this Query.

Return type:	str
Returns:	The project for the query.

projection#

Fields names returned by the query.

Return type:	sequence of string
Returns:	Names of fields in query results.