Stay organized with collections Save and categorize content based on your preferences.
google.appengine.ext.ndb.key module SummaryThe Key class, and associated utilities.
A Key encapsulates the following pieces of information, which together uniquely designate a (possible) entity in the App Engine datastore:
an application id (a string)
a namespace (a string)
a list of one or more (kind, id) pairs where kind is a string and id is either a string or an integer.
The application id must always be part of the key, but since most applications can only access their own entities, it defaults to the current application id and you rarely need to worry about it. It must not be empty.
The namespace designates a top-level partition of the key space for a particular application. If you’ve never heard of namespaces, you can safely ignore this feature.
Most of the action is in the (kind, id) pairs. A key must have at least one (kind, id) pair. The last (kind, id) pair gives the kind and the id of the entity that the key refers to, the others merely specify a ‘parent key’.
The kind is a string giving the name of the model class used to represent the entity. (In more traditional databases this would be the table name.) A model class is a Python class derived from ndb.Model; see the documentation for ndb/model.py. Only the class name itself is used as the kind. This means all your model classes must be uniquely named within one application. You can override this on a per-class basis.
The id is either a string or an integer. When the id is a string, the application is in control of how it assigns ids: For example, if you could use an email address as the id for Account entities.
To use integer ids, you must let the datastore choose a unique id for an entity when it is first inserted into the datastore. You can set the id to None to represent the key for an entity that hasn’t yet been inserted into the datastore. The final key (including the assigned id) will be returned after the entity is successfully inserted into the datastore.
A key for which the id of the last (kind, id) pair is set to None is called an incomplete key. Such keys can only be used to insert entities into the datastore.
A key with exactly one (kind, id) pair is called a top level key or a root key. Top level keys are also used as entity groups, which play a role in transaction management.
If there is more than one (kind, id) pair, all but the last pair represent the ‘ancestor path’, also known as the key of the ‘parent entity’.
Other constraints:
Kinds and string ids must not be empty and must be at most 500 bytes long (after UTF-8 encoding, if given as Python unicode objects). NOTE: This is defined as a module level constant _MAX_KEYPART_BYTES.
Integer ids must be at least 1 and less than 2**63.
For more info about namespaces, see http://code.google.com/appengine/docs/python/multitenancy/overview.html. The namespace defaults to the ‘default namespace’ selected by the namespace manager. To explicitly select the empty namespace pass namespace=’‘.
ContentsBases: object
An immutable datastore key.
For flexibility and convenience, multiple constructor signatures are supported.
The primary way to construct a key is using positional arguments: - Key(kind1, id1, kind2, id2, …).
This is shorthand for either of the following two longer forms: - Key(pairs=[(kind1, id1), (kind2, id2), …]) - Key(flat=[kind1, id1, kind2, id2, …])
Either of the above 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.
You can also construct a Key from a ‘url-safe’ encoded string: - Key(urlsafe=<string>)
For esoteric purposes the following constructors exist: - Key(reference=<reference>) – passing in a low-level Reference object - Key(serialized=<string>) – passing in a serialized low-level Reference - Key(<dict>) – for unpickling, the same as Key(**<dict>)
The ‘url-safe’ string is really 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=<string> – specify the application id - namespace=<string> – specify the namespace
If a Reference is passed (using one of reference, serialized or urlsafe), the args and namespace keywords must match what is already present in the Reference (after decoding if necessary). The parent keyword cannot be combined with a Reference in any form.
Keys are immutable, which means that a Key object cannot be modified once it has been created. This is enforced by the implementation as well as Python allows.
For access to the contents of a key, the following methods and operations are supported:
repr(key), str(key) – return a string representation resembling the shortest constructor form, omitting the app and namespace unless they differ from the default value.
key1 == key2, key1 != key2 – comparison for equality between Keys.
hash(key) – a hash value sufficient for storing Keys in a dict.
key.pairs() – a tuple of (kind, id) pairs.
key.flat() – a tuple of flattened kind and id values, i.e. (kind1, id1, kind2, id2, …).
key.app() – the application id.
key.id() – the string or integer id in the last (kind, id) pair, or None if the key is incomplete.
key.string_id() – the string id in the last (kind, id) pair, or None if the key has an integer id or is incomplete.
key.integer_id() – the integer id in the last (kind, id) pair, or None if the key has a string id or is incomplete.
key.namespace() – the namespace.
key.kind() – a shortcut for key.pairs()[-1][0].
key.parent() – a Key constructed from all but the last (kind, id) pairs.
key.urlsafe() – a websafe-base64-encoded serialized Reference.
key.serialized() – a serialized Reference.
key.reference() – a Reference object. The caller promises not to mutate it.
Keys also support interaction with the datastore; these methods are the only ones that engage in any kind of I/O activity. For Future objects, see the document for ndb/tasklets.py.
key.get() – return the entity for the Key.
key.get_async() – return a Future whose eventual result is the entity for the Key.
key.delete() – delete the entity for the Key.
key.delete_async() – asynchronously delete the entity for the Key.
Keys may be pickled.
Subclassing Key is best avoided; it would be hard to get right.
Return the application id.
Synchronously delete the entity for this Key.
This is a no-op if no such entity exists.
Schedule deletion of the entity for this Key.
This returns a Future, whose result becomes available once the deletion is complete. If no such entity exists, a Future is still returned. In all cases the Future’s result is None (i.e. there is no way to tell whether the entity existed or not).
Return a tuple of alternating kind and id values.
Synchronously get the entity for this Key.
Return None if there is no such entity.
Return a Future whose result is the entity for this Key.
If no such entity exists, a Future is still returned, and the Future’s eventual return result be None.
Return the string or integer id in the last (kind, id) pair, if any.
ReturnsA string or integer id, or None if the key is incomplete.
Return the integer id in the last (kind, id) pair, if any.
ReturnsAn integer id, or None if the key has a string id or is incomplete.
Return the kind of the entity referenced.
This is the kind from the last (kind, id) pair.
Return the namespace.
Return a tuple of (kind, id) pairs.
Return a Key constructed from all but the last (kind, id) pairs.
If there is only one (kind, id) pair, return None.
Return the Reference object for this Key.
This is a entity_pb.Reference instance – a protocol buffer class used by the lower-level API to the datastore.
NOTE: The caller should not mutate the return value.
Return the root key. This is either self or the highest parent.
Return a serialized Reference object for this Key.
Return the string id in the last (kind, id) pair, if any.
ReturnsA string id, or None if the key has an integer id or is incomplete.
Return a url-safe string encoding this Key’s Reference.
This string is compatible with other APIs and languages and with the strings used to represent Keys in GQL and in the App Engine Admin Console.
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-06-16 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-06-16 UTC."],[[["The `Key` class in the `google.appengine.ext.ndb.key` module uniquely identifies an entity in the App Engine datastore, encapsulating an application ID, a namespace, and a series of (kind, id) pairs."],["A `Key` must have at least one (kind, id) pair, where the last pair specifies the entity and any preceding pairs specify parent entities, and both kinds and string ids have to have less than 500 bytes in size after UTF-8 encoding, and integer ids must be between 1 and 2\\*\\*63."],["Keys can be constructed using various methods, including positional arguments, (kind, id) pairs, flat lists of kinds and ids, url-safe encoded strings, and serialized or reference objects."],["`Key` objects are immutable and can be used to retrieve (`get`, `get_async`), delete (`delete`, `delete_async`), and access information about entities, such as the application ID, namespace, kind, parent, and different types of IDs."],["Incomplete keys, which do not have an ID for the last (kind,id) pair, are only meant to insert entities, while a top level or root key contains exactly one (kind,id) pair."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4