2.4. Documents instances¶
To create a new document object, create an instance of the relevant document class, providing values for its fields as its constructor keyword arguments. You may provide values for any of the fields on the document:
>>> page = Page(title="Test Page")
>>> page.title
'Test Page'
You may also assign values to the document’s fields using standard object attribute syntax:
>>> page.title = "Example Page"
>>> page.title
'Example Page'
2.4.1. Saving and deleting documents¶
MongoEngine tracks changes to documents to provide efficient saving. To save
the document to the database, call the save()
method.
If the document does not exist in the database, it will be created. If it does
already exist, then any changes will be updated atomically. For example:
>>> page = Page(title="Test Page")
>>> page.save() # Performs an insert
>>> page.title = "My Page"
>>> page.save() # Performs an atomic set on the title field.
Note
Changes to documents are tracked and on the whole perform set
operations.
list_field.push(0)
- sets the resulting listdel(list_field)
- unsets whole list
With lists its preferable to use Doc.update(push__list_field=0)
as
this stops the whole list being updated - stopping any race conditions.
See also
2.4.1.1. Pre save data validation and cleaning¶
MongoEngine allows you to create custom cleaning rules for your documents when
calling save()
. By providing a custom
clean()
method you can do any pre validation / data
cleaning.
This might be useful if you want to ensure a default value based on other document values for example:
class Essay(Document):
status = StringField(choices=('Published', 'Draft'), required=True)
pub_date = DateTimeField()
def clean(self):
"""Ensures that only published essays have a `pub_date` and
automatically sets the pub_date if published and not set"""
if self.status == 'Draft' and self.pub_date is not None:
msg = 'Draft entries should not have a publication date.'
raise ValidationError(msg)
# Set the pub_date for published items if not set.
if self.status == 'Published' and self.pub_date is None:
self.pub_date = datetime.now()
Note
Cleaning is only called if validation is turned on and when calling
save()
.
2.4.1.2. Cascading Saves¶
If your document contains ReferenceField
or
GenericReferenceField
objects, then by default the
save()
method will not save any changes to
those objects. If you want all references to also be saved also, noting each
save is a separate query, then passing cascade
as True
to the save method will cascade any saves.
2.4.2. Document IDs¶
Each document in the database has a unique id. This may be accessed through the
id
attribute on Document
objects. Usually, the id
will be generated automatically by the database server when the object is save,
meaning that you may only access the id
field once a document has been
saved:
>>> page = Page(title="Test Page")
>>> page.id
>>> page.save()
>>> page.id
ObjectId('123456789abcdef000000000')
Alternatively, you may define one of your own fields to be the document’s
“primary key” by providing primary_key=True
as a keyword argument to a
field’s constructor. Under the hood, MongoEngine will use this field as the
id
; in fact id
is actually aliased to your primary key field so
you may still use id
to access the primary key if you want:
>>> class User(Document):
... email = StringField(primary_key=True)
... name = StringField()
...
>>> bob = User(email='bob@example.com', name='Bob')
>>> bob.save()
>>> bob.id == bob.email == 'bob@example.com'
True
You can also access the document’s “primary key” using the pk
field; in
is an alias to id
:
>>> page = Page(title="Another Test Page")
>>> page.save()
>>> page.id == page.pk
Note
If you define your own primary key field, the field implicitly becomes
required, so a ValidationError
will be thrown if
you don’t provide it.