Each entity in Datastore has a key that uniquely identifies it. The key consists of the following components:
- The namespace of the entity, which allows for multitenancy
- The kind of the entity, which categorizes it for the purpose of Datastore queries
- An optional ancestor path locating the entity within the Datastore hierarchy.
An identifier for the individual entity, which can be either
- a key name string
- an integer numeric ID
Because the identifier is part of the entity's key, the identifier is associated permanently with the entity and cannot be changed. You assign the identifier in either of two ways:
- Specify your own key name string for the entity.
- Let Datastore automatically assign the entity an integer numeric ID.
Specifying a key name for an entity
To assign a key name to an entity, provide the name as the second argument to the constructor when you create the entity:
Entity employee = new Entity("Employee", "asalieri");
To let Datastore assign a numeric ID automatically, omit this argument:
Entity employee = new Entity("Employee");
You can configure Datastore to generate auto IDs using two different auto id policies:
defaultpolicy generates a random sequence of unused IDs that are approximately uniformly distributed. Each ID can be up to 16 decimal digits long.
legacypolicy creates a sequence of non-consecutive smaller integer IDs.
If you want to display the entity IDs to the user, and/or depend upon their order, the best thing to do is use manual allocation.
Using ancestor paths
Entities in Cloud Datastore form a hierarchically structured space similar to the directory structure of a file system. When you create an entity, you can optionally designate another entity as its parent; the new entity is a child of the parent entity (note that unlike in a file system, the parent entity need not actually exist). An entity without a parent is a root entity. The association between an entity and its parent is permanent, and cannot be changed once the entity is created. Cloud Datastore will never assign the same numeric ID to two entities with the same parent, or to two root entities (those without a parent).
An entity's parent, parent's parent, and so on recursively, are its ancestors; its children, children's children, and so on, are its descendants. A root entity and all of its descendants belong to the same entity group. The sequence of entities beginning with a root entity and proceeding from parent to child, leading to a given entity, constitute that entity's ancestor path. The complete key identifying the entity consists of a sequence of kind-identifier pairs specifying its ancestor path and terminating with those of the entity itself:
[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]
For a root entity, the ancestor path is empty and the key consists solely of the entity's own kind and identifier:
This concept is illustrated by the following diagram:
To designate an entity's parent, provide the parent entity's key as an argument
constructor when creating the child entity. You can get the key by calling the
Entity employee = new Entity("Employee"); datastore.put(employee); Entity address = new Entity("Address", employee.getKey()); datastore.put(address);
If the new entity also has a key name, provide the key name as the second
argument to the
Entity() constructor and the key of the parent entity as the
Entity address = new Entity("Address", "addr1", employee.getKey());
Applications can use the class
KeyFactory to create a
Key object for an entity from known components, such as the entity's kind and identifier. For an entity with no parent, pass the kind and identifier (either a key name string or a numeric ID) to the static method
KeyFactory.createKey() to create the key. The following examples create a key for an entity of kind
Person with key name
"GreatGrandpa" or numeric ID
Key k1 = KeyFactory.createKey("Person", "GreatGrandpa"); Key k2 = KeyFactory.createKey("Person", 74219);
If the key includes a path component, you can use the helper class
KeyFactory.Builder to build the path. This class's
addChild method adds a single entity to the path and returns the builder itself, so you can chain together a series of calls, beginning with the root entity, to build up the path one entity at a time. After building the complete path, call
getKey to retrieve the resulting key:
Key k = new KeyFactory.Builder("Person", "GreatGrandpa") .addChild("Person", "Grandpa") .addChild("Person", "Dad") .addChild("Person", "Me") .getKey();
String personKeyStr = KeyFactory.keyToString(k); // Some time later (for example, after using personKeyStr in a link). Key personKey = KeyFactory.stringToKey(personKeyStr); Entity person = datastore.get(personKey);
The string representation of a key is "web-safe": it does not contain characters considered special in HTML or in URLs.