google.appengine.ext.ndb.key module

Summary

A Key encapsulates the following pieces of information, which together
uniquely designate a (possible) entity in the App Engine datastore:

an application id (a string)

a namespace (a string)

a list of one or more (kind, id) pairs where kind is a string and id
is either a string or an integer.

The application id must always be part of the key, but since most
applications can only access their own entities, it defaults to the
current application id and you rarely need to worry about it. It must
not be empty.

The namespace designates a top-level partition of the key space for a
particular application. If you’ve never heard of namespaces, you can
safely ignore this feature.

Most of the action is in the (kind, id) pairs. A key must have at
least one (kind, id) pair. The last (kind, id) pair gives the kind
and the id of the entity that the key refers to, the others merely
specify a ‘parent key’.

The kind is a string giving the name of the model class used to
represent the entity. (In more traditional databases this would be
the table name.) A model class is a Python class derived from
ndb.Model; see the documentation for ndb/model.py. Only the class
name itself is used as the kind. This means all your model classes
must be uniquely named within one application. You can override this
on a per-class basis.

The id is either a string or an integer. When the id is a string, the
application is in control of how it assigns ids: For example, if you
could use an email address as the id for Account entities.

To use integer ids, you must let the datastore choose a unique id for
an entity when it is first inserted into the datastore. You can set
the id to None to represent the key for an entity that hasn’t yet been
inserted into the datastore. The final key (including the assigned
id) will be returned after the entity is successfully inserted into
the datastore.

A key for which the id of the last (kind, id) pair is set to None is
called an incomplete key. Such keys can only be used to insert
entities into the datastore.

A key with exactly one (kind, id) pair is called a top level key or a
root key. Top level keys are also used as entity groups, which play a
role in transaction management.

If there is more than one (kind, id) pair, all but the last pair
represent the ‘ancestor path’, also known as the key of the ‘parent
entity’.

Other constraints:

Kinds and string ids must not be empty and must be at most 500 bytes
long (after UTF-8 encoding, if given as Python unicode objects).
NOTE: This is defined as a module level constant _MAX_KEYPART_BYTES.

Contents

For flexibility and convenience, multiple constructor signatures are
supported.

The primary way to construct a key is using positional arguments:
- Key(kind1, id1, kind2, id2, …).

This is shorthand for either of the following two longer forms:
- Key(pairs=[(kind1, id1), (kind2, id2), …])
- Key(flat=[kind1, id1, kind2, id2, …])

Either of the above constructor forms can additionally pass in another
key using parent=<key>. The (kind, id) pairs of the parent key are
inserted before the (kind, id) pairs passed explicitly.

You can also construct a Key from a ‘url-safe’ encoded string:
- Key(urlsafe=<string>)

For esoteric purposes the following constructors exist:
- Key(reference=<reference>) – passing in a low-level Reference object
- Key(serialized=<string>) – passing in a serialized low-level Reference
- Key(<dict>) – for unpickling, the same as Key(**<dict>)

The ‘url-safe’ string is really a websafe-base64-encoded serialized
Reference, but it’s best to think of it as just an opaque unique
string.

If a Reference is passed (using one of reference, serialized or
urlsafe), the args and namespace keywords must match what is already
present in the Reference (after decoding if necessary). The parent
keyword cannot be combined with a Reference in any form.

Keys are immutable, which means that a Key object cannot be modified
once it has been created. This is enforced by the implementation as
well as Python allows.

For access to the contents of a key, the following methods and
operations are supported:

This returns a Future, whose result becomes available once the
deletion is complete. If no such entity exists, a Future is still
returned. In all cases the Future’s result is None (i.e. there is
no way to tell whether the entity existed or not).