Keys

Create / interact with Google Cloud Datastore keys.

class google.cloud.datastore.key.Key(*path_args, **kwargs)

Bases: object

An immutable representation of a datastore Key.

To create a basic key directly:

>>> Key('EntityKind', 1234, project=project)
<Key('EntityKind', 1234), project=...>
>>> Key('EntityKind', 'foo', project=project)
<Key('EntityKind', 'foo'), project=...>

Though typical usage comes via the key() factory:

>>> client.key('EntityKind', 1234)
<Key('EntityKind', 1234), project=...>
>>> client.key('EntityKind', 'foo')
<Key('EntityKind', 'foo'), project=...>

To create a key with a parent:

>>> 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:

>>> client.key('Parent', 'foo', 'Child')
<Key('Parent', 'foo', 'Child'), project=...>

To create a key from a non-default database:

>>> Key('EntityKind', 1234, project=project, database='mydb')
<Key('EntityKind', 1234), project=my-special-pony, database=mydb>

  • Parameters

    • path_args (tuple of string and integer) – May represent a partial (odd length) or full (even length) key path.

    • kwargs – Keyword arguments to be passed in.

Accepted keyword arguments are

  • namespace (string): A namespace identifier for the key.

  • project (string): The project associated with the key.

  • database (string): The database associated with the key.

  • parent (Key): The parent of the key.

The project argument is required unless it has been set implicitly.

_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.)

  • Return type

    bool

  • Returns

    True if the keys compare equal, else False.

_hash_()

Hash this key for use in a dictionary lookup.

  • Return type

    int

  • Returns

    a hash of the key’s state.

_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.)

  • Return type

    bool

  • Returns

    False if the keys compare equal, else True.

_repr_()

String representation of this key.

Includes the project and database, but suppresses them if they are equal to the default values.

completed_key(id_or_name)

Creates new key from existing partial key by adding final ID/name.

  • Parameters

    id_or_name (str* or *integer) – ID or name to be added to the key.

  • Return type

    google.cloud.datastore.key.Key

  • Returns

    A new Key instance with the same data as the current one and an extra ID or name added.

  • Raises

    ValueError if the current key is not partial or if id_or_name is not a string or integer.

property database()

Database getter.

  • Return type

    str

  • Returns

    The database of the current key.

property flat_path()

Getter for the key path as a tuple.

  • Return type

    tuple of string and integer

  • Returns

    The tuple of elements in the path.

classmethod from_legacy_urlsafe(urlsafe)

Convert urlsafe string to Key.

This is intended to work with the “legacy” representation of a datastore “Key” used within Google App Engine (a so-called “Reference”). This assumes that urlsafe was created within an App Engine app via something like ndb.Key(...).urlsafe().

NOTE: from_legacy_urlsafe only supports the default database.

  • Parameters

    urlsafe (bytes* or *unicode) – The base64 encoded (ASCII) string corresponding to a datastore “Key” / “Reference”.

  • Return type

    Key.

  • Returns

    The key corresponding to urlsafe.

property id()

ID getter. Based on the last element of path.

  • Return type

    int

  • Returns

    The (integer) ID of the key.

property id_or_name()

Getter. Based on the last element of path.

  • Return type

    int (if id) or string (if name)

  • Returns

    The last element of the key’s path if it is either an id or a name.

property is_partial()

Boolean indicating if the key has an ID (or name).

  • Return type

    bool

  • Returns

    True if the last element of the key’s path does not have an id or a name.

property kind()

Kind getter. Based on the last element of path.

  • Return type

    str

  • Returns

    The kind of the current key.

property name()

Name getter. Based on the last element of path.

  • Return type

    str

  • Returns

    The (string) name of the key.

property namespace()

Namespace getter.

  • Return type

    str

  • Returns

    The namespace of the current key.

property parent()

The parent of the current key.

  • Return type

    google.cloud.datastore.key.Key or NoneType

  • Returns

    A new Key instance, whose path consists of all but the last element of current path. If the current key has only one path element, returns None.

property path()

Path getter.

Returns a copy so that the key remains immutable.

  • Return type

    list of dict

  • Returns

    The (key) path of the current key.

property project()

Project getter.

  • Return type

    str

  • Returns

    The key’s project.

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 a datastore “Key” used within Google App Engine (a so-called “Reference”). The returned string can be used as the urlsafe argument to ndb.Key(urlsafe=...). The base64 encoded values will have padding removed.

NOTE: The string returned by to_legacy_urlsafe is equivalent, but not identical, to the string returned by ndb. The location prefix may need to be specified to obtain identical urlsafe keys.

NOTE: to_legacy_urlsafe only supports the default database

  • Parameters

    location_prefix (str) – The location prefix of an App Engine project ID. Often this value is ‘s~’, but may also be ‘e~’, or other location prefixes currently unknown.

  • Return type

    bytes

  • Returns

    A bytestring containing the key encoded as URL-safe base64.

to_protobuf()

Return a protobuf corresponding to the key.

  • Return type

    entity_pb2.Key

  • Returns

    The protobuf representing the key.