Python

0.02.2

Entities

Class for representing a single entity in the Cloud Datastore.

Entities are akin to rows in a relational database, storing the actual instance of data.

Each entity is officially represented with a gcloud.datastore.key.Key class, however it is possible that you might create an Entity with only a partial Key (that is, a Key with a Kind, and possibly a parent, but without an ID).

Entities in this API act like dictionaries with extras built in that allow you to delete or persist the data stored on the entity.

class gcloud.datastore.entity.Entity(dataset=None, kind=None, exclude_from_indexes=())

Bases: dict

Parameters:

• dataset (gcloud.datastore.dataset.Dataset) – The dataset in which this entity belongs.
• kind (string) – The kind of entity this is, akin to a table name in a relational database.

Entities are mutable and act like a subclass of a dictionary. This means you could take an existing entity and change the key to duplicate the object.

This can be used on its own, however it is likely easier to use the shortcut methods provided by gcloud.datastore.dataset.Dataset such as:

• gcloud.datastore.dataset.Dataset.entity() to create a new entity.

  >>> dataset.entity('MyEntityKind')
  <Entity[{'kind': 'MyEntityKind'}] {}>
  

• gcloud.datastore.dataset.Dataset.get_entity() to retrieve an existing entity.

  >>> dataset.get_entity(key)
  <Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>
  

You can the set values on the entity just like you would on any other dictionary.

>>> entity['age'] = 20
>>> entity['name'] = 'JJ'
>>> entity
<Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>

And you can cast an entity to a regular Python dictionary with the dict builtin:

>>> dict(entity)
{'age': 20, 'name': 'JJ'}

Note

When saving an entity to the backend, values which are “text” (‘unicode’ in Python2, ‘str’ in Python3) will be saved using the ‘text_value’ field, after being encoded to UTF-8. When retrieved from the back-end, such values will be decoded to “text” again. Values which are “bytes” (‘str’ in Python2, ‘bytes’ in Python3), will be saved using the ‘blob_value’ field, without any decoding / encoding step.

Parameters:

• dataset (gcloud.datastore.dataset.Dataset, or None) – the Dataset instance associated with this entity.
• kind (str) – the “kind” of the entity (see https://cloud.google.com/datastore/docs/concepts/entities#Datastore_Kinds_and_identifiers)
• exclude_from_indexes – names of fields whose values are not to be indexed for this entity.

dataset()

Get the dataset.Dataset in which this entity belongs.

Return type:gcloud.datastore.dataset.Dataset Returns:The Dataset containing the entity if there is a key, else None.

Note

This is based on the gcloud.datastore.key.Key set on the entity. That means that if you have no key set, the dataset might be None. It also means that if you change the key on the entity, this will refer to that key’s dataset.

delete()

Delete the entity in the Cloud Datastore.

Note

This is based entirely off of the gcloud.datastore.key.Key set on the entity. Whatever is stored remotely using the key on the entity will be deleted.

exclude_from_indexes()

Names of fields which are not to be indexed for this entity.

Return type:sequence of field names

classmethod from_key(key, dataset=None)

Create entity based on datastore.key.Key.

Note

This is a factory method.

Parameters:key (gcloud.datastore.key.Key) – The key for the entity. Returns:The Entity derived from the gcloud.datastore.key.Key.

key(key=None)

Get or set the datastore.key.Key on the current entity.

Parameters:key (glcouddatastore.key.Key) – The key you want to set on the entity. Return type:gcloud.datastore.key.Key or Entity. Returns:Either the current key (on get) or the current object (on set).

>>> entity.key(my_other_key)  # This returns the original entity.
<Entity[{'kind': 'OtherKeyKind', 'id': 1234}] {'property': 'value'}>
>>> entity.key()  # This returns the key.
<Key[{'kind': 'OtherKeyKind', 'id': 1234}]>

kind()

Get the kind of the current entity.

Note

This relies entirely on the gcloud.datastore.key.Key set on the entity. That means that we’re not storing the kind of the entity at all, just the properties and a pointer to a Key which knows its Kind.

reload()

Reloads the contents of this entity from the datastore.

This method takes the gcloud.datastore.key.Key, loads all properties from the Cloud Datastore, and sets the updated properties on the current object.

Warning

This will override any existing properties if a different value exists remotely, however it will not override any properties that exist only locally.

save()

Save the entity in the Cloud Datastore.

Note

Any existing properties for the entity will be replaced by those currently set on this instance. Already-stored properties which do not correspond to keys set on this instance will be removed from the datastore.

Note

Property values which are “text” (‘unicode’ in Python2, ‘str’ in Python3) map to ‘string_value’ in the datastore; values which are “bytes” (‘str’ in Python2, ‘bytes’ in Python3) map to ‘blob_value’.

Return type:gcloud.datastore.entity.Entity Returns:The entity with a possibly updated Key.

exception gcloud.datastore.entity.NoDataset

Bases: exceptions.RuntimeError

Exception raised by Entity methods which require a dataset.

exception gcloud.datastore.entity.NoKey

Bases: exceptions.RuntimeError

Exception raised by Entity methods which require a key.