Datastore Entity

Base class for the entity model

class datastore_entity.datastore_entity.DatastoreEntity(**kwargs)

Bases: object

A base class representing a Google Cloud Datastore entity. This gives you useful ORM features while interacting with the Datastore service.

Google Cloud Datastore is a NoSQL key/value store that provides SQL-like functionalities(eg querying using a ‘table’ name) A datastore entity belonging to a ‘table’(ie a kind) can have varying column number, varying datatypes per columns.

This class also provides useful operations while protecting the user from common mistakes.

It helps you to specify your properties in a way that avoids common mistakes(eg. misspelling property name) while still allowing you to take full advantage of the flexibility datastore provides.

See more examples here: https://www.aloudinthecloud.com/orm-patterns-with-google-cloud-firestore-in-datastore-mode.html

>>> from datastore_entity import DatastoreEntity
>>> class User(DatastoreEntity): 
...    pass
...    # properties/attributes go here
...

Parameters

• namespace (str) – (Optional) datastore namespace to connect to

• service_account_json_path (str) – (Optional) path to service account file

• conn (boolean) – whether to connect when initializing model. Useful for testing or for deferring connection

Raises

class

ValueError if __kind__ is not provided

allocate_ids(incomplete_key, num_ids)

Calls Datastore’s allocate_id() to allocate a list of datastore IDs that is guaranteed to be unique.

Parameters

• incomplete_key – A partial datastore key as base for allocated IDs

• num_ids (int) – The number of IDs to allocate

Returns

the complete key

Return type

list of google.cloud.datastore.key.Key

connect(namespace=None, service_account_json_path=None)

Connect to datastore service. Useful when model is initialized without connection or you want to connect to a different namespace or connect using a different credential

Parameters

• namespace (str) – (Optional) datastore namespace to connect to

• service_account_json_path (str) – (Optional) path to service account file

Returns

boolean

delete()

Deletes an entity

Returns

boolean

find_by_key(key)

Performs a search for an entity using it’s key

Note: This returns the entity as-is, as opposed to returning it as a model instance

To retrieve the entity as a model instance use get_obj_with_key() method

Parameters

key – The datastore key

Returns

The datastore entity

Return type

class

google.cloud.datastore.entity.Entity

find_by_value(prop, val, comparator='=', limit=500)

Returns a list of entities meeting query requirements

Note: This returns the entity as-is, as opposed to returning it as a model instance

To retrieve the entity as a model instance use get_objects() method which also supports pagination

Parameters

• prop (str) – the entity property name

• val (any) – the entity propery value

• comparator (str) – the query operator(=,=< etc)

• limit (int) – the number of entities to fetch

Returns

one or more entities

Return type

list

find_via_parent_or_ancestor(parent_or_ancestor, limit=500)

Fetches entities using ancestor key

Parameters

• parent_or_ancestor – datastore ancestor key

• limit (int) – number of entities to fetch. max of 500

Returns

one or more entities

Return type

list

generate_key(path)

Parameters

path (list) – a list with key path in the format [‘kind’,’id’,…]

Returns

the generated datastore key

Return type

class

google.cloud.datastore.key.Key

get_client()

Return the datastore connection client

Returns

datastore connection client

get_obj(prop, value)

Fetches a single entity and populates the class attributes with the matching entity properties and values

returns object of the class with the entity KEY You can call this directly, or have your model wrap a method around this method passing in only the value(eg. obj.get(username))

Note that this is called only once

Parameters

• prop (str) – the name of entity property to used for the query

• value (int) – the value for the query

Returns

a class object representing the entity

get_obj_with_key(key)

Similar to get_obj(), but fetches entity using it’s key.

Fetching an entity using a key is strongly consistent so object is immediately available after saving it to datastore

Retrieves an entity and populates the class attributes with the matching entity properties and values

Parameters

key (datastore key) – the datastore key

Returns

an object representing the entity

Return type

class

datastore_entity.datastore_entity.DatastoreEntity

get_objects(prop, value, limit=500, paginate=False, cursor=None)

Fetches a given number of entities and populates the class attributes with the matching entity properties and values

Parameters

• prop (str) – the name of the entity property

• value (any. allowed datastore types) – the name of the property value

• limit (int) – the maximum number of entities to return. Datastore supports a maximum of 500

• cursor (str. representing a datastore cursor) – the ‘next’ cursor to be used to fetch next set of entities

Paginate

whether to return a cursor to be used for pagination

Returns

a two-element tuple. first element is a list of entity objects and the second is the cursor for pagination or None

Return type

tuple

save(id=None, parent_or_ancestor=None, extra_props=None, excludes=None)

Performs an ‘upsert’ operation on datastore if ‘id’ is provided.

Performs a new insert when ‘id’ is None

Parameters

• id (int or str) – the entity identifier. part of an entity’s key

• parent_or_ancestor (datastore key) – datastore key for entity’s parent or ancestor

• extra_props (dict) – an optional additional properties to add to entity not defined in model class

• exclude – a list of property names defined in the model class to exclude when saving an entity

Returns

boolean

DatastoreEntity.__kind__ = False

Required. Name of entity’s kind.

DatastoreEntity.__exclude_from_index__ = []

Optional. A list of properties to exclude from datastore indexes.