Bases:abc.ABC

Base class for Filters

abstract build_pb(container_pb=None)

Build the protobuf representation based on values in the Filter.

class google.cloud.datastore.query.Iterator(query, client, limit=None, offset=None, start_cursor=None, end_cursor=None, eventual=False, retry=None, timeout=None, read_time=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 ina 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 throughquery results.

  • end_cursor (bytes) – (Optional) Cursor to end paging throughquery results.

  • eventual (bool) – (Optional) Defaults to strongly consistent (False).Setting True will use eventual consistency,but cannot be used inside a transaction orwith read_time, otherwise will raise ValueError.

  • retry (google.api_core.retry.Retry) – A retry object used to retry requests. IfNone is specified,requests will be retried using a default configuration.

  • timeout (float) – Time, in seconds, to wait for the request to complete.Note that ifretry is specified, the timeout appliesto each individual attempt.

  • read_time (datetime) – (Optional) Runs the query with read time consistency.Cannot be used with eventual consistency or inside atransaction, otherwise will raise ValueError. This feature is in private preview.

property explain_metrics(: google.cloud.datastore.query_profile.ExplainMetric )

Get the metrics associated with the query execution.Metrics are only available when explain_options is set on the query. IfExplainOptions.analyze is False, only plan_summary is available. If it isTrue, execution_stats is also available.

• Return type

  ExplainMetrics

• Returns

  The metrics associated with the query execution.

• Raises

  QueryExplainError if explain_metrics is not available on the query.

class google.cloud.datastore.query.Or(filters)

Bases:google.cloud.datastore.query.BaseCompositeFilter

Class representation of an OR Filter.

class google.cloud.datastore.query.PropertyFilter(property_name, operator, value)

Bases:google.cloud.datastore.query.BaseFilter

Class representation of a Property Filter

build_pb(container_pb=None)

Build the protobuf representation based on values in the Property Filter.

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

Bases:object

A Query against the Cloud Datastore.

This class serves as an abstraction for creating a query over datastored 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, usesthe 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 arerestricted.

  • filters (tuple[str, *[str](https://docs.python.org/3/library/stdtypes.html#str),[str](https://docs.python.org/3/library/stdtypes.html#str)]*) – Property filters applied by this query. The sequenceis(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 forthis query. When set, explain_metrics will be available on the iteratorreturned by query.fetch().

• Raises

  ValueError ifproject is not passed and no implicit default is set.

OPERATORS( = {'!=': Operator.NOT_EQUAL, '<': Operator.LESS_THAN, '<=': Operator.LESS_THAN_OR_EQUAL, '=': Operator.EQUAL, '>': Operator.GREATER_THAN, '>=': Operator.GREATER_THAN_OR_EQUAL, 'IN': Operator.IN, 'NOT_IN': Operator.NOT_IN )

Mapping of operator strings and their protobuf equivalents.

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

where property is a property stored on the entity in the datastoreand operator is one ofOPERATORS(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('<property>', '<operator>', <value>),            PropertyFilter('<property>', '<operator>', <value>)        ]    )).add_filter(    filter=Or(        [            PropertyFilter('<property>', '<operator>', <value>),            PropertyFilter('<property>', '<operator>', <value>)        ]    ))

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

• Parameters

  • property_name (str) – A property name.

  • operator (str) – One of=,<,<=,>,>=,!=,IN,NOT_IN.

  • value (int,str,bool,float,NoneType,datetime.datetime,google.cloud.datastore.key.Key) – The value to filter on.

  • filter (CompositeFilter,PropertyFiler) – A instance of a BaseFilter, either a CompositeFilter or PropertyFilter.

• Return type

  Query

• Returns

  A query object.

• Raises

  ValueError ifoperation 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, read_time=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(filter=PropertyFilter('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 orwith read_time, otherwise will raiseValueError.

  • retry (google.api_core.retry.Retry) – A retry object used to retry requests. IfNone is specified,requests will be retried using a default configuration.

  • timeout (float) – Time, in seconds, to wait for the request to complete.Note that ifretry is specified, the timeout appliesto each individual attempt.

  • read_time (datetime) – (Optional) use read_time read consistency, cannot be used inside atransaction or with eventual consistency, 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=,<,<=,>,>=,!=,IN,NOT_IN.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.