Entity Groups, Ancestors and Paths

• 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.

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.
  
  グループはトランザクションのため
  データの関連づけには　ReferenceProperty と Key を使う
  

class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)

A reference to another model instance. For example, a reference may indicate a many-to-one relationship between the model with the property and the model referenced by the property.

reference_class is the model class of the model instance being referenced. If specified, only model instances of the class can be assigned to this property. If None, any model instance can be the value of this property.

collection_name is the name of the property to give to the referenced model class whose value is a Query for all entities that reference the entity. If no collection_name is set, then modelname_set (with the name of the model in lowercase letters and "_set" added) is used.

ReferenceProperty automatically references and dereferences model instances as property values: A model instance can be assigned to a ReferenceProperty directly, and its key will be used. The ReferenceProperty value can be used as if it were a model instance, and the datastore entity will be fetched and the model instance created when it is first used in this way. Untouched reference properties do not query for unneeded data.

class Author(db.Model):
name = db.StringProperty()

class Story(db.Model):
author = db.ReferenceProperty(Author)

story = db.get(story_key)
author_name = story.author.name

As with a Key value, it is possible for a reference property value to refer to a data entity that does not exist. If a referenced entity is deleted from the datastore, references to the entity are not updated. An application can explicitly db.get() the value of a ReferenceProperty (which is a Key) to test whether the referenced entity exists.

Deleting an entity does not delete entities referred to by a ReferenceProperty.

See also this introduction to reference properties.

Value type: db.Key (see above)

Introduction to reference properties.
http://code.google.com/appengine/docs/datastore/entitiesandmodels.html#References

References

A property value can contain the key of another entity. The value is a Key instance.

# To fetch and iterate over every SecondModel entity that refers to the
# FirstModel instance obj1:
for obj in obj1.firstmodel_set:
 # ...

The name of the back-reference property defaults to modelname_set (with the name of the model class in lowercase letters, and "_set" added to the end), and can be adjusted using the collection_name argument to the ReferenceProperty constructor.

Automatic referencing and dereferencing of model instances, type checking and back-references are only available using the ReferenceProperty model property class. Keys stored as values of Expando dynamic properties or ListProperty values do not have these features.

http://groups.google.com/group/google-appengine/browse_thread/thread/e9464ceb131c726f?hl=en
http://blog.arbingersys.com/2008/04/google-app-engine-better-many-to-many.html

http://cluebin.appspot.com/pasted/25

• 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.