Creating, Retrieving, Updating, and Deleting Entities

Data objects in Google 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 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 datstore 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:

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

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

datastore.put(employee);

Note that if you don't provide a key name, Cloud 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 Cloud Datastore with every call to put().

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

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 Cloud Datastore Admin page
  2. If you have not already enabled Cloud 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 use the batch operations if you want to operate on multiple entities in a single Cloud 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.