Datastore Statistics

Models for accessing datastore usage statistics.

These entities cannot be created by users, but are populated in the application’s datastore by offline processes run by the Google Cloud team.

class google.cloud.ndb.stats.BaseKindStatistic(**kwargs)

Bases: google.cloud.ndb.stats.BaseStatistic

Base Statistic Model class for stats associated with kinds.

kind_name

the name of the kind associated with the statistic instance.

Type

str

entity_bytes

the number of bytes taken up to store the statistic in Cloud Datastore minus the cost of storing indices.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.BaseStatistic(**kwargs)

Bases: google.cloud.ndb.model.Model

Base Statistic Model class.

bytes

the total number of bytes taken up in Cloud Datastore for the statistic instance.

Type

int

count

attribute is the total number of occurrences of the statistic in Cloud Datastore.

Type

int

timestamp

the time the statistic instance was written to Cloud Datastore.

Type

datetime.datetime

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.GlobalStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseStatistic

An aggregate of all entities across the entire application.

This statistic only has a single instance in Cloud Datastore that contains the total number of entities stored and the total number of bytes they take up.

entity_bytes

the number of bytes taken up to store the statistic in Cloud Datastore minus the cost of storing indices.

Type

int

builtin_index_bytes

the number of bytes taken up to store built-in index entries.

Type

int

builtin_index_count

the number of built-in index entries.

Type

int

composite_index_bytes

the number of bytes taken up to store composite index entries.

Type

int

composite_index_count

the number of composite index entries.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.KindCompositeIndexStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseStatistic

Statistic on (kind, composite_index_id) tuples in Cloud Datastore.

There is an instance of the KindCompositeIndexStat for every unique (kind, composite_index_id) tuple in the application’s datastore indexes.

index_id

the id of the composite index associated with the statistic instance.

Type

int

kind_name

the name of the kind associated with the statistic instance.

Type

str

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.KindNonRootEntityStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseKindStatistic

Statistics of the number of non root entities in Cloud Datastore by Kind.

There is an instance of the KindNonRootEntityStat for every Kind that is in the application’s datastore that is a not a root entity. This stat contains statistics regarding these non root entity instances.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.KindPropertyNamePropertyTypeStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseKindStatistic

Statistic on (kind, property_name, property_type) tuples in Cloud Datastore.

There is an instance of the KindPropertyNamePropertyTypeStat for every (kind, property_name, property_type) tuple in the application’s datastore.

property_type

the property type associated with the statistic instance.

Type

str

property_name

the name of the property associated with the statistic instance.

Type

str

builtin_index_bytes

the number of bytes taken up to store built-in index entries

Type

int

builtin_index_count

the number of built-in index entries.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.KindPropertyNameStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseKindStatistic

Statistics on (kind, property_name) tuples in the app’s datastore.

There is an instance of the KindPropertyNameStat for every (kind, property_name) tuple in the application’s datastore.

property_name

the name of the property associated with the statistic instance.

Type

str

builtin_index_bytes

the number of bytes taken up to store built-in index entries.

Type

int

builtin_index_count

the number of built-in index entries.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.KindPropertyTypeStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseKindStatistic

Statistics on (kind, property_type) tuples in the app’s datastore.

There is an instance of the KindPropertyTypeStat for every (kind, property_type) tuple in the application’s datastore.

property_type

the property type associated with the statistic instance.

Type

str

builtin_index_bytes

the number of bytes taken up to store built-in index entries.

Type

int

builtin_index_count

the number of built-in index entries.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.KindRootEntityStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseKindStatistic

Statistics of the number of root entities in Cloud Datastore by Kind.

There is an instance of the KindRootEntityState for every Kind that is in the application’s datastore and has an instance that is a root entity. This stat contains statistics regarding these root entity instances.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.KindStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseKindStatistic

An aggregate of all entities at the granularity of their Kind.

There is an instance of the KindStat for every Kind that is in the application’s datastore. This stat contains per-Kind statistics.

builtin_index_bytes

the number of bytes taken up to store built-in index entries.

Type

int

builtin_index_count

the number of built-in index entries.

Type

int

composite_index_bytes

the number of bytes taken up to store composite index entries.

Type

int

composite_index_count

the number of composite index entries.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceGlobalStat(**kwargs)

Bases: google.cloud.ndb.stats.GlobalStat

GlobalStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceKindCompositeIndexStat(**kwargs)

Bases: google.cloud.ndb.stats.KindCompositeIndexStat

KindCompositeIndexStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceKindNonRootEntityStat(**kwargs)

Bases: google.cloud.ndb.stats.KindNonRootEntityStat

KindNonRootEntityStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceKindPropertyNamePropertyTypeStat(**kwargs)

Bases: google.cloud.ndb.stats.KindPropertyNamePropertyTypeStat

KindPropertyNamePropertyTypeStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceKindPropertyNameStat(**kwargs)

Bases: google.cloud.ndb.stats.KindPropertyNameStat

KindPropertyNameStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceKindPropertyTypeStat(**kwargs)

Bases: google.cloud.ndb.stats.KindPropertyTypeStat

KindPropertyTypeStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceKindRootEntityStat(**kwargs)

Bases: google.cloud.ndb.stats.KindRootEntityStat

KindRootEntityStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceKindStat(**kwargs)

Bases: google.cloud.ndb.stats.KindStat

KindStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespacePropertyTypeStat(**kwargs)

Bases: google.cloud.ndb.stats.PropertyTypeStat

PropertyTypeStat equivalent for a specific namespace.

These may be found in each specific namespace and represent stats for that particular namespace.

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.NamespaceStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseStatistic

An aggregate of all entities across an entire namespace.

This statistic has one instance per namespace. The key_name is the represented namespace. NamespaceStat entities will only be found in the namespace “” (empty string). It contains the total number of entities stored and the total number of bytes they take up.

subject_namespace

the namespace associated with the statistic instance.

Type

str

entity_bytes

the number of bytes taken up to store the statistic in Cloud Datastore minus the cost of storing indices.

Type

int

builtin_index_bytes

the number of bytes taken up to store builtin-in index entries.

Type

int

builtin_index_count

the number of built-in index entries.

Type

int

composite_index_bytes

the number of bytes taken up to store composite index entries.

Type

int

composite_index_count

the number of composite index entries.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.

class google.cloud.ndb.stats.PropertyTypeStat(**kwargs)

Bases: google.cloud.ndb.stats.BaseStatistic

An aggregate of all properties across the entire application by type.

There is an instance of the PropertyTypeStat for every property type (google.appengine.api.datastore_types._PROPERTY_TYPES) in use by the application in its datastore.

property_type

the property type associated with the statistic instance.

Type

str

entity_bytes

the number of bytes taken up to store the statistic in Cloud Datastore minus the cost of storing indices.

Type

int

builtin_index_bytes

the number of bytes taken up to store

Type

int

built-in index entries.

builtin_index_count

the number of built-in index entries.

Type

int

__eq__(other)

Compare two entities of the same class for equality.

__ge__(value)

The >= comparison is not well-defined.

__gt__(value)

The > comparison is not well-defined.

__hash__()

Not implemented hash function.

Raises

TypeError – Always, to emphasize that entities are mutable.

__le__(value)

The <= comparison is not well-defined.

__lt__(value)

The < comparison is not well-defined.

__repr__()

Return an unambiguous string representation of an entity.

classmethod allocate_ids(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Keys for the newly allocated IDs.

Return type

tuple(key.Key)

classmethod allocate_ids_async(size=None, max=None, parent=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Allocates a range of key IDs for this model class.

Parameters

• size (int) – Number of IDs to allocate. Must be specified.

• max (int) – Maximum ID to allocated. This feature is no longer supported. You must always specify size.

• parent (key.Key) – Parent key for which the IDs will be allocated.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Eventual result is tuple(key.Key): Keys for

the newly allocated IDs.

Return type

tasklets.Future

classmethod get_by_id(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This really just a shorthand for Key(cls, id, ....).get().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The retrieved entity, if one is found.

Return type

Optional[Model]

classmethod get_by_id_async(id, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None)

Get an instance of Model class by ID.

This is the asynchronous version of get_by_id().

Parameters

• id (Union[int, str]) – ID of the entity to load.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Optional[Model]: The retrieved entity, if one is

found.

Return type

tasklets.Future

classmethod get_or_insert(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

Will attempt to look up an entity with the given name and parent. If none is found a new entity will be created using the given name and parent, and passing any kw_model_args to the constructor the Model class.

If not already in a transaction, a new transaction will be created and this operation will be run in that transaction.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The entity that was either just retrieved or created.

Return type

Model

classmethod get_or_insert_async(name, parent=None, namespace=None, project=None, app=None, read_consistency=None, read_policy=None, transaction=None, retries=None, timeout=None, deadline=None, use_cache=None, use_global_cache=None, global_cache_timeout=None, use_datastore=None, use_memcache=None, memcache_timeout=None, max_memcache_items=None, force_writes=None, _options=None, **kw_model_args)

Transactionally retrieves an existing entity or creates a new one.

This is the asynchronous version of :meth:_get_or_insert.

Parameters

• name (str) – Name of the entity to load or create.

• parent (Optional[key.Key]) – Key for the parent of the entity to load.

• namespace (Optional[str]) – Namespace for the entity to load. If not passed, uses the client’s value.

• project (Optional[str]) – Project id for the entity to load. If not passed, uses the client’s value.

• app (str) – DEPRECATED: Synonym for project.

• **kw_model_args – Keyword arguments to pass to the constructor of the model class if an instance for the specified key name does not already exist. If an instance with the supplied name and parent already exists, these arguments will be discarded.

• read_consistency – Set this to ndb.EVENTUAL if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster. You can’t do this if using a transaction.

• read_policy – DEPRECATED: Synonym for read_consistency.

• transaction (bytes) – Any results returned will be consistent with the Datastore state represented by this transaction id. Defaults to the currently running transaction. Cannot be used with read_consistency=ndb.EVENTUAL.

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

Model: The entity that was either just retrieved

or created.

Return type

tasklets.Future

classmethod gql(query_string, *args, **kwargs)

Run a GQL query using this model as the FROM entity.

Parameters

• query_string (str) – The WHERE part of a GQL query (including the WHERE keyword).

• args – if present, used to call bind() on the query.

• kwargs – if present, used to call bind() on the query.

Returns

class:query.Query: A query instance.

has_complete_key()

Return whether this entity has a complete key.

Returns

:data:True if and only if entity has a key and that key

has a name or an id.

Return type

bool

populate(**kwargs)

Populate an instance from keyword arguments.

Each keyword argument will be used to set a corresponding property. Each keyword must refer to a valid property name. This is similar to passing keyword arguments to the Model constructor, except that no provision for key, id, or parent are made.

Parameters

**kwargs – Keyword arguments corresponding to properties of this model class.

put(**kwargs)

Synchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The key for the entity. This is always a complete key.

Return type

key.Key

put_async(**kwargs)

Asynchronously write this entity to Cloud Datastore.

If the operation creates or completes a key, the entity’s key attribute is set to the new, complete key.

Parameters

• retries (int) – Number of times to retry this operation in the case of transient server errors. Operation will potentially be tried up to retries + 1 times. Set to 0 to try operation only once, with no retries.

• timeout (float) – Override the gRPC timeout, in seconds.

• deadline (float) – DEPRECATED: Synonym for timeout.

• use_cache (bool) – Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.

• use_global_cache (bool) – Specifies whether to store entities in global cache; overrides global cache policy for this operation.

• use_datastore (bool) – Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.

• global_cache_timeout (int) – Maximum lifetime for entities in global cache; overrides global cache timeout policy for this operation.

• use_memcache (bool) – DEPRECATED: Synonym for use_global_cache.

• memcache_timeout (int) – DEPRECATED: Synonym for global_cache_timeout.

• max_memcache_items (int) – No longer supported.

• force_writes (bool) – No longer supported.

Returns

The eventual result will be the key for the

entity. This is always a complete key.

Return type

tasklets.Future

classmethod query(*filters, **kwargs)

Generate a query for this class.

Parameters

• *filters (query.FilterNode) – Filters to apply to this query.

• distinct (Optional[bool]) – Setting this to True is shorthand for setting distinct_on to projection.

• ancestor (key.Key) – Entities returned will be descendants of ancestor.

• order_by (list[Union[str, google.cloud.ndb.model.Property]]) – The model properties used to order query results.

• orders (list[Union[str, google.cloud.ndb.model.Property]]) – Deprecated. Synonym for order_by.

• project (str) – The project to perform the query in. Also known as the app, in Google App Engine. If not passed, uses the client’s value.

• app (str) – Deprecated. Synonym for project.

• namespace (str) – The namespace to which to restrict results. If not passed, uses the client’s value.

• projection (list[str]) – The fields to return as part of the query results.

• distinct_on (list[str]) – The field names used to group query results.

• group_by (list[str]) – Deprecated. Synonym for distinct_on.

to_dict(include=None, exclude=None)

Return a dict containing the entity’s property values.

Parameters

• include (Optional[Union[list, tuple, set]]) – Set of property names to include. Default is to include all names.

• exclude (Optional[Union[list, tuple, set]]) – Set of property names to exclude. Default is to not exclude any names.