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, eventual=False, retry=None, timeout=None)

Bases: google.api_core.page_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.

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

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

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 (tuple[str, *[str](https://python.readthedocs.io/en/latest/library/stdtypes.html#str), [str](https://python.readthedocs.io/en/latest/library/stdtypes.html#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.

  • Raises

    ValueError if project is not passed and no implicit default is set.

OPERATORS( = {'!=': <Operator.NOT_EQUAL: 9>, '<': <Operator.LESS_THAN: 1>, '<=': <Operator.LESS_THAN_OR_EQUAL: 2>, '=': <Operator.EQUAL: 5>, '>': <Operator.GREATER_THAN: 3>, '>=': <Operator.GREATER_THAN_OR_EQUAL: 4>, 'IN': <Operator.IN: 6>, 'NOT_IN': <Operator.NOT_IN: 13> )

Mapping of operator strings and their protobuf equivalents.

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('<property>', '<operator>', <value>)

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

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

  • Parameters

  • Return type

    Query

  • Returns

    A query object.

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

property ancestor()

The ancestor key for the query.

  • Return type

    Key or None

  • Returns

    The ancestor for the query.

property 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, eventual=False, retry=None, timeout=None)

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

For example:

>>> 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'}>]

  • 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) – (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.

  • Return type

    Iterator

  • Returns

    The iterator for the query.

property filters()

Filters set on the query.

  • Return type

    tuple[str, str, str]

  • Returns

    The filters set on the query. The sequence is (property_name, operator, value).

key_filter(key, operator='=')

Filter on a key.

keys_only()

Set the projection to include only keys.

property kind()

Get the Kind of the Query.

  • Return type

    str

  • Returns

    The kind for the query.

property namespace()

This query’s namespace

  • Return type

    str or None

  • Returns

    the namespace assigned to this query

property order()

Names of fields used to sort query results.

  • Return type

    sequence of string

  • Returns

    The order(s) set on the query.

property project()

Get the project for this Query.

  • Return type

    str

  • Returns

    The project for the query.

property projection()

Fields names returned by the query.

  • Return type

    sequence of string

  • Returns

    Names of fields in query results.