An instance of the Key
class represents an immutable
Datastore key.
This page has API reference documentation. For an overview, 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 comparisons, for example
key1 == key2
or
key1 < key2
.
These operators compare application ID, namespace, and the full
"ancestor path". They use the same ordering as the Datastore uses
for queries when ordering by a key property or by key.
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
, andflat
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.
Note: The URL-safe string looks cryptic, but it is not encrypted! It can easily be decoded to recover the original entity's kind and identifier.
- to_old_key()
-
Returns a
Key
for the "old" Datastore API (db
).
Instance Methods that Affect the Datastore
These methods interact with the Datastore.
- get(**ctx_options)
-
Returns the entity for the Key.
Arguments
- **ctx_options
- Context options
- get_async(**ctx_options)
-
Returns a
Future
whose eventual result is the entity for the Key.Arguments
- **ctx_options
- Context options
- delete(**ctx_options)
-
Delete the entity for the Key.
Arguments
- **ctx_options
- Context options
- delete_async(**ctx_options)
-
Asynchronously delete the entity for the Key.
Arguments
- **ctx_options
- Context options
Class Methods
- from_old_key(k)
-
Returns an NDB key from the passed in "old" Datastore API (
db
)Key
.Arguments
- **ctx_options
- Context options