Class Key (2.22.0)
Key(*path_args,**kwargs)An immutable representation of a datastore Key.
.. testsetup:: key-ctor
from google.cloud import datastore
project = 'my-special-pony' client = datastore.Client(project=project) Key = datastore.Key
parent_key = client.key('Parent', 'foo')
To create a basic key directly:
.. doctest:: key-ctor
Key('EntityKind', 1234, project=project) <Key('EntityKind', 1234), project=...>Key('EntityKind', 'foo', project=project) <Key('EntityKind', 'foo'), project=...>
Though typical usage comes via thexref_key factory:
.. doctest:: key-ctor
client.key('EntityKind', 1234) <Key('EntityKind', 1234), project=...>client.key('EntityKind', 'foo') <Key('EntityKind', 'foo'), project=...>
To create a key with a parent:
.. doctest:: key-ctor
client.key('Parent', 'foo', 'Child', 1234) <Key('Parent', 'foo', 'Child', 1234), project=...>client.key('Child', 1234, parent=parent_key) <Key('Parent', 'foo', 'Child', 1234), project=...>
To create a partial key:
.. doctest:: key-ctor
client.key('Parent', 'foo', 'Child') <Key('Parent', 'foo', 'Child'), project=...>
To create a key from a non-default database:
.. doctest:: key-ctor
Key('EntityKind', 1234, project=project, database='mydb') <Key('EntityKind', 1234), project=my-special-pony, database=mydb>
Parameter | |
|---|---|
| Name | Description |
path_args | tuple of string and integerMay represent a partial (odd length) or full (even length) key path. |
Properties
database
Database getter.
| Returns | |
|---|---|
| Type | Description |
str | The database of the current key. |
flat_path
Getter for the key path as a tuple.
| Returns | |
|---|---|
| Type | Description |
tuple of string and integer | The tuple of elements in the path. |
id
ID getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
int | The (integer) ID of the key. |
id_or_name
Getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
int (if | The last element of the key's path if it is either anid or aname. |
is_partial
Boolean indicating if the key has an ID (or name).
| Returns | |
|---|---|
| Type | Description |
bool | True if the last element of the key's path does not have anid or aname. |
kind
Kind getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
str | The kind of the current key. |
name
Name getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
str | The (string) name of the key. |
namespace
Namespace getter.
| Returns | |
|---|---|
| Type | Description |
str | The namespace of the current key. |
parent
The parent of the current key.
| Returns | |
|---|---|
| Type | Description |
Key or | A newKey instance, whose path consists of all but the last element of current path. If the current key has only one path element, returnsNone. |
path
Path getter.
Returns a copy so that the key remains immutable.
| Returns | |
|---|---|
| Type | Description |
| The (key) path of the current key. |
project
Project getter.
| Returns | |
|---|---|
| Type | Description |
str | The key's project. |
Methods
__eq__
__eq__(other)Compare two keys for equality.
Incomplete keys never compare equal to any other key.
Completed keys compare equal if they have the same path, project,database, and namespace.
(Note that database=None is considered to refer to the default database.)
| Returns | |
|---|---|
| Type | Description |
bool | True if the keys compare equal, else False. |
__hash__
__hash__()Hash this key for use in a dictionary lookup.
| Returns | |
|---|---|
| Type | Description |
int | a hash of the key's state. |
__ne__
__ne__(other)Compare two keys for inequality.
Incomplete keys never compare equal to any other key.
Completed keys compare equal if they have the same path, project,database, and namespace.
(Note that database=None is considered to refer to the default database.)
| Returns | |
|---|---|
| Type | Description |
bool | False if the keys compare equal, else True. |
__repr__
__repr__()String representation of this key.
Includes the project and database, but suppresses them if they areequal to the default values.
completed_key
completed_key(id_or_name)Creates new key from existing partial key by adding final ID/name.
| Parameter | |
|---|---|
| Name | Description |
id_or_name | str or integerID or name to be added to the key. |
| Exceptions | |
|---|---|
| Type | Description |
`ValueError | if the current key is not partial or ifid_or_name is not a string or integer. |
| Returns | |
|---|---|
| Type | Description |
Key | A newKey instance with the same data as the current one and an extra ID or name added. |
from_legacy_urlsafe
from_legacy_urlsafe(urlsafe)Convert urlsafe string to xref_Key.
This is intended to work with the "legacy" representation of adatastore "Key" used within Google App Engine (a so-called"Reference"). This assumes thaturlsafe was created within an AppEngine app via something likendb.Key(...).urlsafe().
| Parameter | |
|---|---|
| Name | Description |
urlsafe | bytes or unicodeThe base64 encoded (ASCII) string corresponding to a datastore "Key" / "Reference". |
| Returns | |
|---|---|
| Type | Description |
Key. | The key corresponding tourlsafe. |
to_legacy_urlsafe
to_legacy_urlsafe(location_prefix=None)Convert to a base64 encode urlsafe string for App Engine.
This is intended to work with the "legacy" representation of adatastore "Key" used within Google App Engine (a so-called"Reference"). The returned string can be used as theurlsafeargument tondb.Key(urlsafe=...). The base64 encoded valueswill have padding removed.
to_legacy_urlsafe is equivalent, butnot identical, to the string returned byndb. The locationprefix may need to be specified to obtain identical urlsafekeys.| Parameter | |
|---|---|
| Name | Description |
location_prefix | strThe location prefix of an App Engine project ID. Often this value is 's |
| Returns | |
|---|---|
| Type | Description |
bytes | A bytestring containing the key encoded as URL-safe base64. |
to_protobuf
to_protobuf()Return a protobuf corresponding to the key.
| Returns | |
|---|---|
| Type | Description |
| The protobuf representing the key. |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-16 UTC.