English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# 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
- Constructors
- Instance Methods that don't Affect the Datastore
  - pairs()
  - flat()
  - app()
  - id()
  - string_id()
  - integer_id()
  - namespace()
  - kind()
  - parent()
  - urlsafe()
- Instance Methods that Affect the Datastore
  - get()
  - get_async()
  - delete()
  - delete_async()

## 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.