Polymorphic Models and Queries

Polymorphic models and queries.

The standard NDB Model class only supports ‘functional polymorphism’. That is, you can create a subclass of Model, and then subclass that class, as many generations as necessary, and those classes will share all the same properties and behaviors of their base classes. However, subclassing Model in this way gives each subclass its own kind. This means that it is not possible to do ‘polymorphic queries’. Building a query on a base class will only return entities whose kind matches that base class’s kind, and exclude entities that are instances of some subclass of that base class.

The PolyModel class defined here lets you create class hierarchies that support polymorphic queries. Simply subclass PolyModel instead of Model.

class google.cloud.ndb.polymodel.PolyModel(**kwargs)[source]

Bases: google.cloud.ndb.model.Model

Base class for class hierarchies supporting polymorphic queries.

Use this class to build hierarchies that can be queried based on their types.

Example:

Consider the following model hierarchy:

+------+
|Animal|
+------+
  |
  +-----------------+
  |                 |
+------+          +------+
|Canine|          |Feline|
+------+          +------+
  |                 |
  +-------+         +-------+
  |       |         |       |
+---+   +----+    +---+   +-------+
|Dog|   |Wolf|    |Cat|   |Panther|
+---+   +----+    +---+   +-------+

This class hierarchy has three levels. The first is the root class. All models in a single class hierarchy must inherit from this root. All models in the hierarchy are stored as the same kind as the root class. For example, Panther entities when stored to Cloud Datastore are of the kind Animal. Querying against the Animal kind will retrieve Cats, Dogs and Canines, for example, that match your query. Different classes stored in the root class kind are identified by their class key. When loaded from Cloud Datastore, it is mapped to the appropriate implementation class.

Polymorphic properties:

Properties that are defined in a given base class within a hierarchy are stored in Cloud Datastore for all subclasses only. So, if the Feline class had a property called whiskers, the Cat and Panther entities would also have whiskers, but not Animal, Canine, Dog or Wolf.

Polymorphic queries:

When written to Cloud Datastore, all polymorphic objects automatically have a property called class that you can query against. Using this property it is possible to easily write a query against any sub-hierarchy. For example, to fetch only Canine objects, including all Dogs and Wolves:

Canine.query()

The class property is not meant to be used by your code other than for queries. Since it is supposed to represent the real Python class it is intended to be hidden from view. Although if you feel the need, it is accessible as the class_ attribute.

Root class:

The root class is the class from which all other classes of the hierarchy inherits from. Each hierarchy has a single root class. A class is a root class if it is an immediate child of PolyModel. The subclasses of the root class are all the same kind as the root class. In other words:

Animal.kind() == Feline.kind() == Panther.kind() == 'Animal'

Note:

All classes in a given hierarchy must have unique names, since the class name is used to identify the appropriate subclass.

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

__ne__(other)

Implement self != other as not(self == other).

__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, database=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.

  • database (Optional[str]) – This parameter is ignored. Please set the database on the Client instead.

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, database: str = 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.

  • database (Optional[str]) – This parameter is ignored. Please set the database on the Client instead.

Returns

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

found.

Return type

tasklets.Future

classmethod get_or_insert(_name, *args, **kwargs)

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, *args, **kwargs)

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.

  • default_options (QueryOptions) – QueryOptions object.

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.