Model and Property¶

Model classes for datastore objects and properties for models.

A model class represents the structure of entities stored in the datastore. Applications define model classes to indicate the structure of their entities, then instantiate those model classes to create entities.

All model classes must inherit (directly or indirectly) from Model. Through the magic of metaclasses, straightforward assignments in the model class definition can be used to declare the model’s structure:

class Person(Model):
    name = StringProperty()
    age = IntegerProperty()

We can now create a Person entity and write it to Cloud Datastore:

person = Person(name='Arthur Dent', age=42)
key = person.put()

The return value from put() is a Key (see the documentation for ndb/key.py), which can be used to retrieve the same entity later:

person2 = key.get()
person2 == person  # Returns True

To update an entity, simply change its attributes and write it back (note that this doesn’t change the key):

person2.name = 'Arthur Philip Dent'
person2.put()

We can also delete an entity (by using the key):

key.delete()

The property definitions in the class body tell the system the names and the types of the fields to be stored in Cloud Datastore, whether they must be indexed, their default value, and more.

Many different Property types exist. Most are indexed by default, the exceptions are indicated in the list below:

StringProperty: a short text string, limited to at most 1500 bytes (when UTF-8 encoded from str to bytes).
TextProperty: an unlimited text string; unindexed.
BlobProperty: an unlimited byte string; unindexed.
IntegerProperty: a 64-bit signed integer.
FloatProperty: a double precision floating point number.
BooleanProperty: a bool value.
DateTimeProperty: a datetime object. Note: Datastore always uses UTC as the timezone.
DateProperty: a date object.
TimeProperty: a time object.
GeoPtProperty: a geographical location, i.e. (latitude, longitude).
KeyProperty: a Cloud Datastore Key value, optionally constrained to referring to a specific kind.
UserProperty: a User object (for backwards compatibility only)
StructuredProperty: a field that is itself structured like an entity; see below for more details.
LocalStructuredProperty: like StructuredProperty but the on-disk representation is an opaque blob; unindexed.
ComputedProperty: a property whose value is computed from other properties by a user-defined function. The property value is written to Cloud Datastore so that it can be used in queries, but the value from Cloud Datastore is not used when the entity is read back.
GenericProperty: a property whose type is not constrained; mostly used by the Expando class (see below) but also usable explicitly.
JsonProperty: a property whose value is any object that can be serialized using JSON; the value written to Cloud Datastore is a JSON representation of that object.
PickleProperty: a property whose value is any object that can be serialized using Python’s pickle protocol; the value written to the Cloud Datastore is the pickled representation of that object, using the highest available pickle protocol

Most Property classes have similar constructor signatures. They accept several optional keyword arguments:

name=<string>: the name used to store the property value in the datastore. Unlike the following options, this may also be given as a positional argument.
indexed=<bool>: indicates whether the property should be indexed (allowing queries on this property’s value).
repeated=<bool>: indicates that this property can have multiple values in the same entity.
write_empty_list<bool>: For repeated value properties, controls whether properties with no elements (the empty list) is written to Datastore. If true, written, if false, then nothing is written to Datastore.
required=<bool>: indicates that this property must be given a value.
default=<value>: a default value if no explicit value is given.
choices=<list of values>: a list or tuple of allowable values.
validator=<function>: a general-purpose validation function. It will be called with two arguments (prop, value) and should either return the validated value or raise an exception. It is also allowed for the function to modify the value, but the function should be idempotent. For example: a validator that returns value.strip() or value.lower() is fine, but one that returns value + ‘$’ is not).
verbose_name=<value>: A human readable name for this property. This human readable name can be used for html form labels.

The repeated and required/default options are mutually exclusive: a repeated property cannot be required nor can it specify a default value (the default is always an empty list and an empty list is always an allowed value), but a required property can have a default.

Some property types have additional arguments. Some property types do not support all options.

Repeated properties are always represented as Python lists; if there is only one value, the list has only one element. When a new list is assigned to a repeated property, all elements of the list are validated. Since it is also possible to mutate lists in place, repeated properties are re-validated before they are written to the datastore.

No validation happens when an entity is read from Cloud Datastore; however property values read that have the wrong type (e.g. a string value for an IntegerProperty) are ignored.

For non-repeated properties, None is always a possible value, and no validation is called when the value is set to None. However for required properties, writing the entity to Cloud Datastore requires the value to be something other than None (and valid).

The StructuredProperty is different from most other properties; it lets you define a sub-structure for your entities. The substructure itself is defined using a model class, and the attribute value is an instance of that model class. However, it is not stored in the datastore as a separate entity; instead, its attribute values are included in the parent entity using a naming convention (the name of the structured attribute followed by a dot followed by the name of the subattribute). For example:

class Address(Model):
  street = StringProperty()
  city = StringProperty()

class Person(Model):
  name = StringProperty()
  address = StructuredProperty(Address)

p = Person(name='Harry Potter',
           address=Address(street='4 Privet Drive',
           city='Little Whinging'))
k = p.put()

This would write a single ‘Person’ entity with three attributes (as you could verify using the Datastore Viewer in the Admin Console):

name = 'Harry Potter'
address.street = '4 Privet Drive'
address.city = 'Little Whinging'

Structured property types can be nested arbitrarily deep, but in a hierarchy of nested structured property types, only one level can have the repeated flag set. It is fine to have multiple structured properties referencing the same model class.

It is also fine to use the same model class both as a top-level entity class and as for a structured property; however, queries for the model class will only return the top-level entities.

The LocalStructuredProperty works similar to StructuredProperty on the Python side. For example:

class Address(Model):
    street = StringProperty()
    city = StringProperty()

class Person(Model):
    name = StringProperty()
    address = LocalStructuredProperty(Address)

p = Person(name='Harry Potter',
           address=Address(street='4 Privet Drive',
           city='Little Whinging'))
k = p.put()

However, the data written to Cloud Datastore is different; it writes a ‘Person’ entity with a ‘name’ attribute as before and a single ‘address’ attribute whose value is a blob which encodes the Address value (using the standard “protocol buffer” encoding).

The Model class offers basic query support. You can create a Query object by calling the query() class method. Iterating over a Query object returns the entities matching the query one at a time. Query objects are fully described in the documentation for query, but there is one handy shortcut that is only available through Model.query(): positional arguments are interpreted as filter expressions which are combined through an AND operator. For example:

Person.query(Person.name == 'Harry Potter', Person.age >= 11)

is equivalent to:

Person.query().filter(Person.name == 'Harry Potter', Person.age >= 11)

Keyword arguments passed to .query() are passed along to the Query() constructor.

It is possible to query for field values of structured properties. For example:

qry = Person.query(Person.address.city == 'London')

A number of top-level functions also live in this module:

get_multi() reads multiple entities at once.
put_multi() writes multiple entities at once.
delete_multi() deletes multiple entities at once.

All these have a corresponding *_async() variant as well. The *_multi_async() functions return a list of Futures.

There are many other interesting features. For example, Model subclasses may define pre-call and post-call hooks for most operations (get, put, delete, allocate_ids), and Property classes may be subclassed to suit various needs. Documentation for writing a Property subclass is in the docs for the Property class.

class google.cloud.ndb.model.BlobKey(blob_key)[source]¶

Bases: object

Key used to identify a blob in the blobstore.

Note

The blobstore was an early Google App Engine feature that later became Google Cloud Storage.

This class is a simple wrapper a bytes object. The bytes represent a key used internally by the Blobstore API to identify application blobs (i.e. Google Cloud Storage objects). The key corresponds to the entity name of the underlying object.

Parameters

blob_key (Optional[bytes]) – The key used for the blobstore.

Raises

BadValueError – If the blob_key exceeds 1500 bytes.
BadValueError – If the blob_key is not None or a bytes instance.

google.cloud.ndb.model.GeoPt¶: alias of google.cloud.datastore.helpers.GeoPoint

exception google.cloud.ndb.model.KindError[source]¶

Bases: google.cloud.ndb.exceptions.BadValueError

Raised when an implementation for a kind can’t be found.

May also be raised when the kind is not a byte string.

exception google.cloud.ndb.model.InvalidPropertyError[source]¶

Bases: google.cloud.ndb.exceptions.Error

Raised when a property is not applicable to a given use.

For example, a property must exist and be indexed to be used in a query’s projection or group by clause.

google.cloud.ndb.model.BadProjectionError¶

This alias for InvalidPropertyError is for legacy support.

alias of google.cloud.ndb.model.InvalidPropertyError

exception google.cloud.ndb.model.UnprojectedPropertyError[source]¶

Bases: google.cloud.ndb.exceptions.Error

Raised when getting a property value that’s not in the projection.

exception google.cloud.ndb.model.ReadonlyPropertyError[source]¶

Bases: google.cloud.ndb.exceptions.Error

Raised when attempting to set a property value that is read-only.

exception google.cloud.ndb.model.ComputedPropertyError[source]¶

Bases: google.cloud.ndb.model.ReadonlyPropertyError

Raised when attempting to set or delete a computed property.

exception google.cloud.ndb.model.UserNotFoundError[source]¶

Bases: google.cloud.ndb.exceptions.Error

No email argument was specified, and no user is logged in.

class google.cloud.ndb.model.IndexProperty[source]¶

Bases: object

Immutable object representing a single property in an index.

__eq__(other)[source]¶: Compare two index properties for equality.

__repr__()[source]¶: Return a string representation.

property direction¶

The direction in the index, asc or desc.

Type: str

property name¶

The property name being indexed.

Type: str

class google.cloud.ndb.model.Index[source]¶

Bases: object

Immutable object representing an index.

__eq__(other)[source]¶: Compare two indexes.

__repr__()[source]¶: Return a string representation.

property ancestor¶

Indicates if this is an ancestor index.

Type: bool

property kind¶

The kind being indexed.

Type: str

property properties¶

The properties being indexed.

Type: List[IndexProperty]

class google.cloud.ndb.model.IndexState[source]¶

Bases: object

Immutable object representing an index and its state.

__eq__(other)[source]¶: Compare two index states.

__repr__()[source]¶: Return a string representation.

property definition¶

The index corresponding to the tracked state.

Type: Index

property id¶

The index ID.

Type: int

property state¶

The index state.

Possible values are error, deleting, serving or building.

Type: str

class google.cloud.ndb.model.ModelAdapter[source]¶: Bases: object

google.cloud.ndb.model.make_connection(*args, **kwargs)[source]¶

class google.cloud.ndb.model.ModelAttribute[source]¶

Bases: object

Base for classes that implement a _fix_up() method.

class google.cloud.ndb.model.Property(name=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.ModelAttribute

A class describing a typed, persisted attribute of an entity.

Warning

This is not to be confused with Python’s @property built-in.

Note

This is just a base class; there are specific subclasses that describe properties of various types (and GenericProperty which describes a dynamically typed property).

The Property does not reserve any “public” names (i.e. names that don’t start with an underscore). This is intentional; the subclass StructuredProperty uses the public attribute namespace to refer to nested property names (this is essential for specifying queries on subproperties).

The IN() attribute is provided as an alias for _IN, but IN can be overridden if a subproperty has the same name.

The Property class and its predefined subclasses allow easy subclassing using composable (or stackable) validation and conversion APIs. These require some terminology definitions:

A user value is a value such as would be set and accessed by the application code using standard attributes on the entity.
A base value is a value such as would be serialized to and deserialized from Cloud Datastore.

A property will be a member of a Model and will be used to help store values in an entity (i.e. instance of a model subclass). The underlying stored values can be either user values or base values.

To interact with the composable conversion and validation API, a Property subclass can define

_to_base_type()
_from_base_type()
_validate()

These should not call their super() method, since the methods are meant to be composed. For example with composable validation:

class Positive(ndb.IntegerProperty):
    def _validate(self, value):
        if value < 1:
            raise ndb.exceptions.BadValueError("Non-positive", value)


class SingleDigit(Positive):
    def _validate(self, value):
        if value > 9:
            raise ndb.exceptions.BadValueError("Multi-digit", value)

neither _validate() method calls super(). Instead, when a SingleDigit property validates a value, it composes all validation calls in order:

SingleDigit._validate
Positive._validate
IntegerProperty._validate

The API supports “stacking” classes with ever more sophisticated user / base conversions:

the user to base conversion goes from more sophisticated to less sophisticated
the base to user conversion goes from less sophisticated to more sophisticated

For example, see the relationship between BlobProperty, TextProperty and StringProperty.

The validation API distinguishes between “lax” and “strict” user values. The set of lax values is a superset of the set of strict values. The _validate() method takes a lax value and if necessary converts it to a strict value. For example, an integer (lax) can be converted to a floating point (strict) value. This means that when setting the property value, lax values are accepted, while when getting the property value, only strict values will be returned. If no conversion is needed, _validate() may return None. If the argument is outside the set of accepted lax values, _validate() should raise an exception, preferably TypeError or BadValueError.

A class utilizing all three may resemble:

class WidgetProperty(ndb.Property):

    def _validate(self, value):
        # Lax user value to strict user value.
        if not isinstance(value, Widget):
            raise nbd.exceptions.BadValueError(value)

    def _to_base_type(self, value):
        # (Strict) user value to base value.
        if isinstance(value, Widget):
            return value.to_internal()

    def _from_base_type(self, value):
        # Base value to (strict) user value.'
        if not isinstance(value, _WidgetInternal):
            return Widget(value)

There are some things that _validate(), _to_base_type() and _from_base_type() do not need to handle:

None: They will not be called with None (and if they return None, this means that the value does not need conversion).
Repeated values: The infrastructure takes care of calling _from_base_type() or _to_base_type() for each list item in a repeated value.
Wrapping “base” values: The wrapping and unwrapping is taken care of by the infrastructure that calls the composable APIs.
Comparisons: The comparison operations call _to_base_type() on their operand.
Distinguishing between user and base values: the infrastructure guarantees that _from_base_type() will be called with an (unwrapped) base value, and that _to_base_type() will be called with a user value.
Returning the original value: if any of these return None, the original value is kept. (Returning a different value not equal to None will substitute the different value.)

Additionally, _prepare_for_put() can be used to integrate with datastore save hooks used by Model instances.

_prepare_for_put(entity)[source]¶

Allow this property to define a pre-put hook.

This base class implementation does nothing, but subclasses may provide hooks.

Parameters: entity (Model) – An entity with values.

Parameters

name (str) – The name of the property.
indexed (bool) – Indicates if the value should be indexed.
repeated (bool) – Indicates if this property is repeated, i.e. contains multiple values.
required (bool) – Indicates if this property is required on the given model type.
default (Any) – The default value for this property.
choices (Iterable[Any]) – A container of allowed values for this property.
validator (Callable[[Property, Any], bool]) – A validator to be used to check values.
verbose_name (str) – A longer, user-friendly name for this property.
write_empty_list (bool) – Indicates if an empty list should be written to the datastore.

IN(value)¶

Used to check if a property value is contained in a set of values.

For example:

Employee.query(Employee.rank.IN([4, 5, 6]))

__delete__(entity)[source]¶

Descriptor protocol: delete the value from the entity.

Parameters: entity (Model) – An entity to delete a value from.

__eq__(value)[source]¶: FilterNode: Represents the = comparison.

__ge__(value)[source]¶: FilterNode: Represents the >= comparison.

__get__(entity, unused_cls=None)[source]¶

Descriptor protocol: get the value from the entity.

Parameters

entity (Model) – An entity to get a value from.
unused_cls (type) – The class that owns this instance.

__gt__(value)[source]¶: FilterNode: Represents the > comparison.

__le__(value)[source]¶: FilterNode: Represents the <= comparison.

__lt__(value)[source]¶: FilterNode: Represents the < comparison.

__ne__(value)[source]¶: FilterNode: Represents the != comparison.

__neg__()[source]¶

Return a descending sort order on this property.

For example:

Employee.query().order(-Employee.rank)

__pos__()[source]¶

Return an ascending sort order on this property.

Note that this is redundant but provided for consistency with __neg__(). For example, the following two are equivalent:

Employee.query().order(+Employee.rank)
Employee.query().order(Employee.rank)

__repr__()[source]¶

Return a compact unambiguous string representation of a property.

This cycles through all stored attributes and displays the ones that differ from the default values.

__set__(entity, value)[source]¶

Descriptor protocol: set the value on the entity.

Parameters

entity (Model) – An entity to set a value on.
value (Any) – The value to set.

class google.cloud.ndb.model.ModelKey[source]¶

Bases: google.cloud.ndb.model.Property

Special property to store a special “key” for a Model.

This is intended to be used as a pseudo-Property on each Model subclass. It is not intended for other usage in application code.

It allows key-only queries to be done for a given kind.

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (Key) – The value to check.
Returns: The passed-in value.
Return type: Key

class google.cloud.ndb.model.BooleanProperty(name=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains values of type bool.

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (bool) – The value to check.
Returns: The passed-in value.
Return type: bool
Raises: BadValueError – If value is not a bool.

class google.cloud.ndb.model.IntegerProperty(name=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains values of type integer.

Note

If a value is a bool, it will be coerced to 0 (for False) or 1 (for True).

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (Union[int, bool]) – The value to check.
Returns: The passed-in value.
Return type: int
Raises: BadValueError – If value is not an int or convertible to one.

class google.cloud.ndb.model.FloatProperty(name=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains values of type float.

Note

If a value is a bool or int, it will be coerced to a floating point value.

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (Union[float, int, bool]) – The value to check.
Returns: The passed-in value, possibly converted to a float.
Return type: float
Raises: BadValueError – If value is not a float or convertible to one.

class google.cloud.ndb.model.BlobProperty(name=None, compressed=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains values that are byte strings.

Note

Unlike most property types, a BlobProperty is not indexed by default.

_to_base_type(value)[source]¶

Convert a value to the “base” value type for this property.

Parameters: value (bytes) – The value to be converted.
Returns: The converted value. If the current property is compressed, this will return a wrapped version of the compressed value. Otherwise, it will return None to indicate that the value didn’t need to be converted.
Return type: Optional[bytes]

_from_base_type(value)[source]¶

Convert a value from the “base” value type for this property.

Parameters: value (bytes) – The value to be converted.
Returns: The converted value. If the current property is a (wrapped) compressed value, this will unwrap the value and return the decompressed form. Otherwise, it will return None to indicate that the value didn’t need to be unwrapped and decompressed.
Return type: Optional[bytes]

_validate(value)[source]¶

Validate a value before setting it.

Parameters

value (bytes) – The value to check.

Raises

BadValueError – If value is not a bytes.
BadValueError – If the current property is indexed but the value exceeds the maximum length (1500 bytes).

Parameters

name (str) – The name of the property.
compressed (bool) – Indicates if the value should be compressed (via zlib).
indexed (bool) – Indicates if the value should be indexed.
repeated (bool) – Indicates if this property is repeated, i.e. contains multiple values.
required (bool) – Indicates if this property is required on the given model type.
default (bytes) – The default value for this property.
choices (Iterable[bytes]) – A container of allowed values for this property.
validator (Callable[[Property, Any], bool]) – A validator to be used to check values.
verbose_name (str) – A longer, user-friendly name for this property.
write_empty_list (bool) – Indicates if an empty list should be written to the datastore.

Raises

NotImplementedError – If the property is both compressed and indexed.

class google.cloud.ndb.model.TextProperty(*args, **kwargs)[source]¶

Bases: google.cloud.ndb.model.Property

An unindexed property that contains UTF-8 encoded text values.

A TextProperty is intended for values of unlimited length, hence is not indexed. Previously, a TextProperty could be indexed via:

class Item(ndb.Model):
    description = ndb.TextProperty(indexed=True)
    ...

but this usage is no longer supported. If indexed text is desired, a StringProperty should be used instead.

_to_base_type(value)[source]¶

Convert a value to the “base” value type for this property.

Parameters: value (Union[bytes, str]) – The value to be converted.
Returns: The converted value. If value is a bytes, this will return the UTF-8 decoded str for it. Otherwise, it will return None.
Return type: Optional[str]

_from_base_type(value)[source]¶

Convert a value from the “base” value type for this property.

Note

Older versions of ndb could write non-UTF-8 TEXT properties. This means that if value is bytes, but is not a valid UTF-8 encoded string, it can’t (necessarily) be rejected. But, _validate() now rejects such values, so it’s not possible to write new non-UTF-8 TEXT properties.

Parameters: value (Union[bytes, str]) – The value to be converted.
Returns: The converted value. If value is a a valid UTF-8 encoded bytes string, this will return the decoded str corresponding to it. Otherwise, it will return None.
Return type: Optional[str]

_validate(value)[source]¶

Validate a value before setting it.

Parameters

value (Union[bytes, str]) – The value to check.

Raises

BadValueError – If value is bytes, but is not a valid UTF-8 encoded string.
BadValueError – If value is neither bytes nor str.
BadValueError – If the current property is indexed but the UTF-8 encoded value exceeds the maximum length (1500 bytes).

Raises: NotImplementedError – If indexed=True is provided.

class google.cloud.ndb.model.StringProperty(*args, **kwargs)[source]¶

Bases: google.cloud.ndb.model.TextProperty

An indexed property that contains UTF-8 encoded text values.

This is nearly identical to TextProperty, but is indexed. Values must be at most 1500 bytes (when UTF-8 encoded from str to bytes).

Raises: NotImplementedError – If indexed=False is provided.

class google.cloud.ndb.model.GeoPtProperty(name=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains GeoPt values.

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (GeoPoint) – The value to check.
Raises: BadValueError – If value is not a GeoPt.

class google.cloud.ndb.model.PickleProperty(name=None, compressed=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.BlobProperty

A property that contains values that are pickle-able.

Note

Unlike most property types, a PickleProperty is not indexed by default.

This will use pickle.dumps() with the highest available pickle protocol to convert to bytes and pickle.loads() to convert from bytes. The base value stored in the datastore will be the pickled bytes.

_to_base_type(value)[source]¶

Convert a value to the “base” value type for this property.

Parameters: value (Any) – The value to be converted.
Returns: The pickled value.
Return type: bytes

_from_base_type(value)[source]¶

Convert a value from the “base” value type for this property.

Parameters: value (bytes) – The value to be converted.
Returns: The unpickled value.
Return type: Any

class google.cloud.ndb.model.JsonProperty(name=None, compressed=None, json_type=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.BlobProperty

A property that contains JSON-encodable values.

Note

Unlike most property types, a JsonProperty is not indexed by default.

_to_base_type(value)[source]¶

Convert a value to the “base” value type for this property.

Parameters: value (Any) – The value to be converted.
Returns: The value, JSON encoded as an ASCII byte string.
Return type: bytes

_from_base_type(value)[source]¶

Convert a value from the “base” value type for this property.

Parameters: value (bytes) – The value to be converted.
Returns: The value (ASCII bytes or string) loaded as JSON.
Return type: Any

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (Any) – The value to check.
Raises: TypeError – If the current property has a JSON type set and value is not an instance of that type.

Parameters

name (str) – The name of the property.
compressed (bool) – Indicates if the value should be compressed (via zlib).
json_type (type) – The expected type of values that this property can hold. If None, any type is allowed.
indexed (bool) – Indicates if the value should be indexed.
repeated (bool) – Indicates if this property is repeated, i.e. contains multiple values.
required (bool) – Indicates if this property is required on the given model type.
default (Any) – The default value for this property.
choices (Iterable[Any]) – A container of allowed values for this property.
validator (Callable[[Property, Any], bool]) – A validator to be used to check values.
verbose_name (str) – A longer, user-friendly name for this property.
write_empty_list (bool) – Indicates if an empty list should be written to the datastore.

class google.cloud.ndb.model.User(email=None, _auth_domain=None, _user_id=None)[source]¶

Bases: object

Provides the email address, nickname, and ID for a Google Accounts user.

Note

This class is a port of google.appengine.api.users.User. In the (legacy) Google App Engine standard environment, this constructor relied on several environment variables to provide a fallback for inputs. In particular:

AUTH_DOMAIN for the _auth_domain argument
USER_EMAIL for the email argument
USER_ID for the _user_id argument
FEDERATED_IDENTITY for the (now removed) federated_identity argument
FEDERATED_PROVIDER for the (now removed) federated_provider argument

However in the gVisor Google App Engine runtime (e.g. Python 3.7), none of these environment variables will be populated.

Note

Previous versions of the Google Cloud Datastore API had an explicit UserValue field. However, the google.datastore.v1 API returns previously stored user values as an Entity with the meaning set to ENTITY_USER=20.

Warning

The federated_identity and federated_provider are decommissioned and have been removed from the constructor. Additionally _strict_mode has been removed from the constructor and the federated_identity() and federated_provider() methods have been removed from this class.

Parameters

email (str) – The user’s email address.
_auth_domain (str) – The auth domain for the current application.
_user_id (str) – The user ID.

Raises

ValueError – If the _auth_domain is not passed in.
UserNotFoundError – If email is empty.

add_to_entity(entity, name)[source]¶

Add the user value to a datastore entity.

Note

This assumes, but does not check, that name is not already set on entity or in the meanings of entity.

Parameters

entity (Entity) – An entity that contains a user value as the field name.
name (str) – The name of the field containing this user value.

auth_domain()[source]¶

Obtains the user’s authentication domain.

Returns: The authentication domain. This method is internal and should not be used by client applications.
Return type: str

email()[source]¶: Returns the user’s email address.

nickname()[source]¶

The nickname for this user.

A nickname is a human-readable string that uniquely identifies a Google user with respect to this application, akin to a username. For some users, this nickname is an email address or part of the email address.

Returns: The nickname of the user.
Return type: str

classmethod read_from_entity(entity, name)[source]¶

Convert the user value to a datastore entity.

Parameters

entity (Entity) – An entity that contains a user value as the field name.
name (str) – The name of the field containing this user value.

Raises

ValueError – If the stored meaning for the name field is not equal to ENTITY_USER=20.
ValueError – If the value stored in the meanings for entity is not the actual stored value under name.

user_id()[source]¶

Obtains the user ID of the user.

Returns: A permanent unique identifying string or None. If the email address was set explicitly, this will return None.
Return type: Optional[str]

class google.cloud.ndb.model.UserProperty(name=None, auto_current_user=None, auto_current_user_add=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains User values.

Warning

This exists for backwards compatibility with existing Cloud Datastore schemas only; storing User objects directly in Cloud Datastore is not recommended.

Warning

The auto_current_user and auto_current_user_add arguments are no longer supported.

Note

On Google App Engine standard, after saving a User the user ID would automatically be populated by the datastore, even if it wasn’t set in the User value being stored. For example:

>>> class Simple(ndb.Model):
...     u = ndb.UserProperty()
...
>>> entity = Simple(u=users.User("user@example.com"))
>>> entity.u.user_id() is None
True
>>>
>>> entity.put()
>>> # Reload without the cached values
>>> entity = entity.key.get(use_cache=False,
...     use_global_cache=False)
>>> entity.u.user_id()
'...9174...'

However in the gVisor Google App Engine runtime (e.g. Python 3.7), this will behave differently. The user ID will only be stored if it is manually set in the User instance, either by the running application or by retrieving a stored User that already has a user ID set.

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (User) – The value to check.
Raises: BadValueError – If value is not a User.

_prepare_for_put(entity)[source]¶

Pre-put hook

This is a no-op. In previous versions of ndb, this method populated the value based on auto_current_user or auto_current_user_add, but these flags have been disabled.

Parameters: entity (Model) – An entity with values.

Parameters

name (str) – The name of the property.
auto_current_user (bool) – Deprecated flag. When supported, if this flag was set to True, the property value would be set to the currently signed-in user whenever the model instance is stored in the datastore, overwriting the property’s previous value. This was useful for tracking which user modifies a model instance.
auto_current_user_add (bool) – Deprecated flag. When supported, if this flag was set to True, the property value would be set to the currently signed-in user he first time the model instance is stored in the datastore, unless the property has already been assigned a value. This was useful for tracking which user creates a model instance, which may not be the same user that modifies it later.
indexed (bool) – Indicates if the value should be indexed.
repeated (bool) – Indicates if this property is repeated, i.e. contains multiple values.
required (bool) – Indicates if this property is required on the given model type.
default (bytes) – The default value for this property.
choices (Iterable[bytes]) – A container of allowed values for this property.
validator (Callable[[Property, Any], bool]) – A validator to be used to check values.
verbose_name (str) – A longer, user-friendly name for this property.
write_empty_list (bool) – Indicates if an empty list should be written to the datastore.

Raises

NotImplementedError – If auto_current_user is provided.
NotImplementedError – If auto_current_user_add is provided.

class google.cloud.ndb.model.KeyProperty(name=None, kind=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains Key values.

The constructor for KeyProperty allows at most two positional arguments. Any usage of None as a positional argument will be ignored. Any of the following signatures are allowed:

>>> name = "my_value"
>>> ndb.KeyProperty(name)
KeyProperty('my_value')
>>> ndb.KeyProperty(SimpleModel)
KeyProperty(kind='SimpleModel')
>>> ndb.KeyProperty(name, SimpleModel)
KeyProperty('my_value', kind='SimpleModel')
>>> ndb.KeyProperty(SimpleModel, name)
KeyProperty('my_value', kind='SimpleModel')

The type of the positional arguments will be used to determine their purpose: a string argument is assumed to be the name and a type argument is assumed to be the kind (and checked that the type is a subclass of Model).

_validate(value)[source]¶

Validate a value before setting it.

Parameters

value (Key) – The value to check.

Raises

BadValueError – If value is not a Key.
BadValueError – If value is a partial Key (i.e. it has no name or ID set).
BadValueError – If the current property has an associated kind and value does not match that kind.

Parameters

name (str) – The name of the property.
kind (Union[type, str]) – The (optional) kind to be stored. If provided as a positional argument, this must be a subclass of Model otherwise the kind name is sufficient.
indexed (bool) – Indicates if the value should be indexed.
repeated (bool) – Indicates if this property is repeated, i.e. contains multiple values.
required (bool) – Indicates if this property is required on the given model type.
default (Key) – The default value for this property.
choices (Iterable[Key]) – A container of allowed values for this property.
validator (Callable[[Property, Key], bool]) – A validator to be used to check values.
verbose_name (str) – A longer, user-friendly name for this property.
write_empty_list (bool) – Indicates if an empty list should be written to the datastore.

class google.cloud.ndb.model.BlobKeyProperty(name=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property containing BlobKey values.

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (BlobKey) – The value to check.
Raises: BadValueError – If value is not a BlobKey.

class google.cloud.ndb.model.DateTimeProperty(name=None, auto_now=None, auto_now_add=None, tzinfo=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.Property

A property that contains datetime values.

If tzinfo is not set, this property expects “naive” datetime stamps, i.e. no timezone can be set. Furthermore, the assumption is that naive datetime stamps represent UTC.

If tzinfo is set, timestamps will be stored as UTC and converted back to the timezone set by tzinfo when reading values back out.

Note

Unlike Django, auto_now_add can be overridden by setting the value before writing the entity. And unlike the legacy google.appengine.ext.db, auto_now does not supply a default value. Also unlike legacy db, when the entity is written, the property values are updated to match what was written. Finally, beware that this also updates the value in the in-process cache, and that auto_now_add may interact weirdly with transaction retries (a retry of a property with auto_now_add set will reuse the value that was set on the first try).

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (datetime) – The value to check.
Raises: BadValueError – If value is not a datetime.

_prepare_for_put(entity)[source]¶

Sets the current timestamp when “auto” is set.

If one of the following scenarios occur

auto_now=True
auto_now_add=True and the entity doesn’t have a value set

then this hook will run before the entity is put() into the datastore.

Parameters: entity (Model) – An entity with values.

Parameters

name (str) – The name of the property.
auto_now (bool) – Indicates that the property should be set to the current datetime when an entity is created and whenever it is updated.
auto_now_add (bool) – Indicates that the property should be set to the current datetime when an entity is created.
tzinfo (Optional[datetime.tzinfo]) – If set, values read from Datastore will be converted to this timezone. Otherwise, values will be returned as naive datetime objects with an implied UTC timezone.
indexed (bool) – Indicates if the value should be indexed.
repeated (bool) – Indicates if this property is repeated, i.e. contains multiple values.
required (bool) – Indicates if this property is required on the given model type.
default (datetime) – The default value for this property.
choices (Iterable[datetime]) – A container of allowed values for this property.
validator (Callable[[Property, Any], bool]) – A validator to be used to check values.
verbose_name (str) – A longer, user-friendly name for this property.
write_empty_list (bool) – Indicates if an empty list should be written to the datastore.

Raises

ValueError – If repeated=True and auto_now=True.
ValueError – If repeated=True and auto_now_add=True.

class google.cloud.ndb.model.DateProperty(name=None, auto_now=None, auto_now_add=None, tzinfo=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.DateTimeProperty

A property that contains date values.

_to_base_type(value)[source]¶

Convert a value to the “base” value type for this property.

Parameters: value (date) – The value to be converted.
Returns: The converted value: a datetime object with the time set to 00:00.
Return type: datetime
Raises: TypeError – If value is not a date.

_from_base_type(value)[source]¶

Convert a value from the “base” value type for this property.

Parameters: value (datetime) – The value to be converted.
Returns: The converted value: the date that value occurs on.
Return type: date

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (date) – The value to check.
Raises: BadValueError – If value is not a date.

class google.cloud.ndb.model.TimeProperty(name=None, auto_now=None, auto_now_add=None, tzinfo=None, indexed=None, repeated=None, required=None, default=None, choices=None, validator=None, verbose_name=None, write_empty_list=None)[source]¶

Bases: google.cloud.ndb.model.DateTimeProperty

A property that contains time values.

_to_base_type(value)[source]¶

Convert a value to the “base” value type for this property.

Parameters: value (time) – The value to be converted.
Returns: The converted value: a datetime object with the date set to 1970-01-01.
Return type: datetime
Raises: TypeError – If value is not a time.

_from_base_type(value)[source]¶

Convert a value from the “base” value type for this property.

Parameters: value (datetime) – The value to be converted.
Returns: The converted value: the time that value occurs at.
Return type: time

_validate(value)[source]¶

Validate a value before setting it.

Parameters: value (time) – The value to check.
Raises: BadValueError – If value is not a time.

class google.cloud.ndb.model.StructuredProperty(model_class, name=None, **kwargs)[source]¶

Bases: google.cloud.ndb.model.Property

A Property whose value is itself an entity.

The values of the sub-entity are indexed and can be queried.

IN(value)¶

For the in comparison operator.

The in operator cannot be overloaded in the way we want to, so we define a method. For example:

Employee.query(Employee.rank.IN([4, 5, 6]))

Note that the method is called _IN() but may normally be invoked as IN(); _IN() is provided for the case that a StructuredProperty refers to a model that has a property named IN.

Parameters

value (Iterable[Any]) – The set of values that the property value must be contained in.

Returns

A node corresponding to the desired in filter.

If value is empty, this will return a FalseNode
If len(value) == 1, this will return a FilterNode
Otherwise, this will return a DisjunctionNode

Return type

Union[DisjunctionNode, FilterNode, FalseNode]

Raises

BadFilterError – If the current property is not indexed.
BadArgumentError – If value is not a basic container (list, tuple, set or frozenset).

__getattr__(attrname)[source]¶: Dynamically get a subproperty.

class google.cloud.ndb.model.LocalStructuredProperty(model_class, **kwargs)[source]¶

Bases: google.cloud.ndb.model.BlobProperty

A property that contains ndb.Model value.

Note

Unlike most property types, a LocalStructuredProperty is not indexed.

_to_base_type(value)[source]¶

Convert a value to the “base” value type for this property. :param value: The given class value to be converted.

Returns: bytes
Raises: TypeError – If value is not the correct Model type.

_from_base_type(value)[source]¶

Convert a value from the “base” value type for this property. :param value: The value to be :type value: ~google.cloud.datastore.Entity or bytes :param converted.:

Returns: The converted value with given class.

_validate(value)[source]¶

Validate a value before setting it. :param value: The value to check.

Raises: BadValueError – If value is not a given class.

Parameters

model_class (type) – The class of the property. (Must be subclass of ndb.Model.)
name (str) – The name of the property.
compressed (bool) – Indicates if the value should be compressed (via zlib).
repeated (bool) – Indicates if this property is repeated, i.e. contains multiple values.
required (bool) – Indicates if this property is required on the given model type.
default (Any) – The default value for this property.
validator (Callable[[Property, Any], bool]) – A validator to be used to check values.
verbose_name (str) – A longer, user-friendly name for this property.
write_empty_list (bool) – Indicates if an empty list should be written to the datastore.

class google.cloud.ndb.model.GenericProperty(name=None, compressed=False, **kwargs)[source]¶

Bases: google.cloud.ndb.model.Property

A Property whose value can be (almost) any basic type. This is mainly used for Expando and for orphans (values present in Cloud Datastore but not represented in the Model subclass) but can also be used explicitly for properties with dynamically-typed values.

This supports compressed=True, which is only effective for str values (not for unicode), and implies indexed=False.

class google.cloud.ndb.model.ComputedProperty(func, name=None, indexed=None, repeated=None, verbose_name=None)[source]¶

Bases: google.cloud.ndb.model.GenericProperty

A Property whose value is determined by a user-supplied function. Computed properties cannot be set directly, but are instead generated by a function when required. They are useful to provide fields in Cloud Datastore that can be used for filtering or sorting without having to manually set the value in code - for example, sorting on the length of a BlobProperty, or using an equality filter to check if another field is not empty. ComputedProperty can be declared as a regular property, passing a function as the first argument, or it can be used as a decorator for the function that does the calculation.

Example:

>>> class DatastoreFile(ndb.Model):
...   name = ndb.model.StringProperty()
...   n_lower = ndb.model.ComputedProperty(lambda self: self.name.lower())
...
...   data = ndb.model.BlobProperty()
...
...   @ndb.model.ComputedProperty
...   def size(self):
...     return len(self.data)
...
...   def _compute_hash(self):
...     return hashlib.sha1(self.data).hexdigest()
...   hash = ndb.model.ComputedProperty(_compute_hash, name='sha1')

Constructor.

Args:

func: A function that takes one argument, the model instance, and: returns a calculated value.

class google.cloud.ndb.model.MetaModel(name, bases, classdict)[source]¶

Bases: type

Metaclass for Model.

This exists to fix up the properties – they need to know their name. For example, defining a model:

class Book(ndb.Model):
    pages = ndb.IntegerProperty()

the Book.pages property doesn’t have the name pages assigned. This is accomplished by calling the _fix_up_properties() method on the class itself.

class google.cloud.ndb.model.Model(**kwargs)[source]¶

Bases: object

A class describing Cloud Datastore entities.

Model instances are usually called entities. All model classes inheriting from Model automatically have MetaModel as their metaclass, so that the properties are fixed up properly after the class is defined.

Because of this, you cannot use the same Property object to describe multiple properties – you must create separate Property objects for each property. For example, this does not work:

reuse_prop = ndb.StringProperty()

class Wrong(ndb.Model):
    first = reuse_prop
    second = reuse_prop

instead each class attribute needs to be distinct:

class NotWrong(ndb.Model):
    first = ndb.StringProperty()
    second = ndb.StringProperty()

The “kind” for a given Model subclass is normally equal to the class name (exclusive of the module name or any other parent scope). To override the kind, define _get_kind(), as follows:

class MyModel(ndb.Model):
    @classmethod
    def _get_kind(cls):
        return "AnotherKind"

A newly constructed entity will not be persisted to Cloud Datastore without an explicit call to put().

User-defined properties can be passed to the constructor via keyword arguments:

>>> class MyModel(ndb.Model):
...     value = ndb.FloatProperty()
...     description = ndb.StringProperty()
...
>>> MyModel(value=7.34e22, description="Mass of the moon")
MyModel(description='Mass of the moon', value=7.34e+22)

In addition to user-defined properties, there are six accepted keyword arguments:

key
id
app
namespace
parent
projection

Of these, key is a public attribute on Model instances:

>>> entity1 = MyModel(id=11)
>>> entity1.key
Key('MyModel', 11)
>>> entity2 = MyModel(parent=entity1.key)
>>> entity2.key
Key('MyModel', 11, 'MyModel', None)
>>> entity3 = MyModel(key=ndb.Key(MyModel, "e-three"))
>>> entity3.key
Key('MyModel', 'e-three')

However, a user-defined property can be defined on the model with the same name as one of those keyword arguments. In this case, the user-defined property “wins”:

>>> class IDCollide(ndb.Model):
...     id = ndb.FloatProperty()
...
>>> entity = IDCollide(id=17)
>>> entity
IDCollide(id=17.0)
>>> entity.key is None
True

In such cases of argument “collision”, an underscore can be used as a keyword argument prefix:

>>> entity = IDCollide(id=17, _id=2009)
>>> entity
IDCollide(key=Key('IDCollide', 2009), id=17.0)

For the very special case of a property named key, the key attribute will no longer be the entity’s key but instead will be the property value. Instead, the entity’s key is accessible via _key:

>>> class KeyCollide(ndb.Model):
...     key = ndb.StringProperty()
...
>>> entity1 = KeyCollide(key="Take fork in road", id=987)
>>> entity1
KeyCollide(_key=Key('KeyCollide', 987), key='Take fork in road')
>>> entity1.key
'Take fork in road'
>>> entity1._key
Key('KeyCollide', 987)
>>>
>>> entity2 = KeyCollide(key="Go slow", _key=ndb.Key(KeyCollide, 1))
>>> entity2
KeyCollide(_key=Key('KeyCollide', 1), key='Go slow')

The constructor accepts keyword arguments based on the properties defined on model subclass. However, using keywords for nonexistent or non-Property class attributes will cause a failure:

>>> class Simple(ndb.Model):
...     marker = 1001
...     some_name = ndb.StringProperty()
...
>>> Simple(some_name="Value set here.")
Simple(some_name='Value set here.')
>>> Simple(some_name="Value set here.", marker=29)
Traceback (most recent call last):
  ...
TypeError: Cannot set non-property marker
>>> Simple(some_name="Value set here.", missing=29)
Traceback (most recent call last):
  ...
AttributeError: type object 'Simple' has no attribute 'missing'

classmethod _get_kind()[source]¶

str: Return the kind name for this class.

This defaults to cls.__name__; users may override this to give a class a different name when stored in Google Cloud Datastore than the name of the class.

Parameters

key (Key) – Datastore key for this entity (kind must match this model). If key is used, id and parent must be unset or None.
id (str) – Key ID for this model. If id is used, key must be None.
parent (Key) – The parent model or None for a top-level model. If parent is used, key must be None.
namespace (str) – Namespace for the entity key.
project (str) – Project ID for the entity key.
app (str) – DEPRECATED: Synonym for project.
kwargs (Dict[str, Any]) – Additional keyword arguments. These should map to properties of this model.

Raises

BadArgumentError – If the constructor is called with key and one of id, app, namespace or parent specified.

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

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.

__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

key¶

A special pseudo-property for key queries.

For example:

key = ndb.Key(MyModel, 808)
query = MyModel.query(MyModel.key > key)

will create a query for the reserved __key__ property.

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

Bases: google.cloud.ndb.model.Model

Model subclass to support dynamic Property names and types.

Sometimes the set of properties is not known ahead of time. In such cases you can use the Expando class. This is a Model subclass that creates properties on the fly, both upon assignment and when loading an entity from Cloud Datastore. For example:

>>> class SuperPerson(Expando):
        name = StringProperty()
        superpower = StringProperty()

>>> razorgirl = SuperPerson(name='Molly Millions',
                            superpower='bionic eyes, razorblade hands',
                            rasta_name='Steppin' Razor',
                            alt_name='Sally Shears')
>>> elastigirl = SuperPerson(name='Helen Parr',
                             superpower='stretchable body')
>>> elastigirl.max_stretch = 30  # Meters

>>> print(razorgirl._properties.keys())
    ['rasta_name', 'name', 'superpower', 'alt_name']
>>> print(elastigirl._properties)
    {'max_stretch': GenericProperty('max_stretch'),
     'name': StringProperty('name'),
     'superpower': StringProperty('superpower')}

Note: You can inspect the properties of an expando instance using the _properties attribute, as shown above. This property exists for plain Model instances too; it is just not as interesting for those.

google.cloud.ndb.model.get_multi_async(keys, 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)[source]¶

Fetches a sequence of keys.

Parameters

keys (Sequence[Key]) – A sequence of keys.
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.
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.
read_policy – DEPRECATED: Synonym for read_consistency.
force_writes (bool) – No longer supported.

Returns

List of futures.

Return type

List[Future]

google.cloud.ndb.model.get_multi(keys, 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)[source]¶

Fetches a sequence of keys.

Parameters

keys (Sequence[Key]) – A sequence of keys.
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.
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.
read_policy – DEPRECATED: Synonym for read_consistency.
force_writes (bool) – No longer supported.

Returns

List: containing the retrieved models or None where a key was not found.

Return type

List[Union[Model, None]]

google.cloud.ndb.model.put_multi_async(entities, 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)[source]¶

Stores a sequence of Model instances.

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.
entities (List[Model]) – A sequence of models to store.
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

List of futures.

Return type

List[Future]

google.cloud.ndb.model.put_multi(entities, 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)[source]¶

Stores a sequence of Model instances.

Parameters

entities (List[Model]) – A sequence of models to store.
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

A list with the stored keys.

Return type

List[Key]

google.cloud.ndb.model.delete_multi_async(keys, 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)[source]¶

Deletes a sequence of keys.

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.
keys (Sequence[Key]) – A sequence of keys.
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

List of futures.

Return type

List[Future]

google.cloud.ndb.model.delete_multi(keys, 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)[source]¶

Deletes a sequence of keys.

Parameters

keys (Sequence[Key]) – A sequence of keys.
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

A list whose items are all None, one per deleted: key.

Return type

List[None]

google.cloud.ndb.model.get_indexes_async(**options)[source]¶: Get a data structure representing the configured indexes.

google.cloud.ndb.model.get_indexes(**options)[source]¶: Get a data structure representing the configured indexes.

Model and Property¶

ndb

Navigation

Related Topics