GAE Datastore: Entity, Keys and Properties

Entity = an object in the data store

An object in the
datastore is known as an entity.
An entity has a key that uniquely identifies the object across the entire system. If you
have a key, you can fetch the entity for the key quickly. Keys can be stored as data in
entities, such as to create a reference from one entity to another. A key has several parts,
some of which we'll discuss here and some of which we'll cover later.
One part of the key is the application's ID, which ensures that nothing else about the
key can collide with the entities of any other application. It also ensures that no other
app can access your app's data, and that your app cannot access data for other apps.
You won't see the app ID mentioned in the datastore API; this is automatic.
An important part of the key is the kind. An entity's kind categorizes the entity for the
purposes of queries, and for ensuring the uniqueness of the rest of the key. For example,
a shopping cart application might represent each customer order with an entity of the
kind "Order." The application specifies the kind when it creates the entity.
The key also contains an entity ID. This can be an arbitrary string specified by the app,
or it can be generated automatically by the datastore. The API calls an entity ID given
by the app a key name, and an entity ID generated by the datastore an ID. An entity
has either a key name or an ID, but not both.
App-assigned key names are strings, while system-assigned IDs are integers. Systemassigned
IDs are generally increasing, though they are not guaranteed to be monotonically
increasing. If you want a strictly increasing ID, you must maintain this yourself
in a transaction. See Chapter 6. If you purposefully do not want an increasing ID, such
as to avoid exposing data sizes to users, you can either generate your own key name,
or allow the system to generate a numeric ID, then encrypt and store it with other data.
Once an entity has been created, its key cannot be changed. This applies to all parts of
its key, including the kind and the key name or ID.
The data for the entity is stored in one or more properties. Each property has a name
and at least one value. Each value is of one of several supported data types, such as a
string, an integer, a date-time, or a null value. We'll look at property value types in
detail later in this chapter.
A property can have multiple values, and each value can be of a different type. As you
will see in "Multivalued Properties" on page 127, multivalued properties have unusual
behavior, but are quite useful for modeling some kinds of data, and surprisingly efficient.
118 | Chapter 4: Datastore Entities
It's tempting to compare these concepts with similar concepts in relational
databases: kinds are tables; entities are rows; properties are fields
or columns. That's a useful comparison, but watch out for differences.
Unlike a table in a relational database, there is no relationship between
an entity's kind and its properties. Two entities of the same kind can
have different properties set or not set, and can each have a property of
the same name but with values of different types. You can (and often
will) enforce a data schema in your own code, and App Engine includes
libraries to make this easy, but this is not required by the datastore.
Also unlike relational databases, keys are not properties. You can perform
queries on key names just like properties, but you cannot change
a key name after the entity has been created.
And of course, a relational database cannot store multiple values in a
single cell, while an App Engine property can have multiple values.