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)

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.

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( = {'<': 1, '<=': 2, '=': 5, '>': 3, '>=': 4 )

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, = , < , <= , > , >= ):

 >>> 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( str ) – A property name.

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

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)

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

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

• Parameters

  • key( google.cloud.datastore.key.Key ) – The key to filter on.

  • operator( str ) – (Optional) One of = , < , <= , > , >= . Defaults to = .

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.