Properties Reference¶

Property descriptors for the Google Cloud Datastore ODM.

This module provides the base Property descriptor and its type-specific subclasses (e.g., StringProperty, IntegerProperty, etc.). These classes handle data coercion, validation, default values, and Datastore schema mapping.

`Property(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Base descriptor for model properties.

This class implements the Python descriptor protocol (__get__, __set__, __delete__) to manage state on the underlying Model instances.

Responsibilities

Required checks and default value assignment
Python type enforcement (via subclasses)
Inline property-level validators
Routing to Model-level @field_validator methods
Datastore aliasing (name)
Indexing control (indexed)
List support (repeated)
Value restriction (choices)

Initialize a new Property.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	The Datastore column name. If omitted, defaults to the Python attribute name. Useful for mapping legacy database fields.	`None`
`indexed`	`bool`	Whether the Datastore should index this property. Set to False for massive text blocks to save space and reduce write costs. If not sure leave this True and pass unindexed properties on the fly during put() operations.	`True`
`repeated`	`bool`	If True, this property expects an iterable (list/set/tuple) and stores it as an array in Datastore. Defaults to False.	`False`
`required`	`bool`	If True, assigning `None` or an empty list (if repeated) will raise a ValueError. Defaults to False.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one (e.g., `default=list` or `default=datetime.now`).	`None`
`choices`	`list \| None`	An optional list of allowed values. Assignments not in this list will raise a ValueError.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions. Each function should accept a single value, validate/mutate it, and return it.	`None`

Raises:

Type	Description
`TypeError`	If any provided validator is not callable.

Examples:

status = StringProperty(
    default="draft",
    choices=["draft", "published"],
    name="legacy_status_col"
)
tags = StringProperty(repeated=True)

`validate(instance, value)` ¶

Validate and process a value (or list of values) for this property.

Handles None assignments, required checks, and maps the validation pipeline over elements if the property is repeated.

Parameters:

Name	Type	Description	Default
`instance`	`Model`	The underlying model instance.	required
`value`	`Any`	The assigned value (or iterable if repeated).	required

Raises:

Type	Description
`ValueError`	If the property is required but None/empty is provided.
`TypeError`	If a repeated property is assigned a non-iterable.

Returns:

Name	Type	Description
`Any`	`Any`	The fully validated value or list of validated values.

`serialize_value(value)` ¶

Convert the Python value into a JSON-safe primitive.

By default, this is a simple pass-through. Subclasses containing complex types (e.g. datetimes, bytes, Datastore keys) must override this.

`in_(values)` ¶

Generates an 'IN' query filter.

`not_in_(values)` ¶

Generates a 'NOT IN' query filter.

`KeyProperty(kind=None, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that enforces Datastore Key values.

This property acts as a foreign key to create relationships between entities. It can optionally be restricted to only accept keys of a specific entity kind.

Examples:

class Post(Model):
    # Restrict to keys of the 'Author' kind
    author_key = KeyProperty(kind="Author")

Initialize a new KeyProperty.

Parameters:

Name	Type	Description	Default
`kind`	`str \| Any \| None`	A string or Model class to restrict the allowed keys. If provided, assigning a key of a different kind will raise a ValueError.	`None`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool`	Whether the Datastore should index this property.	`True`
`repeated`	`bool`	If True, expects an iterable of keys.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`expected_kind` `property` ¶

Resolve the expected kind string from a string or Model class.

`StringProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that strictly enforces string values.

Examples:

class User(Model):
    username = StringProperty(required=True)

`TextProperty(compressed=False, *, name=None, indexed=False, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: StringProperty

A Datastore property for large strings.

Unlike StringProperty, this is strictly unindexed to bypass Datastore's 1500-byte limit. It also supports optional zlib compression for saving space.

Examples:

class Article(Model):
    # Automatically compress large text blocks
    body = TextProperty(compressed=True)

Initialize a new TextProperty.

Parameters:

Name	Type	Description	Default
`compressed`	`bool`	If True, automatically compress the text string using zlib.	`False`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool \| None`	Text properties cannot be indexed. This must be False or None.	`False`
`repeated`	`bool`	If True, expects an iterable of strings.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`IntegerProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that strictly enforces integer values.

Note: Python evaluates booleans as subclasses of integers (isinstance(True, int) is True). This descriptor explicitly rejects boolean values to maintain strict Datastore type integrity.

Examples:

class Product(Model):
    stock_count = IntegerProperty(default=0)

`BooleanProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that strictly enforces boolean values.

Examples:

class User(Model):
    is_active = BooleanProperty(default=True)

`FloatProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that enforces floating-point values.

This property safely accepts both float and int types, automatically casting int assignments to float to prevent strict type errors over simple math (e.g. assigning 1 instead of 1.0).

Examples:

class Sensor(Model):
    temperature = FloatProperty()

`BytesProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property for raw byte data.

This replaces the legacy BlobProperty. It is by default unindexed to bypass Datastore's 1500-byte limit for indexed properties. It also supports optional zlib compression to reduce storage costs for large binary payloads.

Examples:

class FileUpload(Model):
    # Automatically compress large binary files before saving
    raw_data = BytesProperty(compressed=True)

Initialize a new BytesProperty.

Parameters:

Name	Type	Description	Default
`compressed`	`bool`	If True, automatically compress the bytes using zlib.	`False`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool \| None`	Defaults to False in order to bypass 1500-byte limits.	`None`
`repeated`	`bool`	If True, expects an iterable of byte objects.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`PickleProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property for storing arbitrary Python objects.

Uses Python's built-in pickle module to serialize objects into bytes. It is by default unindexed to bypass Datastore's 1500-byte limit.

WARNING: The pickle module is not secure. Only unpickle data you trust. For standard data structures, JsonProperty is highly recommended instead.

Examples:

class GameState(Model):
    # Store complex Python objects natively
    inventory_set = PickleProperty(compressed=True)

Initialize a new PickleProperty.

Parameters:

Name	Type	Description	Default
`compressed`	`bool`	If True, automatically compress the pickled bytes using zlib.	`False`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool \| None`	Defaults to False in order to bypass 1500-byte limits.	`None`
`repeated`	`bool`	If True, expects an iterable of Python objects.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`StructuredProperty(model_class, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property, Generic[TStruct]

A Datastore property that embeds another Model instance.

Maps directly to Datastore's EmbeddedEntity data type. Nested models are fully hydrated, validated, and natively queryable using dot-notation.

Examples:

class Address(Model):
    city = StringProperty()

class Profile(Model):
    # Embed the Address model completely
    location = StructuredProperty(Address)

# Natively query embedded properties
Profile.query().filter(Profile.location.city == "London")

Initialize a new StructuredProperty.

Parameters:

Name	Type	Description	Default
`model_class`	`type[Model]`	The class of the ODM Model to embed.	required
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool`	Whether the Datastore should index this property.	`True`
`repeated`	`bool`	If True, expects an iterable of Model instances.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`serialize_value(value)` ¶

Serialize the nested model into a JSON-safe dictionary.

`JsonProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that enforces JSON-serializable structures.

This property defaults to indexed=False to prevent Datastore index explosions on arbitrarily nested dynamic keys. It also supports optional zlib compression to drastically reduce storage costs for massive JSON payloads.

Examples:

class AuditLog(Model):
    # Store complex nested dictionaries securely
    payload = JsonProperty(compressed=True)

Initialize a new JsonProperty.

Parameters:

Name	Type	Description	Default
`compressed`	`bool`	If True, automatically compress the JSON string using zlib.	`False`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool \| None`	Defaults to False in order to prevent index explosions.	`None`
`repeated`	`bool`	If True, expects an iterable of JSON-serializable objects.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`DateTimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that enforces datetime values.

If tzinfo is None, this expects naive datetimes and assumes UTC. If tzinfo is provided, it converts Datastore's UTC datetimes to that timezone.

Examples:

class Article(Model):
    # Automatically populate on first save
    created_at = DateTimeProperty(auto_now_add=True, tzinfo=datetime.timezone.utc)

    # Automatically update on every save
    updated_at = DateTimeProperty(auto_now=True, tzinfo=datetime.timezone.utc)

Initialize a new DateTimeProperty.

Parameters:

Name	Type	Description	Default
`auto_now`	`bool`	If True, automatically set to the current time on every put().	`False`
`auto_now_add`	`bool`	If True, automatically set to the current time when first created.	`False`
`tzinfo`	`tzinfo \| None`	The timezone to convert Datastore's UTC to/from.	`None`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool`	Whether the Datastore should index this property. Defaults to True.	`True`
`repeated`	`bool`	If True, expects an iterable of datetimes.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`DateProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: DateTimeProperty

A Datastore property that enforces date values.

Datastore only supports Datetimes, so this property casts to a Datetime at midnight UTC before saving, and casts back to a Date when reading.

Examples:

class Employee(Model):
    hire_date = DateProperty()

Initialize a new DateProperty.

Parameters:

Name	Type	Description	Default
`auto_now`	`bool`	If True, automatically set to the current date on every put().	`False`
`auto_now_add`	`bool`	If True, automatically set to the current date when first created.	`False`
`tzinfo`	`tzinfo \| None`	The timezone used to evaluate the "current" date.	`None`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool`	Whether the Datastore should index this property.	`True`
`repeated`	`bool`	If True, expects an iterable of dates.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`TimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: DateTimeProperty

A Datastore property that enforces time values.

Datastore only supports Datetimes, so this property casts to a Datetime on Jan 1, 1970 UTC before saving, and casts back to a Time when reading.

Initialize a new TimeProperty.

Parameters:

Name	Type	Description	Default
`auto_now`	`bool`	If True, automatically set to the current time on every put().	`False`
`auto_now_add`	`bool`	If True, automatically set to the current time when first created.	`False`
`tzinfo`	`tzinfo \| None`	The timezone used to evaluate the "current" time.	`None`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool`	Whether the Datastore should index this property.	`True`
`repeated`	`bool`	If True, expects an iterable of times.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`GeoPtProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property for storing geographical coordinates (latitude and longitude).

Accepts a native google.cloud.datastore.helpers.GeoPoint.

Examples:

from google.cloud.datastore.helpers import GeoPoint

class Landmark(Model):
    location = GeoPtProperty()

eiffel_tower = Landmark(location=GeoPoint(48.8584, 2.2945))

`GenericProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: Property

A Datastore property that can store any natively supported type dynamically.

Acts as a schema-less field allowing you to store strings, integers, floats, booleans, datetimes, lists, or dictionaries without strict type enforcement.

Supports compressed=True, which is only effective for bytes values and forces indexed=False.

Examples:

class Webhook(Model):
    # Accept whatever payload the external service sends
    payload = GenericProperty()

Initialize a new GenericProperty.

Parameters:

Name	Type	Description	Default
`compressed`	`bool`	If True, compresses `bytes` values (forces `indexed=False`).	`False`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool \| None`	Whether the Datastore should index this property. Defaults to True unless compressed=True.	`None`
`repeated`	`bool`	If True, expects an iterable of dynamic values.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

`serialize_value(value)` ¶

Recursively serialize dynamic data into a JSON-safe structure.

Because GenericProperty is schema-less, it must check for non-JSON-safe primitives (like datetimes or bytes) on the fly and cast them.

`ComputedProperty(func=None, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

Bases: GenericProperty

A Property whose value is dynamically computed by a developer-supplied function.

Cannot be assigned manually. The value is automatically evaluated when the property is accessed, or immediately before saving to the Datastore.

Examples:

class Article(Model):
    content = TextProperty()

    @ComputedProperty
    def length(self):
        return len(self.content) if self.content else 0

Initialize a new ComputedProperty.

Parameters:

Name	Type	Description	Default
`func`	`Callable \| None`	The function to compute the property's value.	`None`
`name`	`str \| None`	The Datastore column name. Defaults to Python attribute name.	`None`
`indexed`	`bool`	Whether the Datastore should index this property.	`True`
`repeated`	`bool`	If True, expects an iterable.	`False`
`required`	`bool`	If True, assigning `None` will raise a ValueError.	`False`
`default`	`Any`	The default value or a zero-argument callable to generate one.	`None`
`choices`	`list \| None`	An optional list of allowed values.	`None`
`validators`	`list[Callable] \| None`	A list of custom validation functions.	`None`

Properties Reference¶

Property(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

validate(instance, value) ¶

serialize_value(value) ¶

in_(values) ¶

not_in_(values) ¶

KeyProperty(kind=None, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

expected_kind property ¶

StringProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

TextProperty(compressed=False, *, name=None, indexed=False, repeated=False, required=False, default=None, choices=None, validators=None) ¶

IntegerProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

BooleanProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

FloatProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

BytesProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None) ¶

PickleProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None) ¶

StructuredProperty(model_class, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

serialize_value(value) ¶

JsonProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None) ¶

DateTimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

DateProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

TimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

GeoPtProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

GenericProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None) ¶

serialize_value(value) ¶

ComputedProperty(func=None, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None) ¶

`Property(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`validate(instance, value)` ¶

`serialize_value(value)` ¶

`in_(values)` ¶

`not_in_(values)` ¶

`KeyProperty(kind=None, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`expected_kind` `property` ¶

`StringProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`TextProperty(compressed=False, *, name=None, indexed=False, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`IntegerProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`BooleanProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`FloatProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`BytesProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`PickleProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`StructuredProperty(model_class, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`serialize_value(value)` ¶

`JsonProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`DateTimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`DateProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`TimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`GeoPtProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`GenericProperty(compressed=False, *, name=None, indexed=None, repeated=False, required=False, default=None, choices=None, validators=None)` ¶

`serialize_value(value)` ¶

`ComputedProperty(func=None, *, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)` ¶