Datastore Metadata¶

Models and helper functions for access to a project’s datastore metadata.

These entities cannot be created by users, but are created as the results of __namespace__, __kind__, __property__ and __entity_group__ metadata queries or gets.

A simplified API is also offered:

get_namespaces(): A list of namespace names.

get_kinds(): A list of kind names.

get_properties_of_kind(): A list of property names for the given kind name.

get_representations_of_kind(): A dict mapping property names to lists of representation ids.

get_kinds(), get_properties_of_kind(), get_representations_of_kind() implicitly apply to the current namespace.

get_namespaces(), get_kinds(), get_properties_of_kind(), get_representations_of_kind() have optional start and end arguments to limit the query to a range of names, such that start <= name < end.

google.cloud.ndb.metadata.get_entity_group_version(*args, **kwargs)[source]¶

Return the version of the entity group containing key.

Raises: class:google.cloud.ndb.exceptions.NoLongerImplementedError. Always. This method is not supported anymore.

google.cloud.ndb.metadata.get_kinds(start=None, end=None)[source]¶

Return all kinds in the specified range, for the current namespace.

Parameters

start (str) – only return kinds >= start if start is not None.
end (str) – only return kinds < end if end is not None.

Returns

Kind names between the (optional) start and end values.

Return type

List[str]

google.cloud.ndb.metadata.get_namespaces(start=None, end=None)[source]¶

Return all namespaces in the specified range.

Parameters

start (str) – only return namespaces >= start if start is not None.
end (str) – only return namespaces < end if end is not None.

Returns

Namespace names between the (optional) start and end values.

Return type

List[str]

google.cloud.ndb.metadata.get_properties_of_kind(kind, start=None, end=None)[source]¶

Return all properties of kind in the specified range.

NOTE: This function does not return unindexed properties.

Parameters

kind (str) – name of kind whose properties you want.
start (str) – only return properties >= start if start is not None.
end (str) – only return properties < end if end is not None.

Returns

Property names of kind between the (optional) start and end: values.

Return type

List[str]

google.cloud.ndb.metadata.get_representations_of_kind(kind, start=None, end=None)[source]¶

Return all representations of properties of kind in the specified range.

NOTE: This function does not return unindexed properties.

Parameters

kind – name of kind whose properties you want.
start – only return properties >= start if start is not None.
end – only return properties < end if end is not None.

Returns

map of property names to their list of representations.

Return type

dict

class google.cloud.ndb.metadata.EntityGroup[source]¶

Bases: object

Model for __entity_group__ metadata. No longer supported by datastore.

class google.cloud.ndb.metadata.Kind(**kwargs)[source]¶

Bases: google.cloud.ndb.metadata._BaseMetadata

Model for __kind__ metadata query results.

override to prevent instantiation

__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.

static __new__(cls, *args, **kwargs)¶: override to prevent instantiation

__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

classmethod key_for_kind(kind)[source]¶

Return the __kind__ key for kind.

Parameters: kind (str) – kind whose key is requested.
Returns: key for kind.
Return type: key.Key

classmethod key_to_kind(key)[source]¶

Return the kind specified by a given __kind__ key.

Parameters: key (key.Key) – key whose name is requested.
Returns: The kind specified by key.
Return type: str

property kind_name¶

Return the kind name specified by this entity’s key.

Returns: the kind name.
Return type: str

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.metadata.Namespace(**kwargs)[source]¶

Bases: google.cloud.ndb.metadata._BaseMetadata

Model for __namespace__ metadata query results.

override to prevent instantiation

__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.

static __new__(cls, *args, **kwargs)¶: override to prevent instantiation

__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

classmethod key_for_namespace(namespace)[source]¶

Return the Key for a namespace.

Parameters: namespace (str) – A string giving the namespace whose key is requested.
Returns: The Key for the namespace.
Return type: key.Key

classmethod key_to_namespace(key)[source]¶

Return the namespace specified by a given __namespace__ key.

Parameters: key (key.Key) – key whose name is requested.
Returns: The namespace specified by key.
Return type: str

property namespace_name¶

Return the namespace name specified by this entity’s key.

Returns: the namespace name.
Return type: str

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.metadata.Property(**kwargs)[source]¶

Bases: google.cloud.ndb.metadata._BaseMetadata

Model for __property__ metadata query results.

override to prevent instantiation

__eq__(other)[source]¶: Compare two entities of the same class for equality.

__ge__(value)[source]¶: The >= comparison is not well-defined.

__gt__(value)[source]¶: The > comparison is not well-defined.

__hash__()¶

Not implemented hash function.

Raises: TypeError – Always, to emphasize that entities are mutable.

__le__(value)[source]¶: The <= comparison is not well-defined.

__lt__(value)[source]¶: The < comparison is not well-defined.

static __new__(cls, *args, **kwargs)¶: override to prevent instantiation

__repr__()[source]¶: 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

classmethod key_for_kind(kind)[source]¶

Return the __property__ key for kind.

Parameters: kind (str) – kind whose key is requested.
Returns: The parent key for __property__ keys of kind.
Return type: key.Key

classmethod key_for_property(kind, property)[source]¶

Return the __property__ key for property of kind.

Parameters

kind (str) – kind whose key is requested.
property (str) – property whose key is requested.

Returns

The key for property of kind.

Return type

key.Key

classmethod key_to_kind(key)[source]¶

Return the kind specified by a given __property__ key.

Parameters: key (key.Key) – key whose kind name is requested.
Returns: The kind specified by key.
Return type: str

classmethod key_to_property(key)[source]¶

Return the property specified by a given __property__ key.

Parameters

key (key.Key) – key whose property name is requested.

Returns

property specified by key, or None if the key specified: only a kind.

Return type

str

property kind_name¶

Return the kind name specified by this entity’s key.

Returns: the kind name.
Return type: str

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.

property property_name¶

Return the property name specified by this entity’s key.

Returns: the property name.
Return type: str

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.

Datastore Metadata¶

ndb

Navigation

Related Topics