# Queries

2.25.0 (latest) 2.24.0 2.23.0 2.22.0 2.21.0 2.20.2 2.19.0 2.18.0 2.17.0 2.16.1 2.15.2 2.14.0 2.13.2 2.12.0 2.11.1 2.10.0 2.9.0 2.8.3 2.7.2 2.6.2 2.5.1 2.4.0 2.3.0 2.2.0 2.1.6 2.0.1 1.15.5 1.14.0 1.13.2 1.12.0 1.11.0 1.10.0 1.9.0 Create / interact with Google Cloud Datastore queries.

### *class* google.cloud.datastore.query.And(filters)

Bases: `google.cloud.datastore.query.BaseCompositeFilter`

Class representation of an AND Filter.

### *class* google.cloud.datastore.query.BaseCompositeFilter(operation=Operator.OPERATOR_UNSPECIFIED, filters=None)

Bases: `google.cloud.datastore.query.BaseFilter`

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

#### build_pb(container_pb=None)

Build the protobuf representation based on values in the Composite Filter.

### *class* google.cloud.datastore.query.BaseFilter()

Bases: [`abc.ABC`](https://docs.python.org/3/library/abc.html#abc.ABC)

Base class for Filters

#### *abstract* build_pb(container_pb=None)

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)

Bases: [`google.api_core.page_iterator.Iterator`](https://googleapis.dev/python/google-api-core/latest/page_iterator.html#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`](https://docs.cloud.google.com/python/docs/reference/datastore/latest/client#google.cloud.datastore.client.Client)) -- The client used to make a request.

  - **limit** ([*int*](https://docs.python.org/3/library/functions.html#int)) -- (Optional) Limit the number of results returned.

  - **offset** ([*int*](https://docs.python.org/3/library/functions.html#int)) -- (Optional) Offset used to begin a query.

  - **start_cursor** ([*bytes*](https://docs.python.org/3/library/stdtypes.html#bytes)) -- (Optional) Cursor to begin paging through
    query results.

  - **end_cursor** ([*bytes*](https://docs.python.org/3/library/stdtypes.html#bytes)) -- (Optional) Cursor to end paging through
    query results.

  - **eventual** ([*bool*](https://docs.python.org/3/library/functions.html#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`](https://googleapis.dev/python/google-api-core/latest/retry.html#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*](https://docs.python.org/3/library/functions.html#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.ExplainMetric* )

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)

Bases: `google.cloud.datastore.query.BaseCompositeFilter`

Class representation of an OR Filter.

### *class* google.cloud.datastore.query.PropertyFilter(property_name, operator, value)

Bases: `google.cloud.datastore.query.BaseFilter`

Class representation of a Property Filter

#### build_pb(container_pb=None)

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)

Bases: [`object`](https://docs.python.org/3/library/functions.html#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`](https://docs.cloud.google.com/python/docs/reference/datastore/latest/client#google.cloud.datastore.client.Client)) -- The client used to connect to Datastore.

  - **kind** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) -- The kind to query.

  - **project** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) -- (Optional) The project associated with the query. If not passed, uses
    the client's value.

  - **namespace** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) -- (Optional) The namespace to which to restrict results. If not passed,
    uses the client's value.

  - **ancestor** ([`Key`](https://docs.cloud.google.com/python/docs/reference/datastore/latest/keys#google.cloud.datastore.key.Key)) -- (Optional) key of the ancestor to which this query's results are
    restricted.

  - **filters** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[* [*str*](https://docs.python.org/3/library/stdtypes.html#str)*, \*\[* str*\](<https://docs.python.org/3/library/stdtypes.html#str>)* , *\[* str*\](<https://docs.python.org/3/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.

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

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*](https://docs.python.org/3/library/stdtypes.html#str)) -- A property name.

  - **operator** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) -- One of `=`, `<`, `<=`, `>`, `>=`, `!=`, `IN`, `NOT_IN`.

  - **value** ([`int`](https://docs.python.org/3/library/functions.html#int), [`str`](https://docs.python.org/3/library/stdtypes.html#str), [`bool`](https://docs.python.org/3/library/functions.html#bool),
    [`float`](https://docs.python.org/3/library/functions.html#float), `NoneType`,
    [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime),
    [`google.cloud.datastore.key.Key`](https://docs.cloud.google.com/python/docs/reference/datastore/latest/keys#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`](https://docs.python.org/3/library/exceptions.html#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`](https://docs.cloud.google.com/python/docs/reference/datastore/latest/keys#google.cloud.datastore.key.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(filter=PropertyFilter('name', '=', 'Sally')).fetch())
    >>> result
    [<Entity('Person', 2345) {'name': 'Sally'}>]

- **Parameters**

  - **limit** ([*int*](https://docs.python.org/3/library/functions.html#int)) -- (Optional) limit passed through to the iterator.

  - **offset** ([*int*](https://docs.python.org/3/library/functions.html#int)) -- (Optional) offset passed through to the iterator.

  - **start_cursor** ([*bytes*](https://docs.python.org/3/library/stdtypes.html#bytes)) -- (Optional) cursor passed through to the iterator.

  - **end_cursor** ([*bytes*](https://docs.python.org/3/library/stdtypes.html#bytes)) -- (Optional) cursor passed through to the iterator.

  - **client** ([`google.cloud.datastore.client.Client`](https://docs.cloud.google.com/python/docs/reference/datastore/latest/client#google.cloud.datastore.client.Client)) -- (Optional) client used to connect to datastore.
    If not supplied, uses the query's value.

  - **eventual** ([*bool*](https://docs.python.org/3/library/functions.html#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`](https://googleapis.dev/python/google-api-core/latest/retry.html#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*](https://docs.python.org/3/library/functions.html#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](https://docs.python.org/3/library/stdtypes.html#tuple)\[[str](https://docs.python.org/3/library/stdtypes.html#str), [str](https://docs.python.org/3/library/stdtypes.html#str), [str](https://docs.python.org/3/library/stdtypes.html#str)\]
- **Returns**

  The filters set on the query. The sequence is
  `(property_name, operator, value)`.

#### key_filter(key, operator='=')

Filter on a key.

- **Parameters**

  - **key** ([`google.cloud.datastore.key.Key`](https://docs.cloud.google.com/python/docs/reference/datastore/latest/keys#google.cloud.datastore.key.Key)) -- The key to filter on.

  - **operator** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) -- (Optional) One of `=`, `<`, `<=`, `>`, `>=`, `!=`, `IN`, `NOT_IN`.
    Defaults to `=`.

#### keys_only()

Set the projection to include only keys.

#### *property* kind()

Get the Kind of the Query.

- **Return type**

  [str](https://docs.python.org/3/library/stdtypes.html#str)
- **Returns**

  The kind for the query.

#### *property* namespace()

This query's namespace

- **Return type**

  [str](https://docs.python.org/3/library/stdtypes.html#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](https://docs.python.org/3/library/stdtypes.html#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.