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

# The Key Class

An instance of the Key class represents a unique key for a datastore entity.

`Key` is provided by the `google.appengine.ext.db` module.

- Introduction
- Key()
- Class methods:
  - Key.from_path()
- Instance methods:
  - app()
  - has_id_or_name()
  - id()
  - id_or_name()
  - kind()
  - name()
  - namespace()
  - parent()

## Introduction

Every model instance that has been stored in the datastore has a unique key that represents the object. The key() method of a model instance returns the Key object for the instance. If the instance has never been put() in the datastore, key() raises a NotSavedError.

An application can retrieve a model instance for a given Key using the get() function.

Key instances can be values for datastore entity properties, including Expando dynamic properties and ListProperty members. The ReferenceProperty model provides features for Key property values such as automatic dereferencing.

## Constructor

class Key(encoded=None)

  A unique key for a datastore object.

  A key can be encoded to a string by passing the Key object to `str()` (or calling the object's `__str__()` method). A string-encoded key is an opaque value using characters safe for including in URLs. The string-encoded key can be converted back to a Key object by passing it to the Key constructor (the encoded argument).

  Note: A string-encoded key can be converted back to the raw key data. This makes it easy to guess other keys when one is known. While string-encoded key values are safe to include in URLs, an application should only do so if key guessability is not an issue.

  encoded
    The `str` form of a Key instance to convert back into a Key.

## Class Methods

The Key class provides the following class method:

Key.from_path(kind, id_or_name, parent=none, namespace=None, **kwds)

  Builds a new Key object from an ancestor path of one or more entity keys.

  A path represents the hierarchy of parent-child relationships for an entity. Each entity in the path is represented the entity's kind, and either its numeric ID or its key name. The full path represents the entity that appears last in the path, with its ancestors (parents) as preceding entities.

  For example, the following call creates a key for an entity of kind `Address` with the numeric ID `9876` whose parent is an entity of kind `User` with the named key `'Boris'`:

      k = Key.from_path('User', 'Boris', 'Address', 9876)

  For more information about paths, see Keys and Entity Groups.

  Arguments:

  kind
    The entity kind, represented as a string or a Unicode string.
  id_or_name
    The `id`, specified as a string or long. It cannot be the number 0.
  namespace=None
    The namespace to set for this Key only. If you supply a namespace here, it overrides the current namespace set in the namespace_manager. If `None`, the API uses the current namespace from namespace_manager.get_namespace.
  parent=None
    Optional parent key. If not supplied, defaults to `None`.
  **kwds
    Keyword arguments. The method supports one keyword argument, parent, which specifies a parent entity to prepend to the given path. Its value is the parent's Key.

### Instance Methods

Key instances have the following methods:

app()

  Returns the name of the application that stored the data entity.

has_id_or_name()

  Returns `True` if the entity has either a name or a numeric ID.

id()

  Returns the numeric ID of the data entity, as an integer, or `None` if the entity does not have a numeric ID.

id_or_name()

  Returns the name or numeric ID of the data entity, whichever it has, or `None` if the entity has neither a name nor a numeric ID.

kind()

  Returns the kind of the data entity, as a string.

name()

  Returns the name of the data entity, or `None` if the entity does not have a name.

namespace()

  Returns the namespace of the data entity. If the entity does not have a current namespace, this method returns the current namespace set in the namespace_manager.

parent()

  Returns the Key of the data entity's parent entity, or `None` if the entity has no parent.