Class Query (2.11.1)

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 datastored 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`(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.

Properties

ancestor

The ancestor key for the query.

Returns
Type	Description
`Key or None`	The ancestor for the query.

distinct_on

Names of fields used to group query results.

Returns
Type	Description
`sequence of string`	The "distinct on" fields set on the query.

filters

Filters set on the query.

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

Returns
Type	Description
`str`	The kind for the query.

namespace

This query's namespace

Returns
Type	Description
`str or None`	the namespace assigned to this query

order

Names of fields used to sort query results.

Returns
Type	Description
`sequence of string`	The order(s) set on the query.

project

Get the project for this Query.

Returns
Type	Description
`str`	The project for the query.

projection

Fields names returned by the query.

Returns
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 datastoreand operator is one ofOPERATORS(ie,=,<,<=,>,>=,!=,IN,NOT_IN):

.. testsetup:: query-filter

import uuidfrom google.cloud importdatastoreclient =datastore.Client()

.. doctest:: query-filter

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

Parameters
Name	Description
`property_name`	`str` A property name.
`operator`	`str` One of`=`,`<`,`<=`,`>`,`>=`,`!=`,`IN`,`NOT_IN`.
`value`	`int,str,bool,float,NoneType,datetime.datetime,Key` The value to filter on.

Exceptions
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).

Returns
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,read_time=None,)

Execute the Query; return an iterator for the matching entities.

For example:

.. testsetup:: query-fetch

import uuidfrom google.cloud importdatastoreunique = 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)

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

Returns
Type	Description
`Iterator`	The iterator for the query.

key_filter

key_filter(key,operator="=")

Filter on a key.

Parameters
Name	Description
`key`	`Key` The key to filter on.
`operator`	`str` (Optional) One of`=`,`<`,`<=`,`>`,`>=`,`!=`,`IN`,`NOT_IN`. Defaults to`=`.

keys_only

keys_only()

Set the projection to include only keys.

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

Last updated 2025-12-16 UTC.

Movatterモバイル変換

Class Query (2.11.1) Stay organized with collections Save and categorize content based on your preferences.

Parameters