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.
Creating and Using Entity Keys
Stay organized with collections
Save and categorize content based on your preferences.
Each entity is identified by a key that is unique within the application's
Datastore instance, and consists of the following:
- kind. The kind is normally the name of the model class to which the entity
belongs, but you can change this to some other string by overriding the classmethod
_get_kind()
.
- identifier. You specify your own key name as the identifier or let
Datastore automatically generate an integer numeric ID.
Specifying your own key name
The following example implicitly creates a key with a string identifier
using the named parameter id
:
You could alternatively set the key name directly:
Letting Datastore generate an ID to use for the key
This code shows how to use an auto-generated ID as the key:
Using the ancestor path in the key
The sequence of entities beginning with a root entity and proceeding from parent
to child, leading to a given entity, constitute that entity's ancestor path.
An entity, its parent, parent's parent, and so on recursively, are the entity's
ancestors. The entities in Datastore form a hierarchical key space
similar to the hierarchical directory structure of a file system.
The complete key identifying an entity consists of a sequence of kind-identifier
pairs specifying its ancestor path and terminating with those of the entity
itself. The constructor method for class Key
accepts such a sequence of kinds and
identifiers and returns an object representing the key for the corresponding entity.
The following example shows a blogging service that stores messages by revision.
Messages are organized under accounts, and revisions are under messages.
...
In the sample, ('Account', 'sandy@example.com')
, ('Message', 123)
, and ('Revision', '1')
are all examples of kind-identifier pairs.
Notice that Message
is not a model class; it is used only as a way to group
revisions, not to store data.
As shown in the sample code, the entity's kind is designated by the last
kind-name pair in the list: ndb.Key('Revision', '1')
.
Using named parameters
You can use the named parameter parent
to designate any entity in the ancestor
path directly. All of the following notations represent the same key:
Specifying a root entity
For a root entity, the ancestor path is empty and the key consist solely of the
entity's own kind and identifier.
Specifying an entity with ancestors
To insert a new message with parent keys
For keys that were created with a parent, the parent()
method returns a key
representing the parent entity:
Using Numeric Key IDs
You can create an entity without specifying an ID, in which case the data store
automatically generates a numeric ID. If you choose to specify some IDs and then
let Datastore automatically generate some IDs, you could
violate the requirement for unique keys. To avoid this, reserve a range of
numbers to use to choose IDs or use string IDs to avoid this issue entirely.
To reserve a range of IDs, use the model class'
allocate_ids()
class method:
- to allocate a specified number of IDs
- to allocate all IDs up to a given maximum value.
Allocating IDs
To allocate 100 IDs for a given model class MyModel
:
To allocate 100 IDs for entities with parent key p
:
The returned values, first
and last
, are the first and last IDs (inclusive)
that are allocated. You can use these to construct keys as follows:
These keys are guaranteed not to have been returned previously by the data
store's internal ID generator, nor will they be returned by future calls to the
internal ID generator. However, the allocate_ids()
method does not check
whether the IDs returned are present in the data store; it only interacts with
the ID generator.
To allocate all IDs up to a given maximum value:
This form ensures that all IDs less than or equal to N
are considered
allocated. The return values, first
and last
, indicate the range of IDs
reserved by this operation. It is not an error to attempt to reserve IDs already
allocated; if that happens, first
indicates the first ID not yet allocated and
last
is the last ID allocated.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-29 UTC.
[[["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-08-29 UTC."],[[["\u003cp\u003eEntities in the Datastore are uniquely identified by a key, which includes a kind and an identifier, either specified by the user or automatically generated by Datastore.\u003c/p\u003e\n"],["\u003cp\u003eThe key identifier can be a string, set by the user, or an integer ID, automatically generated by Datastore, which can be chosen by either setting an \u003ccode\u003eid\u003c/code\u003e parameter or letting it be generated upon using \u003ccode\u003eput\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eEntities can have an ancestor path, forming a hierarchical structure similar to a file system, where the complete key includes a sequence of kind-identifier pairs representing the entity and its ancestors.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eallocate_ids()\u003c/code\u003e method can be used to reserve a range of numeric IDs for a specific model, ensuring unique key creation, and this can be done either by specifying a number of ID's or a max number.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eparent\u003c/code\u003e named parameter can be used to designate any entity in the ancestor path directly, offering flexibility in defining entity relationships and key structures.\u003c/p\u003e\n"]]],[],null,["# Creating and Using Entity Keys\n\n| This API is supported for first-generation runtimes and can be used when [upgrading to corresponding second-generation runtimes](/appengine/docs/standard/\n| python3\n|\n| /services/access). 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\nEach entity is identified by a key that is unique within the application's\nDatastore instance, and consists of the following:\n\n- **kind** . The kind is normally the name of the model class to which the entity belongs, but you can change this to some other string by overriding the classmethod `_get_kind()`.\n- **identifier** . You specify your own *key name* as the identifier or let Datastore automatically generate an integer numeric ID.\n\nSpecifying your own key name\n----------------------------\n\nThe following example implicitly creates a key with a string identifier\nusing the named parameter `id`: \n\n account = Account(\n username='Sandy', userid=1234, email='sandy@example.com',\n id='sandy@example.com')\n\n return account.key.id() # returns 'sandy@example.com'\n\nYou could alternatively set the key name directly: \n\n account.key = ndb.Key('Account', 'sandy@example.com')\n\n # You can also use the model class object itself, rather than its name,\n # to specify the entity's kind:\n account.key = ndb.Key(Account, 'sandy@example.com')\n\nLetting Datastore generate an ID to use for the key\n---------------------------------------------------\n\nThis code shows how to use an auto-generated ID as the key: \n\n # note: no id kwarg\n account = Account(username='Sandy', userid=1234, email='sandy@example.com')\n account.put()\n # account.key will now have a key of the form: ndb.Key(Account, 71321839)\n # where the value 71321839 was generated by Datastore for us.\n\nUsing the ancestor path in the key\n----------------------------------\n\nThe sequence of entities beginning with a root entity and proceeding from parent\nto child, leading to a given entity, constitute that entity's *ancestor path* .\nAn entity, its parent, parent's parent, and so on recursively, are the entity's\n*ancestors*. The entities in Datastore form a hierarchical key space\nsimilar to the hierarchical directory structure of a file system.\n\nThe complete key identifying an entity consists of a sequence of kind-identifier\npairs specifying its ancestor path and terminating with those of the entity\nitself. The constructor method for class `Key` accepts such a sequence of kinds and\nidentifiers and returns an object representing the key for the corresponding entity.\n\nThe following example shows a blogging service that stores messages by revision.\nMessages are organized under accounts, and revisions are under messages.\n\n\n class Revision(ndb.Model):\n message_text = ndb.StringProperty()\n\n`...` \n\n ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')\n ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '2')\n ndb.Key('Account', 'larry@example.com', 'Message', 456, 'Revision', '1')\n ndb.Key('Account', 'larry@example.com', 'Message', 789, 'Revision', '2')\n\nIn the sample, `('Account', 'sandy@example.com')`, `('Message', 123)`, and `('Revision', '1')`\nare all examples of kind-identifier pairs.\n\nNotice that `Message` is not a model class; it is used only as a way to group\nrevisions, not to store data.\n\nAs shown in the sample code, the entity's kind is designated by the *last*\nkind-name pair in the list: `ndb.Key('Revision', '1')`.\n\n### Using named parameters\n\nYou can use the named parameter `parent` to designate any entity in the ancestor\npath directly. All of the following notations represent the same key: \n\n ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')\n\n ndb.Key('Revision', '1', parent=ndb.Key(\n 'Account', 'sandy@example.com', 'Message', 123))\n\n ndb.Key('Revision', '1', parent=ndb.Key(\n 'Message', 123, parent=ndb.Key('Account', 'sandy@example.com')))\n\n### Specifying a root entity\n\nFor a root entity, the ancestor path is empty and the key consist solely of the\nentity's own kind and identifier. \n\n sandy_key = ndb.Key(Account, 'sandy@example.com')\n\n### Specifying an entity with ancestors\n\nTo insert a new message with parent keys \n\n account_key = ndb.Key(Account, 'sandy@example.com')\n\n # Ask Datastore to allocate an ID.\n new_id = ndb.Model.allocate_ids(size=1, parent=account_key)[0]\n\n # Datastore returns us an integer ID that we can use to create the message\n # key\n message_key = ndb.Key('Message', new_id, parent=account_key)\n\n # Now we can put the message into Datastore\n initial_revision = Revision(\n message_text='Hello', id='1', parent=message_key)\n initial_revision.put()\n\nFor keys that were created with a parent, the `parent()` method returns a key\nrepresenting the parent entity: \n\n message_key = initial_revision.key.parent()\n\nUsing Numeric Key IDs\n---------------------\n\nYou can create an entity without specifying an ID, in which case the data store\nautomatically generates a numeric ID. If you choose to specify some IDs and then\nlet Datastore automatically generate some IDs, you could\nviolate the requirement for unique keys. To avoid this, reserve a range of\nnumbers to use to choose IDs or use string IDs to avoid this issue entirely.\n\nTo reserve a range of IDs, use the model class'\n[`allocate_ids()`](/appengine/docs/legacy/standard/python/ndb/modelclass#Model_allocate_ids)\nclass method:\n\n- to allocate a specified number of IDs\n- to allocate all IDs up to a given maximum value.\n\n### Allocating IDs\n\nTo allocate 100 IDs for a given model class `MyModel`: \n\n first, last = MyModel.allocate_ids(100)\n\nTo allocate 100 IDs for entities with parent key `p`: \n\n first, last = MyModel.allocate_ids(100, parent=p)\n\nThe returned values, `first` and `last`, are the first and last IDs (inclusive)\nthat are allocated. You can use these to construct keys as follows: \n\n keys = [ndb.Key(MyModel, id) for id in range(first, last+1)]\n\nThese keys are guaranteed not to have been returned previously by the data\nstore's internal ID generator, nor will they be returned by future calls to the\ninternal ID generator. However, the `allocate_ids()` method does not check\nwhether the IDs returned are present in the data store; it only interacts with\nthe ID generator.\n\nTo allocate all IDs up to a given maximum value: \n\n first, last = MyModel.allocate_ids(max=N)\n\nThis form ensures that all IDs less than or equal to `N` are considered\nallocated. The return values, `first` and `last`, indicate the range of IDs\nreserved by this operation. It is not an error to attempt to reserve IDs already\nallocated; if that happens, `first` indicates the first ID not yet allocated and\n`last` is the last ID allocated.\n| **Note:** you cannot call `allocate_ids()` in a [transaction](/appengine/docs/legacy/standard/python/ndb/transactions)."]]