Stay organized with collections Save and categorize content based on your preferences.
Note: Developers building new applications are strongly encouraged to use the NDB Client Library, which has several benefits compared to this client library, such as automatic entity caching via the Memcache API. If you are currently using the older DB Client Library, read the DB to NDB Migration Guide
Class Model is the superclass for data model definitions.
Model is defined in the module google.appengine.ext.db.
An application defines a data model by defining a class that subclasses Model. Properties of the model are defined using class attributes and Property class instances. For example:
class Story(db.Model): title = db.StringProperty() body = db.TextProperty() created = db.DateTimeProperty(auto_now_add=True)
An application creates a new data entity by instantiating a subclass of the Model class. Properties of an entity can be assigned using attributes of the instance, or as keyword arguments to the constructor.
s = Story() s.title = "The Three Little Pigs" s = Story(title="The Three Little Pigs")
The name of the model sub-class is used as the name of the Datastore entity kind. The Datastore reserves all kind names that begin with two underscores (__). Model sub-classes must not use such names.
The names of the attributes are used as the names of the corresponding properties on an entity. Model instance attributes whose names begin with an underscore (_) are ignored, so your application can use such attributes to store data on a model instance that isn't saved to the Datastore.
The Datastore and the model class API impose several restrictions on property names and model instance attributes. See Disallowed Property Names for a complete description.
Every entity has a key, a unique identifier that represents the entity. The key can include an optional key name, a string unique across entities of the given kind. The entity's kind and key name can be used with the Key.from_path() and Model.get_by_key_name() methods to retrieve the entity.
An entity can also have an optional parent entity. Parent-child relationships form entity groups, which are used to control transactionality and data locality in the Datastore. An application creates a parent-child relationship between two entities by passing the parent entity to the child entity's constructor, as the parent argument.
The method Model.get_or_insert() can be used to retrieve an entity that may not exist, creating it in the Datastore if necessary:
keyname = "some_key" s = Story.get_or_insert(keyname, title="The Three Little Pigs")
Note: A model instance does not have a corresponding entity in the Datastore until it is written (put) for the first time, either explicitly or via Model.get_or_insert().
To create a dict that is a copy of a model instance's data, use the db.to_dict function.
The constructor for class Model is defined as follows:
The superclass for data model definitions.
During construction, each property's validate() method is called. Exceptions from such calls propagate to callers of this constructor.
Arguments
The key name for the entity. The name becomes part of the primary key. If None, a system-generated numeric ID is used for the key.
The value for key_name must not be of the form __*__.
The key name is stored as a Unicode string, with str values converted as ASCII text.
Calling put() on this object will overwrite any existing Datastore entity with the same key.
Additional keyword argument
The explicit Key instance for the entity. Cannot be used with key_name or parent. If None, falls back on the behavior for key_name and parent. Useful when using allocate_ids() to reserve numeric IDs for new entities.
The value for key must be a valid Key instance.
Calling put() on this object will overwrite any existing Datastore entity with the same key.
Class Model has the following class methods:
Retrieves the model instance (or instances) for the given key (or keys). The keys must represent entities of the model's kind. If a provided key is not of the correct kind, a KindError exception is raised.
This method is similar to the db.get() function, with additional type checking.
Arguments
Note: Global (non-ancestor) queries ignore this argument.
If keys consists of a single key (or its string representation), this method returns the model instance associated with the key if the key exists in the Datastore, otherwise None. If keys is a list, the return value is a corresponding list of model instances, with None values where no entity exists for a given key.
See also the db.get() function.
Retrieves the model instance (or instances) for the given numeric ID (or IDs).
Arguments
None (the default) if the requested entities do not have a parent. Multiple entities requested by one call must all have the same parent.
Note: Global (non-ancestor) queries ignore this argument.
If ids consists of a single numeric ID, this method returns the model instance associated with the ID if the ID exists in the Datastore, otherwise None. If ids is a list, the return value is a corresponding list of model instances, with None values where no entity exists for a given numeric ID.
Retrieves the model instance (or instances) for the given key name (or names).
Arguments
None (the default) if the requested entities do not have a parent. Multiple entities requested by one call must all have the same parent.
Note: Global (non-ancestor) queries ignore this argument.
If key_names consists of a single key name, this method returns the model instance associated with the name if the name exists in the Datastore, otherwise None. If key_names is a list, the return value is a corresponding list of model instances, with None values where no entity exists for a given key name.
Attempts to get the entity of the model's kind with the given key name. If it exists, get_or_insert() simply returns it. If it doesn't exist, a new entity with the given kind, name, and parameters in kwds is created, stored, and returned.
The get and subsequent (possible) put operations are wrapped in a transaction to ensure atomicity. Ths means that get_or_insert() will never overwrite an existing entity, and will insert a new entity if and only if no entity with the given kind and name exists. In other words, get_or_insert() is equivalent to the following Python code:
def txn(key_name, **kwds):
entity = Story.get_by_key_name(key_name, parent=kwds.get('parent'))
if entity is None:
entity = Story(key_name=key_name, **kwds)
entity.put()
return entity
def get_or_insert(key_name, **kwargs):
return db.run_in_transaction(txn, key_name, **kwargs)
get_or_insert('some key', title="The Three Little Pigs")
Arguments
parent argument is required if the desired entity has a parent.
Note: get_or_insert() does not accept a read_policy or deadline argument.
The method returns an instance of the model class that represents the requested entity, whether it existed or was created by the method. As with all Datastore operations, this method can raise a TransactionFailedError if the transaction could not be completed.
Returns a Query object that represents all entities for the kind corresponding to this model. Methods on the query object can apply filters and sort orders to the query before it is executed; see the Query class page for more information.
Arguments
Performs a GQL query over instances of this model.
Arguments
SELECT * FROM model (which is implied by using this class method).
GqlQuery() constructor.
GqlQuery() constructor.
s = Story.gql("WHERE title = :1", "Little Red Riding Hood")
s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")
The return value is a GqlQuery object, which can be used to access the results.
Model instances have the following methods:
Returns the Datastore Key for this model instance.
A model instance's key includes the instance's entity kind along with a unique identifier. The identifier may be either a key name string, assigned explicitly by the application when the instance is created, or an integer numeric ID, assigned automatically by App Engine when the instance is written (put) to the Datastore. Calling key() before the instance has been assigned an identifier raises a NotSavedError exception.
Stores the model instance in the Datastore. If the model instance is newly created and has never been stored, this method creates a new data entity in the Datastore. Otherwise, it updates the data entity with the current property values.
The method returns the key of the stored entity.
If the data could not be committed, raises a TransactionFailedError exception.
Arguments
Deletes the model instance from the Datastore. If the instance has never been written (put) to the Datastore, the delete raises a NotSavedError exception.
Arguments
Returns True if the model instance has been written (put) to the Datastore at least once.
This method only checks that the instance has been written to the Datastore at least once since it was created. It does not check whether the instance's properties have been updated since the last time it was written.
Returns a list of the names of all of the dynamic properties defined for this model instance. This only applies to instances of Expando classes. For non-Expando model instances, this returns an empty list.
Returns a model instance for the parent entity of this instance, or None if this instance does not have a parent.
Returns the Key of the parent entity of this instance, or None if this instance does not have a parent.
Returns an XML representation of the model instance.
Property values conform to the Atom and Data specifications.
The Datastore and its API impose several restrictions on names for entity properties and model instance attributes.
The Datastore reserves all property names that begin and end with two underscores (__*__). A Datastore entity cannot have a property with such a name.
The Python model API ignores all attributes on a Model or Expando class that begin with an underscore (_). Your application can use these attributes to associate data with the model objects that is not saved to the Datastore.
Lastly, the Python model API uses object attributes to define properties of a model, and by default the Datastore entity properties are named after the attributes. Because the Model class has several properties and methods for other purposes, those attributes cannot be used for properties in the Python API. For example, a Model cannot have a property accessed with the attribute key.
However, a property can specify a different name for the Datastore than the attribute name by giving a name argument to the property constructor. This allows the Datastore entity to have a property name similar to a reserved attribute in the Model class, and use a different attribute name in the class.
class MyModel(db.Model): obj_key = db.StringProperty(name="key")
The following attribute names are reserved by the Model class in the Python API:
allappcopydeleteentityentity_typefieldsfrom_entitygetgqlinstance_propertiesis_savedkeykey_namekindparentparent_keypropertiesputsetdefaultto_xmlupdateExcept as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-07 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["The `Model` class serves as the foundation for defining data models in applications, where each subclass represents a distinct data entity type."],["Data entities are created by instantiating `Model` subclasses, and properties are set using class attributes or keyword arguments during construction."],["Each entity has a unique key, which can include an optional key name, and entities can have parent-child relationships forming entity groups for managing data locality and transactions."],["Model class provides methods such as `get`, `get_by_id`, `get_by_key_name`, and `get_or_insert` to interact with data entities, enabling retrieval, creation, and ensuring unique entity creation."],["Model class offers various class and instance methods for tasks like querying data (`all`, `gql`), managing entities (`put`, `delete`), and checking entity states (`is_saved`), alongside features for handling entity properties, parent relationships, and XML representations."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4