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)[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 will raise ValueError.
-
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 (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.
- 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)[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
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
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)[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
) – (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
- Returns
The iterator for the query.
-
property
filters
# Filters set on the query.
-
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
=
,<
,<=
,>
,>=
. Defaults to=
.
-
property
namespace
# This query’s namespace
-
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
- 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.