Python

0.4.1

Queries

Create / interact with gcloud datastore queries.

class gcloud.datastore.query.Iterator(query, connection, limit=None, offset=0, start_cursor=None, end_cursor=None)

Bases: object

Represent the state of a given execution of a Query.

next_page()

Fetch a single “page” of query results.

Low-level API for fine control: the more convenient API is to iterate on the current Iterator.

Return type:tuple, (entities, more_results, cursor)

class gcloud.datastore.query.Query(dataset_id=None, kind=None, namespace=None, ancestor=None, filters=(), projection=(), order=(), group_by=())

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:

• kind (string) – The kind to query.
• dataset_id (string) – The ID of the dataset to query. If not passed, uses the implicit default.
• namespace (string or None) – The namespace to which to restrict results.
• ancestor (gcloud.datastore.key.Key or None) – key of the ancestor to which this query’s results are restricted.
• filters (sequence of (property_name, operator, value) tuples) – property filters applied by this query.
• 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.
• group_by (sequence of string) – field names used to group query results.

Raises:

ValueError if dataset_id is not passed and no implicit default is set.

OPERATORS = {'<': 1, '=': 5, '>': 3, '<=': 2, '>=': 4}

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

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

Parameters:

• property_name (string) – A property name.
• operator (string) – One of =, <, <=, >, >=.
• value (integer, string, boolean, float, None, datetime) – The value to filter on.

Raises:

ValueError if operation is not one of the specified values, or if a filter names '__key__' but passes invalid operator (== is required) or value (a key is required).

ancestor

The ancestor key for the query.

Return type:Key or None

dataset_id

Get the dataset ID for this Query.

Return type:str

fetch(limit=None, offset=0, start_cursor=None, end_cursor=None, connection=None)

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

For example:

>>> from gcloud.datastore.query import Query
>>> query = Query('dataset-id', 'Person')
>>> query.add_filter('name', '=', 'Sally')
>>> list(query.fetch())
[<Entity object>, <Entity object>, ...]
>>> list(query.fetch(1))
[<Entity object>]

Parameters:

• limit (integer or None) – An optional limit passed through to the iterator.
• offset (integer) – An optional offset passed through to the iterator.
• start_cursor (bytes) – An optional cursor passed through to the iterator.
• end_cursor (bytes) – An optional cursor passed through to the iterator.
• connection (gcloud.datastore.connection.Connection) – An optional cursor passed through to the iterator. If not supplied, uses the implicit default.

Return type:

Iterator

Raises:

ValueError if connection is not passed and no implicit default has been set.

filters

Filters set on the query.

Return type:sequence of (property_name, operator, value) tuples.

group_by

Names of fields used to group query results.

Return type:sequence of string

keys_only()

Set the projection to include only keys.

kind

Get the Kind of the Query.

Return type:string

namespace

This query’s namespace

Return type:string or None Returns:the namespace assigned to this query

order

Names of fields used to sort query results.

Return type:sequence of string

projection

Fields names returned by the query.

Return type:sequence of string Returns:Names of fields in query results.