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

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( = {'!=': <Operator.NOT_EQUAL: 9>, '<': <Operator.LESS_THAN: 1>, '<=': <Operator.LESS_THAN_OR_EQUAL: 2>, '=': <Operator.EQUAL: 5>, '>': <Operator.GREATER_THAN: 3>, '>=': <Operator.GREATER_THAN_OR_EQUAL: 4>, 'IN': <Operator.IN: 6>, 'NOT_IN': <Operator.NOT_IN: 13> )

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

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

  • Parameters

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

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

Filter on a key.

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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月30日 UTC.