A key has several components:
- a path describing a parent-child relationship between the entity and another entity
- the kind of the entity
- and either a name assigned to the entity by the application or a numeric ID assigned by the datastore.
Every entity has an identifier. An application can assign its own identifier for use in the key by giving the instance constructor a key_name argument (a str value):
s = Story(key_name="xzy123")
A key_name is stored as a Unicode string (with str values converted as ASCII text). A key_name must not start with a number, and must not be of the form * (start and end with two underscores). If your application uses user-submitted data as datastore entity key names (such as an email address), the application should sanitize the value first, such as by prefixing it with a known string, to meet these requirements.
If a key_name is not specified, the entity is assigned a numeric ID when it is first stored in the datastore. Once the entity has been created, its ID or name cannot be changed.
Key names and IDs are not property values. However, you can perform a limited set of queries on keys by referring to the special property name key. If all entities have the same kind and parent, filters and sort orders can be applied to the key names or IDs.
Every entity belongs to an entity group, a set of one or more entities that can be manipulated in a single transaction. Entity group relationships tell App Engine to store several entities in the same part of the distributed network. A transaction sets up datastore operations for an entity group, and all of the operations are applied as a group, or not at all if the transaction fails.
When the application creates an entity, it can assign another entity as the parent of the new entity. Assigning a parent to a new entity puts the new entity in the same entity group as the parent entity.
An entity without a parent is a root entity. An entity that is a parent for another entity can also have a parent. A chain of parent entities from an entity up to the root is the path for the entity, and members of the path are the entity's ancestors. The parent of an entity is defined when the entity is created, and cannot be changed later.
Every entity with a given root entity as an ancestor is in the same entity group. All entities in a group are stored in the same datastore node. A single transaction can modify multiple entities in a single group, or add new entities to the group by making the new entity's parent an existing entity in the group.
If an entity that is an ancestor of another entity is deleted, the descendant entity is not deleted. The descendant entity is still accessible using its complete Key or path.
You can create an entity with an ancestor path without first creating the parent entity. To do so, you create a Key for the ancestor using a kind and key name, then use it as the parent of the new entity. All entities with the same root ancestor belong to the same entity group, whether or not the root of the path represents an actual entity.
Tips for using entity groups:
- Only use entity groups when they are needed for transactions. For other relationships between entities, use ReferenceProperty properties and Key values, which can be used in queries.
- The more entity groups your application has—that is, the more root entities there are—the more efficiently the datastore can distribute the entity groups across datastore nodes. Better distribution improves the performance of creating and updating data. Also, multiple users attempting to update entities in the same entity group at the same time will cause some users to retry their transactions, possibly causing some to fail to commit changes. Do not put all of the application's entities under one root.
- A good rule of thumb for entity groups is that they should be about the size of a single user's worth of data or smaller.
- Entity groups do not have a significant impact on the speed of queries.