Entities are akin to rows in a relational database
An entity storing the actual instance of data.
Each entity is officially represented with a
xref_Key, however it is possible that
you might create an entity with only a partial key (that is, a key
with a kind, and possibly a parent, but without an ID). In such a
case, the datastore service will automatically assign an ID to the
partial key.
Entities in this API act like dictionaries with extras built in that
allow 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 key
to duplicate the object.
You can the set values on the entity just like you would on any
other dictionary.
.. doctest:: entity-ctor
>>> entity['age'] = 20
>>> entity['name'] = 'JJ'
.. testcleanup:: entity-ctor
client.delete(entity.key)
However, not all types are allowed as a value for a Google Cloud Datastore
entity. The following basic types are supported by the API:
datetime.datetime
xref_Key
bool
float
int (as well as long in Python 2)
unicode (called str in Python 3)
bytes (called str in Python 2)
xref_GeoPoint
:data:None
In addition, three container types are supported:
list
xref_Entity
dict (will just be treated like an Entity without
a key or exclude_from_indexes)
Each entry in a list must be one of the value types (basic or
container) and each value in an
xref_Entity must as well. In
this case an xref_Entity as a
container acts as a dict, but also has the special annotations
of key and exclude_from_indexes.
And you can treat an entity like a regular Python dictionary:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Class Entity (2.21.0)\n\nVersion latestkeyboard_arrow_down\n\n- [2.21.0 (latest)](/python/docs/reference/datastore/latest/google.cloud.datastore.entity.Entity)\n- [2.20.2](/python/docs/reference/datastore/2.20.2/google.cloud.datastore.entity.Entity)\n- [2.19.0](/python/docs/reference/datastore/2.19.0/google.cloud.datastore.entity.Entity)\n- [2.18.0](/python/docs/reference/datastore/2.18.0/google.cloud.datastore.entity.Entity)\n- [2.17.0](/python/docs/reference/datastore/2.17.0/google.cloud.datastore.entity.Entity)\n- [2.16.1](/python/docs/reference/datastore/2.16.1/google.cloud.datastore.entity.Entity)\n- [2.15.2](/python/docs/reference/datastore/2.15.2/google.cloud.datastore.entity.Entity)\n- [2.14.0](/python/docs/reference/datastore/2.14.0/google.cloud.datastore.entity.Entity)\n- [2.13.2](/python/docs/reference/datastore/2.13.2/google.cloud.datastore.entity.Entity)\n- [2.12.0](/python/docs/reference/datastore/2.12.0/google.cloud.datastore.entity.Entity)\n- [2.11.1](/python/docs/reference/datastore/2.11.1/google.cloud.datastore.entity.Entity)\n- [2.10.0](/python/docs/reference/datastore/2.10.0/google.cloud.datastore.entity.Entity)\n- [2.9.0](/python/docs/reference/datastore/2.9.0/google.cloud.datastore.entity.Entity)\n- [2.8.3](/python/docs/reference/datastore/2.8.3/google.cloud.datastore.entity.Entity)\n- [2.7.2](/python/docs/reference/datastore/2.7.2/google.cloud.datastore.entity.Entity)\n- [2.6.2](/python/docs/reference/datastore/2.6.2/google.cloud.datastore.entity.Entity)\n- [2.5.1](/python/docs/reference/datastore/2.5.1/google.cloud.datastore.entity.Entity)\n- [2.4.0](/python/docs/reference/datastore/2.4.0/google.cloud.datastore.entity.Entity)\n- [2.3.0](/python/docs/reference/datastore/2.3.0/google.cloud.datastore.entity.Entity)\n- [2.2.0](/python/docs/reference/datastore/2.2.0/google.cloud.datastore.entity.Entity)\n- [2.1.6](/python/docs/reference/datastore/2.1.6/google.cloud.datastore.entity.Entity)\n- [2.0.1](/python/docs/reference/datastore/2.0.1/google.cloud.datastore.entity.Entity)\n- [1.15.5](/python/docs/reference/datastore/1.15.5/google.cloud.datastore.entity.Entity)\n- [1.14.0](/python/docs/reference/datastore/1.14.0/google.cloud.datastore.entity.Entity)\n- [1.13.2](/python/docs/reference/datastore/1.13.2/google.cloud.datastore.entity.Entity)\n- [1.12.0](/python/docs/reference/datastore/1.12.0/google.cloud.datastore.entity.Entity)\n- [1.11.0](/python/docs/reference/datastore/1.11.0/google.cloud.datastore.entity.Entity)\n- [1.10.0](/python/docs/reference/datastore/1.10.0/google.cloud.datastore.entity.Entity)\n- [1.9.0](/python/docs/reference/datastore/1.9.0/google.cloud.datastore.entity.Entity) \n\n Entity(key=None, exclude_from_indexes=())\n\nEntities are akin to rows in a relational database\n\nAn entity storing the actual instance of data.\n\nEach entity is officially represented with a\nxref_Key, however it is possible that\nyou might create an entity with only a partial key (that is, a key\nwith a kind, and possibly a parent, but without an ID). In such a\ncase, the datastore service will automatically assign an ID to the\npartial key.\n\nEntities in this API act like dictionaries with extras built in that\nallow you to delete or persist the data stored on the entity.\n\nEntities are mutable and act like a subclass of a dictionary.\nThis means you could take an existing entity and change the key\nto duplicate the object.\n\nUse xref_get to retrieve an\nexisting entity:\n\n.. testsetup:: entity-ctor \n\n import uuid\n\n from google.cloud import https://cloud.google.com/python/docs/reference/datastore/latest/\n\n unique = str(uuid.uuid4())[0:8]\n client = https://cloud.google.com/python/docs/reference/datastore/latest/.https://cloud.google.com/python/docs/reference/datastore/latest/google.cloud.datastore.client.Client.html(namespace='ns{}'.format(unique))\n\n entity = https://cloud.google.com/python/docs/reference/datastore/latest/.https://cloud.google.com/python/docs/reference/datastore/latest/google.cloud.datastore.entity.Entity.html(client.https://cloud.google.com/python/docs/reference/datastore/latest/google.cloud.datastore.client.Client.html#google_cloud_datastore_client_Client_key('EntityKind', 1234))\n entity['property'] = 'value'\n client.https://cloud.google.com/python/docs/reference/datastore/latest/google.cloud.datastore.client.Client.html#google_cloud_datastore_client_Client_put(entity)\n\n.. doctest:: entity-ctor \n\n \u003e\u003e\u003e key = client.key('EntityKind', 1234)\n \u003e\u003e\u003e client.get(key)\n \u003cEntity('EntityKind', 1234) {'property': 'value'}\u003e\n\nYou can the set values on the entity just like you would on any\nother dictionary.\n\n.. doctest:: entity-ctor \n\n \u003e\u003e\u003e entity['age'] = 20\n \u003e\u003e\u003e entity['name'] = 'JJ'\n\n.. testcleanup:: entity-ctor \n\n client.delete(entity.key)\n\nHowever, not all types are allowed as a value for a Google Cloud Datastore\nentity. The following basic types are supported by the API:\n\n- `datetime.datetime`\n- xref_Key\n- `bool`\n- `float`\n- `int` (as well as `long` in Python 2)\n- `unicode` (called `str` in Python 3)\n- `bytes` (called `str` in Python 2)\n- xref_GeoPoint\n- :data:`None`\n\nIn addition, three container types are supported:\n\n- `list`\n- xref_Entity\n- `dict` (will just be treated like an `Entity` without a key or `exclude_from_indexes`)\n\nEach entry in a list must be one of the value types (basic or\ncontainer) and each value in an\nxref_Entity must as well. In\nthis case an xref_Entity **as a\ncontainer** acts as a `dict`, but also has the special annotations\nof `key` and `exclude_from_indexes`.\n\nAnd you can treat an entity like a regular Python dictionary:\n\n.. testsetup:: entity-dict \n\n from google.cloud import https://cloud.google.com/python/docs/reference/datastore/latest/\n\n entity = https://cloud.google.com/python/docs/reference/datastore/latest/.https://cloud.google.com/python/docs/reference/datastore/latest/google.cloud.datastore.entity.Entity.html()\n entity['age'] = 20\n entity['name'] = 'JJ'\n\n.. doctest:: entity-dict \n\n \u003e\u003e\u003e sorted(entity.keys())\n ['age', 'name']\n \u003e\u003e\u003e sorted(entity.items())\n [('age', 20), ('name', 'JJ')]\n\n| **Note:** When saving an entity to the backend, values which are \"text\" (`unicode` in Python2, `str` in Python3) will be saved using the 'text_value' field, after being encoded to UTF-8. When retrieved from the back-end, such values will be decoded to \"text\" again. Values which are \"bytes\" (`str` in Python2, `bytes` in Python3), will be saved using the 'blob_value' field, without any decoding / encoding step.\n\nProperties\n----------\n\n### id\n\n\u003cbr /\u003e\n\nGet the ID of the current entity.\n| **Note:** This relies entirely on the [Key](/python/docs/reference/datastore/latest/google.cloud.datastore.key.Key) set on the entity. That means that we're not storing the ID of the entity at all, just the properties and a pointer to a Key which knows its ID.\n|\n|\n| \u003cbr /\u003e\n|\n\u003cbr /\u003e\n\n### kind\n\n\u003cbr /\u003e\n\nGet the kind of the current entity.\n| **Note:** This relies entirely on the [Key](/python/docs/reference/datastore/latest/google.cloud.datastore.key.Key) set on the entity. That means that we're not storing the kind of the entity at all, just the properties and a pointer to a Key which knows its Kind.\n|\n|\n| \u003cbr /\u003e\n|\n\u003cbr /\u003e\n\nMethods\n-------\n\n### __eq__\n\n __eq__(other)\n\nCompare two entities for equality.\n\nEntities compare equal if their keys compare equal and their\nproperties compare equal.\n\n### __ne__\n\n __ne__(other)\n\nCompare two entities for inequality.\n\nEntities compare equal if their keys compare equal and their\nproperties compare equal."]]