English

Google App Engine

NDB Key Class

Experimental!

NDB is an experimental, innovative, and rapidly changing new feature for App Engine. Unfortunately, being on the bleeding edge means that we may make backwards-incompatible changes to NDB. We will inform the community when this feature is no longer experimental.

An instance of the Key class represents an immutable Datastore key.

This page has API reference documentation. For an overview, please see NDB Entities and Keys.

Introduction

A Key is an immutable Datastore key. Applications normally use them to refer to entities. Any entity that has been stored has a key. To get an entity's key, use the model's key property. To retrieve an entity from its key, call the Key object's get() method.

Keys support equality tests. That is, key1 == key2 and key1 != key2 work. The equality test checks application ID, namespace, and the full "ancestor path". Keys aren't ordered; they do not support key1 < key2 or key1 > key2.

repr(key) or str(key) returns a string representation resembling the shortest constructor form, omitting the app and namespace unless they differ from the default value.

hash(key) works. Thus, you can store keys in a hash table.

Constructors

For flexibility and convenience, multiple constructor signatures are supported.

class Key(kind1, id1, kind2, id2, ...)
class Key(pairs=[(kind1, id1), (kind2, id2), ...])
class Key(flat=[kind1, id1, kind2, id2, ...])
class Key(urlsafe=string)

The positional arguments kind1, id1, kind2, id2... are in "ancestor" order. (This is a shortcut for flat=[kind1, id1, kind2, id2]) Parents come before children.

The positional-arguments, pairs, and flat 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.

The urlsafe keyword parameter uses a websafe-base64-encoded serialized Reference but it's best to think of it as just an opaque unique string.

Additional constructor keyword arguments:

app
specify the application id (a string)
namespace
specify the namespace (a string)

Instance Methods that Don't Affect the Datastore

The following methods access the contents of a key. They do not engage in any Datastore I/O activity.

pairs()

Returns a tuple of (kind, id) pairs.

flat()

Returns a tuple of flattened kind and id values (kind1, id1, kind2, id2, ...).

app()

Returns the application id.

id()

Returns the string or integer id in the last (kind, id) pair, or None if the key is incomplete.

string_id()

Returns the string id in the last (kind, id) pair, or None if the key has an integer id or is incomplete.

integer_id()

Returns the integer id in the last (kind, id) pair, or None if the key has an string id or is incomplete.

namespace()

Returns the namespace.

kind()

Returns the kind in the last (kind, id) pair.

parent()

Returns a Key constructed from all but the last (kind, id) pair (or None if the key has just one (kind, id) pair).

urlsafe()

Returns a websafe-base64-encoded serialized version of the key.

Instance Methods that Affect the Datastore

These methods interact with the Datastore.

get()

Returns the entity for the Key.

get_async()

Returns a Future whose eventual result is the entity for the Key.

delete()

Delete the entity for the Key.

delete()

Asynchronously delete the entity for the Key.