Creating, Retrieving, Updating, and Deleting Entities

Data objects in 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 concept document Entities, Properties, and Keys.

Creating entities and setting properties

In Java, you create a new entity by constructing an instance of class Entity, supplying the entity's kind as an argument to the Entity() constructor. After populating the entity's properties if necessary, you save it to the datastore by passing it as an argument to the DatastoreService.put() method. You can specify the entity's key name by passing it as the second argument to the constructor.

The following example creates an entity of kind Employee, populates its property values, and saves it to data store:

Entity employee = new Entity("Employee", "asalieri");
employee.setProperty("firstName", "Antonio");
employee.setProperty("lastName", "Salieri");
employee.setProperty("hireDate", new Date());
employee.setProperty("attendedHrTraining", true);

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
datastore.put(employee);

Note that if you don't provide a key name, Datastore automatically generates a numeric ID for the entity's key:

Entity employee = new Entity("Employee");
// Set the entity properties.
// ...
datastore.put(employee);

Retrieving entities

To retrieve an entity identified by a given key, pass the Key object to the DatastoreService.get() method:

// Key employeeKey = ...;
Entity employee = datastore.get(employeeKey);

Updating entities

To update an existing entity, modify the attributes of the Entity object, then pass it to the DatastoreService.put() method. The object data overwrites the existing entity. The entire object is sent to Datastore with every call to put().

Entity employee = new Entity("Employee", "asalieri");
employee.setProperty("firstName", "Antonio");
employee.setProperty("lastName", "Salieri");
employee.setProperty("hireDate", new Date());
employee.setProperty("attendedHrTraining", true);

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
datastore.put(employee);

Deleting entities

Given an entity's key, you can delete the entity with the DatastoreService.delete() method:

// Key employeeKey = ...;
datastore.delete(employeeKey);

Deleting entities in bulk

If you need to delete a large number of entities, we recommend using Dataflow to delete entities in bulk.

Using batch operations

You can use the batch operations if you want to operate on multiple entities in a single Datastore call.

Here is an example of a batch call:

Entity employee1 = new Entity("Employee");
Entity employee2 = new Entity("Employee");
Entity employee3 = new Entity("Employee");
// ...

List<Entity> employees = Arrays.asList(employee1, employee2, employee3);
datastore.put(employees);

These batch operations group all the entities or keys by entity group and then perform the requested operation on each entity group in parallel, which is faster than making separate calls for each individual entity because they incur the overhead for only one service call. If the batch uses multiple entity groups, the work for all groups is done in parallel on the server side.

A batch put() or delete() call may succeed for some entities but not others. If it is important that the call succeed completely or fail completely, use a transaction with all affected entities in the same entity group.