Data objects in Datastore are known asentities, each of which is categorizedunder a particularkind for the purpose of queries. Forinstance, if you are writing a human resources application you might representeach employee with an entity of kindEmployee. Note that the entity datavalues are in the form ofproperties.For more information about entities, see the documentation onancestor paths andtransactions.

Creating entities and setting properties

You create an entity and set by calling the constructor method for its model class. SeeCreating and Using Entity Model Classesfor 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 thatthe entity disappears when the process terminates, so you must also persist theentity to Datastore, by callingput(), as follows:

sandy_key=sandy.put()

Notice that this returns a key that you can use forretrieving the entity from Datastorelater.

Set properties by using one of the following options:

• Specify the entity's properties to the constructor with keyword arguments:
  sandy=Account(username='Sandy',userid=123,email='sandy@example.com')

• Set properties manually after entity creation:
  sandy=Account()sandy.username='Sandy'sandy.userid=123sandy.email='sandy@example.com'

• Use thepopulate() convenience method to set several properties in oneoperation:
  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 thiscase,StringProperty andIntegerProperty) 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 fromDatastore:

sandy=sandy_key.get()

The Key methodskind() andid() recover the entity's kind and identifierfrom 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 forembedding in a URL:

url_string=sandy_key.urlsafe()

This produces a result likeagVoZWxsb3IPCxIHQWNjb3VudBiZiwIM which can laterbe 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 easilybe 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 asemail addresses as entity identifiers. A possible solution wouldbe to use a hash of the sensitive data as the identifier.This stops third parties, who can see the encrypted keys, from usingthem to harvest email addresses, though it doesn't stop them fromindependently generating their own hash of a known email address andusing it to check whether that address is present in Datastore.

Updating entities

To update an existing entity, retrieve it from Datastore,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 byput() in this case, since an entity keydoesn't change when you update it.

Deleting entities

When an entity is no longer needed, you can remove it fromDatastore with the key'sdelete() method:

sandy.key.delete()

Note that this is an operation on the key, not on the entity itself. It alwaysreturnsNone.

Deleting entities in bulk

If you need to delete a large number of entities, we recommendusingDataflow to delete entities in bulk.

Using batch operations

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

In the above code, you pass a list of key objects tondb.get_multi to fetchmultiple entities in a batch;ndb.get_multi returns a list of entity objects,withNone values for keys that do not have a corresponding entity inDatastore. Getting the entities in this way results infewer calls to Datastore for the entire batch. (The number ofcalls per batch depends on your batch size settings.)