Creating, Retrieving, Updating, and Deleting Entities

Data objects in Cloud Datastore are known as entities, each of which is categorized under a particular kind for the purpose of queries. For instance, if you are writing a human resources application you might represent each employee with an entity of kind Employee. Note that the entity data values are in the form of properties. For more information about entities, see the documentation on ancestor paths and transactions.

Creating entities and setting properties

You create an entity and set by calling the constructor method for its model class. See Creating and Using Entity Model Classes for information on creating an entity model class.

The following example shows how to invoke a model class constructor with keyword arguments:

sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')

This code creates an object in your program's main memory. However, note that the entity disappears when the process terminates, so you must also persist the entity to Cloud Datastore, by calling put(), as follows:

sandy_key = sandy.put()

Notice that this returns a key that you can use for retrieving the entity from the data store later:

Note that you don't have to set properties in the constructor. You could set properties using any of the options in the following table:

Using the Constructor

You can specify the entity's properties to the constructor with keyword arguments:

sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')

Set Manually Post-Creation

You can set properties manually after entity creation:

sandy = Account()
sandy.username = 'Sandy'
sandy.userid = 123
sandy.email = 'sandy@example.com'

Using populate()

You can use the convenience method populate() if you want to set several properties in one operation:

sandy = Account()
sandy.populate(
    username='Sandy',
    userid=123,
    email='sandy@gmail.com')

However you choose to set the entity's properties, the property types (in this case, StringProperty and IntegerProperty) enforce type checking.

For example:

bad = Account(
    username='Sandy', userid='not integer')  # raises an exception
...
sandy.username = 42  # raises an exception

Retrieving Entities from Keys

If you have an entity's key, you can retrieve the entity from the data store:

sandy = sandy_key.get()

The Key methods kind() and id() recover the entity's kind and identifier from the key:

kind_string = sandy_key.kind()  # returns 'Account'
ident = sandy_key.id()  # returns '2'

You can also use an entity's key to obtain an encoded string suitable for embedding in a URL:

url_string = sandy_key.urlsafe()

This produces a result like agVoZWxsb3IPCxIHQWNjb3VudBiZiwIM which can later be used to reconstruct the key and retrieve the original entity:

sandy_key = ndb.Key(urlsafe=url_string)
sandy = sandy_key.get()

Notice that the URL-safe string looks cryptic, but it is not encrypted! It can easily be decoded to recover the original entity's kind and identifier:

key = Key(urlsafe=url_string)
kind_string = key.kind()
ident = key.id()

If you use such URL-safe keys, don't use sensitive data such as email addresses as entity identifiers. A possible solution would be to use the MD5 hash of the sensitive data as the identifier. This stops third parties, who can see the encrypted keys, from using them to harvest email addresses, though it doesn't stop them from independently generating their own hash of a known email address and using it to check whether that address is present in the data store.

Updating entities

To update an existing entity, retrieve it from the data store, modify its properties, and store it back again:

sandy = key.get()
sandy.email = 'sandy@example.co.uk'
sandy.put()

You can ignore the value returned by put() in this case, since an entity key doesn't change when you update it.)

Deleting entities

When an entity is no longer needed, you can remove it from the data store with the key's delete() method:

sandy.key.delete()

Note that this is an operation on the key, not on the entity itself. It always returns None.

Deleting entities in bulk

You can use the Cloud Platform Console to delete all entities of a given kind, or all entities of all kinds, in the default namespace:

  1. Go to the Cloud Datastore Admin page:
    Go to the Datastore Admin page
  2. If you have not already enabled Datastore Admin functionality, click Enable Datastore Admin.
  3. Select the entity kind(s) you want to delete.
  4. Click Delete Entities. Note that bulk deletion takes place within your application, and thus counts against your quota.

Using batch operations

You can process a collection of entities or keys in a single call rather than individually in separate calls, for example inside a loop. This results in a single remote procedure call (RPC) for the batch, rather than a separate RPC call for each entity.

The following code shows how you do this:

list_of_keys = ndb.put_multi(list_of_entities)
list_of_entities = ndb.get_multi(list_of_keys)
ndb.delete_multi(list_of_keys)

Send feedback about...