Como criar, recuperar, atualizar e excluir entidades

Os objetos de dados no Datastore são conhecidos como entidades. Cada uma é categorizada como um tipo específico para fins de consultas. Por exemplo, se você estiver programando um aplicativo de recursos humanos, poderá representar cada funcionário com uma entidade do tipo Employee. Observe que os valores de dados de entidade estão na forma de propriedades. Para mais informações sobre entidades, consulte o documento conceitual Entidades, propriedades e chaves.

Como criar entidades e definir propriedades

Em Java, você constrói uma instância de classe Entity para criar uma nova entidade, fornecendo o tipo de entidade como um argumento para o construtor Entity(). Depois de preencher as propriedades da entidade, se necessário, salve-a no armazenamento de dados transferindo-a como um argumento para o método DatastoreService.put(). É possível especificar o nome da chave da entidade passando-o como o segundo argumento para o construtor.

O exemplo a seguir cria uma entidade do tipo Employee, preenche os valores da propriedade e a salva no armazenamento de dados:

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
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);

Se você não fornecer um nome de chave, o Datastore gerará automaticamente um ID numérico para a chave da entidade:

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
Entity employee = new Entity("Employee");
// Set the entity properties.
// ...
datastore.put(employee);

Como recuperar entidades

Para recuperar uma entidade identificada por determinada chave, transmita o objeto Key para o método DatastoreService.get():

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
// Key employeeKey = ...;
Entity employee = datastore.get(employeeKey);

Como atualizar entidades

Para atualizar uma entidade atual, modifique os atributos do objeto Entity e, em seguida, transmita-o para o método DatastoreService.put(). Os dados do objeto sobrescrevem a entidade atual. O objeto inteiro é enviado ao Datastore com todas as chamadas para put().

Como excluir entidades

Com a chave de uma entidade, é possível excluir a entidade usando o método DatastoreService.delete():

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
// Key employeeKey = ...;
datastore.delete(employeeKey);

Como excluir entidades em massa

Se você precisar excluir um grande número de entidades, recomendamos usar o Dataflow para excluir entidades em massa.

Como usar operações em lote

Use as operações em lote se quiser operar em várias entidades em uma única chamada do Datastore.

Veja um exemplo de chamada em lote:

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
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);

Essas operações em lote agrupam todas as entidades ou chaves por grupo de entidades e, em seguida, executam a operação solicitada em cada grupo de entidades em paralelo, o que é mais rápido do que fazer chamadas separadas para cada entidade, porque elas geram sobrecarga para apenas uma chamada de serviço. Se o lote usa múltiplos grupos de entidades, o trabalho referente a todos os grupos é feito em paralelo no lado do servidor.

Uma chamada put() ou delete() em lote pode ser bem-sucedida para algumas entidades, mas não para outras. Se for importante que a chamada tenha êxito total ou falhe completamente, use uma transação com todas as entidades afetadas no mesmo grupo de entidades.