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
- Constructors
- Instance Methods that don't Affect the Datastore
- Instance Methods that Affect the Datastore
- Class Method
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