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
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);
// Key employeeKey = ...; Entity employee = datastore.get(employeeKey);
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
Given an entity's key, you can delete the entity with the
// 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.
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.