Python 2.7 has reached end of support
and will be deprecated
on January 31, 2026. After deprecation, you won't be able to deploy Python 2.7
applications, even if your organization previously used an organization policy to
re-enable deployments of legacy runtimes. Your existing Python
2.7 applications will continue to run and receive traffic after their
deprecation date. We recommend that
you migrate to the latest supported version of Python.
Stay organized with collections
Save and categorize content based on your preferences.
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.
classKey(kind1, id1, kind2, id2, ...)
classKey(pairs=[(kind1, id1), (kind2, id2), ...])
classKey(flat=[kind1, id1, kind2, id2, ...])
classKey(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.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eThis API for bundled services and \u003ccode\u003eKey\u003c/code\u003e class operations is specifically for first-generation runtimes in the App Engine standard environment, with migration to Python 3 requiring a specific guide.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eKey\u003c/code\u003e class represents an immutable Datastore key, used to refer to entities and to retrieve them using the \u003ccode\u003eget()\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eKeys can be compared using operators such as \u003ccode\u003e==\u003c/code\u003e and \u003ccode\u003e<\u003c/code\u003e, and also support string representation, as well as being used within a hash table.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eKey\u003c/code\u003e class offers various constructor signatures, including those for ancestor order, pairs, flat structures, and URL-safe strings, along with options for specifying the application ID and namespace.\u003c/p\u003e\n"],["\u003cp\u003eThere are multiple methods to access key properties and contents, which do not affect the Datastore, as well as other methods that will interact with the Datastore, like to get or delete an entity.\u003c/p\u003e\n"]]],[],null,["# NDB Key Class\n\n| This page describes how to use the legacy bundled services and APIs. This API can only run in first-generation runtimes in the App Engine standard environment. If you are updating to the App Engine Python 3 runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/python-differences) to learn about your migration options for legacy bundled services.\n\nAn instance of the `Key` class represents an immutable\nDatastore key.\n\nThis page has API reference documentation. For an overview,\nsee [NDB Entities and Keys](/appengine/docs/legacy/standard/python/ndb/creating-entities).\n\nIntroduction\n------------\n\nA Key is an immutable Datastore key. Applications normally use them to refer\nto entities. Any entity that has been stored has a key. To get an entity's\nkey, use the model's [key](/appengine/docs/legacy/standard/python/ndb/modelclass#Model_key)\nproperty.\nTo retrieve an entity from its key, call the `Key`\nobject's [get()](#Key_get) method.\n\nKeys support comparisons, for example\n\u003cvar translate=\"no\"\u003ekey1\u003c/var\u003e` == `\u003cvar translate=\"no\"\u003ekey2\u003c/var\u003e or\n\u003cvar translate=\"no\"\u003ekey1\u003c/var\u003e` \u003c `\u003cvar translate=\"no\"\u003ekey2\u003c/var\u003e.\nThese operators compare application ID, namespace, and the full\n\"ancestor path\". They use the same ordering as the Datastore uses\nfor queries when ordering by a key property or by key.\n\n`repr(`\u003cvar translate=\"no\"\u003ekey\u003c/var\u003e`)` or\n`str(`\u003cvar translate=\"no\"\u003ekey\u003c/var\u003e`)` returns\na string representation resembling\nthe shortest constructor form, omitting the app and namespace\nunless they differ from the default value.\n\n`hash(`\u003cvar translate=\"no\"\u003ekey\u003c/var\u003e`)` works. Thus, you can store keys in\na hash table.\n\nConstructors\n------------\n\nFor flexibility and convenience, multiple constructor signatures are\nsupported.\n\nclass Key(\u003cvar translate=\"no\"\u003ekind1\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid1\u003c/var\u003e, \u003cvar translate=\"no\"\u003ekind2\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid2\u003c/var\u003e, ...)\nclass Key(pairs=\\[(\u003cvar translate=\"no\"\u003ekind1\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid1\u003c/var\u003e), (\u003cvar translate=\"no\"\u003ekind2\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid2\u003c/var\u003e), ...\\])\nclass Key(flat=\\[\u003cvar translate=\"no\"\u003ekind1\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid1\u003c/var\u003e, \u003cvar translate=\"no\"\u003ekind2\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid2\u003c/var\u003e, ...\\])\nclass Key(urlsafe=\u003cvar translate=\"no\"\u003estring\u003c/var\u003e)\n\n: The positional arguments\n \u003cvar translate=\"no\"\u003ekind1\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid1\u003c/var\u003e, \u003cvar translate=\"no\"\u003ekind2\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid2\u003c/var\u003e...\n are in \"ancestor\" order. (This is a shortcut for\n `flat=[`\u003cvar translate=\"no\"\u003ekind1\u003c/var\u003e`, `\u003cvar translate=\"no\"\u003eid1\u003c/var\u003e`,\n `\u003cvar translate=\"no\"\u003ekind2\u003c/var\u003e`, `\u003cvar translate=\"no\"\u003eid2\u003c/var\u003e`]`) Parents come before children.\n\n The positional-arguments, `pairs`, and `flat`\n constructor forms can additionally pass in another\n key using parent=\u003cvar translate=\"no\"\u003ekey\u003c/var\u003e.\n The (\u003cvar translate=\"no\"\u003ekind\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid\u003c/var\u003e) pairs of the parent key are\n inserted before the (\u003cvar translate=\"no\"\u003ekind\u003c/var\u003e, \u003cvar translate=\"no\"\u003eid\u003c/var\u003e) pairs\n passed explicitly.\n\n The `urlsafe` keyword parameter uses\n a websafe-base64-encoded serialized\n reference\n but it's best to think of it as just an opaque unique\n string.\n\n Additional constructor keyword arguments:\n\n app\n : specify the application id (a string)\n\n namespace\n : specify the namespace (a string)\n\nInstance Methods that Don't Affect the Datastore\n------------------------------------------------\n\nThe following methods access the contents of a key. They do not\nengage in any Datastore I/O activity.\n\npairs()\n\n: Returns a tuple of (kind, id) pairs.\n\nflat()\n\n: Returns a tuple of flattened kind and id values\n (kind1, id1, kind2, id2, ...).\n\napp()\n\n: Returns the application id.\n\nid()\n\n: Returns the string or integer id in the last (kind, id) pair,\n or `None` if the key is incomplete.\n\nstring_id()\n\n: Returns the string id in the last (kind, id) pair,\n or `None` if the key has an integer id or is incomplete.\n\ninteger_id()\n\n: Returns the integer id in the last (kind, id) pair,\n or `None` if the key has an string id or is incomplete.\n\nnamespace()\n\n: Returns the namespace.\n\nkind()\n\n: Returns the kind in the last (kind, id) pair.\n\nparent()\n\n: Returns a Key constructed from all but the last (kind, id) pair\n (or `None` if the key has just one (kind, id) pair).\n\nurlsafe()\n\n: Returns a websafe-base64-encoded serialized version of the key.\n\n **Note:**\n The URL-safe string looks cryptic, but it is not encrypted!\n It can easily be decoded to recover the original entity's kind and\n identifier.\n\nto_old_key()\n\n: Returns a\n [Key](/appengine/docs/legacy/standard/python/datastore/keyclass)\n for the \"old\" Datastore API (`db`).\n\nInstance Methods that Affect the Datastore\n------------------------------------------\n\nThese methods interact with the Datastore.\n\nget(\\*\\*ctx_options)\n\n: Returns the entity for the Key.\n\n **Arguments**\n\n \\*\\*ctx_options\n : [Context options](/appengine/docs/legacy/standard/python/ndb/functions#context_options)\n\nget_async(\\*\\*ctx_options)\n\n: Returns a\n [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n whose eventual result is\n the entity for the Key.\n\n **Arguments**\n\n \\*\\*ctx_options\n : [Context options](/appengine/docs/legacy/standard/python/ndb/functions#context_options)\n\ndelete(\\*\\*ctx_options)\n\n: Delete the entity for the Key.\n\n **Arguments**\n\n \\*\\*ctx_options\n : [Context options](/appengine/docs/legacy/standard/python/ndb/functions#context_options)\n\ndelete_async(\\*\\*ctx_options)\n\n: Asynchronously delete the entity for the Key.\n\n **Arguments**\n\n \\*\\*ctx_options\n : [Context options](/appengine/docs/legacy/standard/python/ndb/functions#context_options)\n\nClass Methods\n-------------\n\nfrom_old_key(k)\n\n: Returns an NDB key from the passed in \"old\" Datastore API\n (`db`)\n [Key](/appengine/docs/legacy/standard/python/datastore/keyclass).\n\n **Arguments**\n\n \\*\\*ctx_options\n : [Context options](/appengine/docs/legacy/standard/python/ndb/functions#context_options)"]]