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: google.cloud.iterator.Iterator

Represent the state of a given execution of a Query.

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

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

Set the projection to include only keys.

kind#

Get the Kind of the Query.

Return type:str
Returns:The kind for the query.
namespace#

This query’s namespace

Return type:str 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.