As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Queries¶

Create / interact with Google Cloud Datastore queries.

class google.cloud.datastore.query.And(filters)[source]¶

Bases: google.cloud.datastore.query.BaseCompositeFilter

Class representation of an AND Filter.

class google.cloud.datastore.query.BaseCompositeFilter(operation=Operator.OPERATOR_UNSPECIFIED, filters=None)[source]¶

Bases: google.cloud.datastore.query.BaseFilter

Base class for a Composite Filter. (either OR or AND).

build_pb(container_pb=None)[source]¶: Build the protobuf representation based on values in the Composite Filter.

class google.cloud.datastore.query.BaseFilter[source]¶

Bases: abc.ABC

Base class for Filters

abstract build_pb(container_pb=None)[source]¶: 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)[source]¶

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 with read_time, otherwise 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.
read_time (datetime) – (Optional) Runs the query with read time consistency. Cannot be used with eventual consistency or inside a transaction, otherwise will raise ValueError. This feature is in private preview.

property explain_metrics: google.cloud.datastore.query_profile.ExplainMetrics¶

Get the metrics associated with the query execution. Metrics are only available when explain_options is set on the query. If ExplainOptions.analyze is False, only plan_summary is available. If it is True, 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)[source]¶

Bases: google.cloud.datastore.query.BaseCompositeFilter

Class representation of an OR Filter.

class google.cloud.datastore.query.PropertyFilter(property_name, operator, value)[source]¶

Bases: google.cloud.datastore.query.BaseFilter

Class representation of a Property Filter

build_pb(container_pb=None)[source]¶: 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)[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 (tuple[str, str, 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.
explain_options (ExplainOptions) – (Optional) Options to enable query profiling for this query. When set, explain_metrics will be available on the iterator returned by query.fetch().

Raises

ValueError if project 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)[source]¶

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 datastore and operator is one of OPERATORS (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 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, read_time=None)[source]¶

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 or with read_time, otherwise 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.
read_time (datetime) – (Optional) use read_time read consistency, cannot be used inside a transaction 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='=')[source]¶

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()[source]¶: 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.

Queries¶

google-cloud-datastore

Navigation

Related Topics