Model Reference¶
Core model definitions for the Google Cloud Datastore ODM.
This module provides the base Model class, its metaclass, and validation
decorators required to define and interact with Datastore entities.
ModelMeta
¶
Bases: type
Metaclass responsible for parsing and collecting model configurations.
This runs once per model class at class creation time. It collects: - Property definitions - Model-level validators - Field-level validators - Datastore kind metadata and unindexed properties
Model(**kwargs)
¶
Base ODM model for Google Cloud Datastore.
Responsibilities: - Property validation and memory storage - Model-level and Field-level validation routing - Datastore persistence, mapping, and hydration - Lifecycle hook execution
Initialize a new model instance.
Properties can be passed as keyword arguments.
To explicitly set the Datastore key components, use the id, parent, or key kwargs.
To explicitly set routing metadata use project, database and namespace kwargs.
If your model has an actual property named after those keywords, prefix the routing kwargs with an underscore:
_id, _parent, _project, _database, _namespace
'key' is reserved and prohibited from being used as a property name but if you have an actual Datastore field called 'key' you can still access it by using the alias feature.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**kwargs
|
Any
|
Property values and Datastore routing metadata |
{}
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If a required property is missing. |
AttributeError
|
If an unknown property is provided. |
items()
¶
Return a view of the model's property names and values.
to_dict(include=None, exclude=None)
¶
Return a shallow dictionary representation of the model properties.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
include
|
Optional[List[str]]
|
If provided, only include these Python property names. |
None
|
exclude
|
Optional[List[str]]
|
If provided, exclude these Python property names. |
None
|
Returns:
| Type | Description |
|---|---|
Dict[str, Any]
|
Dict[str, Any]: A dictionary mapping Python property names to their current values. |
validate()
¶
Execute all model-level validators.
Property-level validation automatically occurs during standard assignment. This
method runs methods decorated with @model_validator to verify cross-property logic.
kind()
classmethod
¶
Return the Datastore kind associated with this model class.
get_schema(output_format='full')
classmethod
¶
Introspect the model's schema and property configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_format
|
str
|
The format of the returned schema. - "full" (default): Dict[str, dict] with JSON-serializable configurations. - "properties": List[Property] instances. - "named_properties": Dict[str, Property] instances. - "property_names": List[str] of Python property names. - "property_aliases": Dict[str, str] mapping Python names to Datastore names. |
'full'
|
Returns:
| Name | Type | Description |
|---|---|---|
Any |
Any
|
The schema in the requested format. |
allocate_ids(size, parent=None, project=None, database=None, namespace=None)
classmethod
¶
Allocate a batch of integer IDs for this model's kind.
Reserves a block of numeric IDs directly from the Datastore backend. This is useful for generating guaranteed-unique IDs before instantiating objects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
size
|
int
|
The number of IDs to allocate. Must be > 0. |
required |
parent
|
Optional[Key]
|
An optional ancestor key for the allocated IDs. |
None
|
project
|
Optional[str]
|
An optional project override. |
None
|
database
|
Optional[str]
|
An optional database override. |
None
|
namespace
|
Optional[str]
|
An optional namespace override. |
None
|
Returns:
| Type | Description |
|---|---|
List[Key]
|
List[datastore.Key]: A list of fully resolved keys with allocated integer IDs. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the requested size is 0 or negative. |
allocate_key(parent=None)
¶
Explicitly allocate a complete datastore key for this specific instance.
Triggers a single RPC call to the Datastore to fetch an integer ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent
|
Optional[Key]
|
An optional ancestor key. |
None
|
Returns:
| Type | Description |
|---|---|
Key
|
datastore.Key: The newly allocated, fully resolved Key. |
client(project=None, database=None)
classmethod
¶
Retrieve the configured active Datastore client.
key_from_id(identifier, parent=None, project=None, database=None, namespace=None)
classmethod
¶
Construct a datastore Key for this model's kind.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifier
|
Any
|
The string or integer ID for the entity. |
required |
parent
|
Optional[Key]
|
An optional ancestor key. |
None
|
project
|
Optional[str]
|
An optional project override. |
None
|
database
|
Optional[str]
|
An optional database override. |
None
|
namespace
|
Optional[str]
|
An optional namespace override. |
None
|
Returns:
| Type | Description |
|---|---|
Key
|
datastore.Key: The constructed Key object. |
populate(**kwargs)
¶
Update multiple properties at once.
Triggers all descriptor and field validators during assignment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**kwargs
|
Any
|
Property names and their new values. |
{}
|
Raises:
| Type | Description |
|---|---|
AttributeError
|
If an unknown property is provided. |
from_entity(entity, _is_projected=False)
classmethod
¶
get(key)
classmethod
¶
Fetch an entity by its Datastore key and hydrate a model instance.
Executes the _pre_get_hook before fetching, and the _post_get_hook
after hydration (even if the entity was not found).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
Key
|
The Google Cloud Datastore Key to fetch. |
required |
Returns:
| Type | Description |
|---|---|
Optional[Model]
|
Optional[Model]: The hydrated model instance, or None if not found. |
get_by_id(identifier, parent=None)
classmethod
¶
Fetch an entity by its string or integer ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
identifier
|
Any
|
The string name or integer ID. |
required |
parent
|
Optional[Key]
|
An optional ancestor key. |
None
|
Returns:
| Type | Description |
|---|---|
Optional[Model]
|
Optional[Model]: The hydrated model instance, or None if not found. |
query(project=None, database=None, namespace=None)
classmethod
¶
Create a Query object for this model's Datastore kind.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project
|
Optional[str]
|
An optional project override. |
None
|
database
|
Optional[str]
|
An optional database override. |
None
|
namespace
|
Optional[str]
|
An optional namespace override. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Query |
Query
|
An ODM Query object ready for filtering and fetching. |
put(exclude_from_indexes=None)
¶
Persist the model instance to the Datastore.
Triggers model-level validation and runs the _pre_put_hook and _post_put_hook.
If the instance does not have a complete key, Datastore auto-assigns an ID natively.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exclude_from_indexes
|
Optional[List[str]]
|
An optional list of Python property names (or even raw datastore fields) to dynamically exclude from Datastore indexes for this specific write. |
None
|
Returns:
| Type | Description |
|---|---|
Key
|
datastore.Key: The fully resolved Datastore Key. |
delete()
¶
Delete the model instance from the Datastore.
Executes the _pre_delete_hook before deletion and _post_delete_hook after.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the entity does not have a key. |
get_multi(keys)
classmethod
¶
Fetch multiple entities by their keys in a single RPC call.
Returns a list of model instances in the exact order of the provided keys.
Missing entities are represented as None in the returned list.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
keys
|
List[Key]
|
A list of Datastore keys to fetch. |
required |
Returns:
| Type | Description |
|---|---|
List[Optional[Model]]
|
List[Optional[Model]]: Hydrated instances or None, preserving input order. |
put_multi(instances)
classmethod
¶
Persist multiple model instances in a single batch Datastore operation.
This is significantly faster and more cost-effective than calling .put()
in a loop. Hooks (_pre_put_hook, _post_put_hook) and validators are
triggered for each instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instances
|
List[Model]
|
A list of unsaved or modified model instances. |
required |
Returns:
| Type | Description |
|---|---|
List[Key]
|
List[datastore.Key]: A list of keys corresponding to the saved entities. |
model_validator(func)
¶
Decorator used to mark a method as a model-level validator.
Model-level validators are executed when:
- Model.validate() is called explicitly
- Model.put() or Model.put_multi() is called
They are NOT executed during instantiation or property assignment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
func
|
Callable
|
The method to decorate. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Callable |
Callable
|
The decorated method. |
field_validator(field)
¶
Decorator used to mark a method as a field-level validator.
Field validators run automatically during property assignment,
instantiation, and when calling populate().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field
|
str
|
The name of the Python property this validates. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Callable |
Callable
|
A decorator for the specific validation method. |