Class Entity (2.0.1)

Entity(key=None,exclude_from_indexes=())

Entities are akin to rows in a relational database

An entity storing the actual instance of data.

Each entity is officially represented with axref_Key, however it is possible thatyou might create an entity with only a partial key (that is, a keywith a kind, and possibly a parent, but without an ID). In such acase, the datastore service will automatically assign an ID to thepartial key.

Entities in this API act like dictionaries with extras built in thatallow you to delete or persist the data stored on the entity.

Entities are mutable and act like a subclass of a dictionary.This means you could take an existing entity and change the keyto duplicate the object.

Use xref_get to retrieve anexisting entity:

.. testsetup:: entity-ctor

import osimport uuidfrom google.cloud importdatastorefrom tests.system.test_system import Config  # system testsunique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])client =datastore.Client(namespace='ns{}'.format(unique))key = client.key('EntityKind', 1234, namespace='_Doctest')entity =datastore.Entity(key=key)entity['property'] = 'value'Config.TO_DELETE.append(entity)client.put(entity)

.. doctest:: entity-ctor

>>> client.get(key)<Entity('EntityKind', 1234) {'property': 'value'}>

You can the set values on the entity just like you would on anyother dictionary.

.. doctest:: entity-ctor

>>> entity['age'] = 20>>> entity['name'] = 'JJ'

However, not all types are allowed as a value for a Google Cloud Datastoreentity. The following basic types are supported by the API:

  • datetime.datetime
  • xref_Key
  • bool
  • float
  • int (as well aslong in Python 2)
  • unicode (calledstr in Python 3)
  • bytes (calledstr in Python 2)
  • xref_GeoPoint
  • :data:None

In addition, three container types are supported:

  • list
  • xref_Entity
  • dict (will just be treated like anEntity withouta key orexclude_from_indexes)

Each entry in a list must be one of the value types (basic orcontainer) and each value in anxref_Entity must as well. Inthis case an xref_Entityas acontainer acts as adict, but also has the special annotationsofkey andexclude_from_indexes.

And you can treat an entity like a regular Python dictionary:

.. testsetup:: entity-dict

from google.cloud importdatastoreentity =datastore.Entity()entity['age'] = 20entity['name'] = 'JJ'

.. doctest:: entity-dict

>>> sorted(entity.keys())['age', 'name']>>> sorted(entity.items())[('age', 20), ('name', 'JJ')]
Note:When saving an entity to the backend, values which are "text"(unicode in Python2,str in Python3) will be saved usingthe 'text_value' field, after being encoded to UTF-8. Whenretrieved from the back-end, such values will be decoded to "text"again. Values which are "bytes" (str in Python2,bytes inPython3), will be saved using the 'blob_value' field, withoutany decoding / encoding step.

Parameters

NameDescription
keyKey

Optional key to be set on entity.

exclude_from_indexestuple of string

Names of fields whose values are not to be indexed for this entity.

Properties

id

Get the ID of the current entity.

Note:This relies entirely on theKeyset on the entity. That means that we're not storing the IDof the entity at all, just the properties and a pointer to aKey which knows its ID.

kind

Get the kind of the current entity.

Note:This relies entirely on theKeyset on the entity. That means that we're not storing the kindof the entity at all, just the properties and a pointer to aKey which knows its Kind.

Methods

__eq__

__eq__(other)

Compare two entities for equality.

Entities compare equal if their keys compare equal and theirproperties compare equal.

Returns
TypeDescription
boolTrue if the entities compare equal, else False.

__ne__

__ne__(other)

Compare two entities for inequality.

Entities compare equal if their keys compare equal and theirproperties compare equal.

Returns
TypeDescription
boolFalse if the entities compare equal, else True.

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.