Query
(
client
,
kind
=
None
,
project
=
None
,
namespace
=
None
,
ancestor
=
None
,
filters
=
(),
projection
=
(),
order
=
(),
distinct_on
=
(),
)
A Query against the Cloud Datastore.
This class serves as an abstraction for creating a query over data stored in the Cloud Datastore.
Parameters
| Name | Description |
| 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 |
| projection | sequence of string
fields returned as part of query results. |
| order | sequence of string
field names used to order query results. Prepend |
| distinct_on | sequence of string
field names used to group query results. |
Inheritance
builtins.object > QueryProperties
ancestor
The ancestor key for the query.
| Type | Description |
| Key or None | The ancestor for the query. |
distinct_on
Names of fields used to group query results.
| Type | Description |
| sequence of string | The "distinct on" fields set on the query. |
filters
Filters set on the query.
| Type | Description |
| tuple[str, str, str] | The filters set on the query. The sequence is ``(property_name, operator, value)``. |
kind
Get the Kind of the Query.
| Type | Description |
|---|---|
| str | The kind for the query. |
namespace
This query's namespace
| Type | Description |
| str or None | the namespace assigned to this query |
order
Names of fields used to sort query results.
| Type | Description |
| sequence of string | The order(s) set on the query. |
project
Get the project for this Query.
| Type | Description |
| str | The project for the query. |
projection
Fields names returned by the query.
| Type | Description |
| sequence of string | Names of fields in query results. |
Methods
add_filter
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('
where property is a property stored on the entity in the datastore
and operator is one of OPERATORS
(ie, =
, <
, <=
, >
, >=
):
.. testsetup:: query-filter
import uuid
from google.cloud import datastore
client = datastore.Client()
.. doctest:: query-filter
>>> query = client.query(kind='Person')
>>> query = query.add_filter('name', '=', 'James')
>>> query = query.add_filter('age', '>', 50)
| Name | Description |
| property_name | str
A property name. |
| operator | str
One of |
| value | `int`, `str`, `bool`, `float`, `NoneType`, `datetime.datetime`, Key
The value to filter on. |
| Type | Description |
| `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). |
| Type | Description |
|---|---|
| Query | A query object. |
fetch
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:
.. testsetup:: query-fetch
import uuid
from google.cloud import datastore
unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))
.. doctest:: query-fetch
>>> 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'}>]
.. testcleanup:: query-fetch
client.delete(andy.key)
client.delete(sally.key)
client.delete(bobby.key)
| Name | Description |
| 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 | 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 |
| timeout | float
Time, in seconds, to wait for the request to complete. Note that if |
| Type | Description |
| `Iterator` | The iterator for the query. |
key_filter
key_filter
(
key
,
operator
=
"="
)
Filter on a key.
| Name | Description |
| key | Key
The key to filter on. |
| operator | str
(Optional) One of |
keys_only
keys_only
()
Set the projection to include only keys.
